<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
<p><br>
</p>
<div class="moz-cite-prefix">On 10/13/23 2:35 AM, Victor Nazarov
wrote:<br>
</div>
<blockquote type="cite" cite="mid:CAFOkWZaSqFfBc-6qL6KQRF9ZpnQoFaq4U4WTtV-WspTTPnYPVw@mail.gmail.com">
<div dir="ltr">Hello Javadoc developers,<br>
<br>
below is a slight rephrasing of my comment on reddit. <span class="gmail-_28nEhn86_R1ENZ59eAru8S">u/pavelrappo</span>
asked me to post it here, so that it can be better discussed.<br>
<br>
> Alternate transformers could convert more Markdown
constructs to HTML and JavaDoc tags.<br>
><br>
> ...<br>
><br>
> it would be possible to for there to be additional
transformers that a client may choose to use that are adequate
and sufficient for their needs.<br>
<br>
I feel like it would be better for the JEP to go into some
details about what kind of needs are these.<br>
As a javadoc user, I'm mainly concerned with authoring and
consuming javadoc documentation.<br>
Most of the usage of javadoc tools that I've personally seen was
mostly using default settings.<br>
So for me it is not clear why I would want to convert more
Markdown constructs to HTML and JavaDoc tags? Still it feels
like a very important part of the proposal that can affect other
pieces of the design.<br>
<br>
Another note is that the problem as stated in the JEP feels like
the same problem [described by Project Babylon](<a href="https://www.youtube.com/watch?v=xbk9_6XA_IY&t=889s" moz-do-not-send="true">https://www.youtube.com/watch?v=xbk9_6XA_IY&t=889s</a>),
different needs require different concentrations of syntactic
sugar. Low level optimizations require low level assembly code
(for javadoc this is probably HTML), some require more
high-level elements, like javadoc links and some require full
source code like original markdown. So maybe some ideas from
Project Babylon can be borrowed to create a multi-level "Javadoc
Model" that can be used in many different usage scenarios. <br>
<div>
<div><br>
</div>
<div>
<div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div>--<br>
</div>
<div>Victor Nazarov<br>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</blockquote>
<p><br>
</p>
<p>Victor,</p>
<p>Thank you for your interest.<br>
</p>
<p>1. Re: additional transformers.<br>
<br>
If you are satisfied with the default facilities provided by the
javadoc tool, then you may not be interested in an ability to
extend the functionality. Markdown is an imperfectly specified
language, and even leveraging the CommonMark spec, that is
something of a low bar. Some authors may have a compelling desire
to use additional well-known Markdown constructs -- such as
definition lists -- that will not be supported out of the box in
the work described in the JEP, and others may wish to extend the
features -- for example, the proposed support for tables does not
include support for table captions, which may be important for
authors wishing to generate accessible documentation.</p>
<p>2. Re: "Javadoc Model" and Babylon.<br>
<br>
I doubt that (m)any ideas from Project Babylon will apply,
although it is maybe way too soon to make any reliable prediction.
For now, the ability to specify alternate transformers should be
thought of as just an extension point, conceptually similar to
doclets and taglets.</p>
<p>-- Jon<br>
</p>
</body>
</html>