<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
Not scripts, but yes, the JDK uses pandoc to process their markdown
files. I'd prefer not to go down that route at this time. The docs
we are talking about can be rendered directly by the GitHub UI.<br>
<br>
-- Kevin<br>
<br>
<br>
<div class="moz-cite-prefix">On 5/12/2023 2:00 PM, Andy Goryachev
wrote:<br>
</div>
<blockquote type="cite" cite="mid:DM5PR1001MB2172064331B96AFC8865F746E5759@DM5PR1001MB2172.namprd10.prod.outlook.com">
<meta name="Generator" content="Microsoft Word 15 (filtered
medium)">
<style>@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}@font-face
{font-family:Verdana;
panose-1:2 11 6 4 3 5 4 4 2 4;}@font-face
{font-family:"Times New Roman \(Body CS\)";
panose-1:2 11 6 4 2 2 2 2 2 4;}p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
font-size:10.0pt;
font-family:"Calibri",sans-serif;}a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Courier New";
color:windowtext;}.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;
mso-ligatures:none;}div.WordSection1
{page:WordSection1;}</style>
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">Looks
like JDK uses a different flavor of markdown:<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">>
% Testing the JDK<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><a href="https://github.com/openjdk/jdk/blob/38838b344af00b32251b3141350ba4deb3962d6f/doc/testing.md?plain=1#LL1C18-L1C18" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/openjdk/jdk/blob/38838b344af00b32251b3141350ba4deb3962d6f/doc/testing.md?plain=1#LL1C18-L1C18</a><o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">Are
there any scripts that process the .md in jdk?<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New"">-andy<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Courier New""><o:p> </o:p></span></p>
<div style="border:none;border-top:solid #B5C4DF
1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal" style="margin-bottom:12.0pt"><b><span style="font-size:12.0pt;color:black">From:
</span></b><span style="font-size:12.0pt;color:black">openjfx-dev
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev-retn@openjdk.org"><openjfx-dev-retn@openjdk.org></a> on behalf of Marius
Hanl <a class="moz-txt-link-rfc2396E" href="mailto:mariushanl@web.de"><mariushanl@web.de></a><br>
<b>Date: </b>Friday, May 12, 2023 at 13:57<br>
<b>To: </b>John Hendrikx <a class="moz-txt-link-rfc2396E" href="mailto:john.hendrikx@gmail.com"><john.hendrikx@gmail.com></a><br>
<b>Cc: </b><a class="moz-txt-link-abbreviated" href="mailto:openjfx-dev@openjdk.org">openjfx-dev@openjdk.org</a>
<a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev@openjdk.org"><openjfx-dev@openjdk.org></a><br>
<b>Subject: </b>Aw: Developer documentation<o:p></o:p></span></p>
</div>
<div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif">I
like this idea as well. And I agree, especially the
snapping insight are good to document as this topic
really isn't trivial.<br>
I think we should stick to the official JDK, which also
follows the idea suggested by John.<br>
See here: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/tree/master/doc">https://github.com/openjdk/jdk/tree/master/doc</a><br>
-> There is a doc folder in the root directory.<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif"><br>
The JDK decided to always have a .md as well as a .html
file.<br>
See: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/blob/master/doc/building.md">https://github.com/openjdk/jdk/blob/master/doc/building.md</a><br>
And: <a class="moz-txt-link-freetext" href="https://github.com/openjdk/jdk/blob/master/doc/building.html">https://github.com/openjdk/jdk/blob/master/doc/building.html</a><o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif"><br>
+1 for the Markdown format (.md). IntelliJ is also able
to render this format.<o:p></o:p></span></p>
</div>
<div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif"> <o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif">--
Marius<o:p></o:p></span></p>
</div>
<div>
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif">
<o:p></o:p></span></p>
<div style="border:none;border-left:solid #C3D9E5
1.5pt;padding:0in 0in 0in
8.0pt;margin-left:7.5pt;margin-top:7.5pt;margin-right:3.75pt;margin-bottom:3.75pt;-webkit-nbsp-mode:
space;-webkit-line-break: after-white-space" name="quote">
<div style="margin-bottom:7.5pt">
<p class="MsoNormal"><b><span style="font-size:9.0pt;font-family:"Verdana",sans-serif">Gesendet:</span></b><span style="font-size:9.0pt;font-family:"Verdana",sans-serif"> Freitag,
12. Mai 2023 um 21:02 Uhr<br>
<b>Von:</b> "John Hendrikx"
<a class="moz-txt-link-rfc2396E" href="mailto:john.hendrikx@gmail.com"><john.hendrikx@gmail.com></a><br>
<b>An:</b> <a class="moz-txt-link-abbreviated" href="mailto:openjfx-dev@openjdk.org">openjfx-dev@openjdk.org</a><br>
<b>Betreff:</b> Developer documentation<o:p></o:p></span></p>
</div>
<div name="quoted-content">
<p class="MsoNormal"><span style="font-size:9.0pt;font-family:"Verdana",sans-serif">In
PR
<a href="https://github.com/openjdk/jfx/pull/910" target="_blank" moz-do-not-send="true" class="moz-txt-link-freetext">https://github.com/openjdk/jfx/pull/910</a>
a lot of "new" insights<br>
were gained in the snapping logic. Michael
Strauss suggested<br>
documenting this, and I thought we may as well
discuss this on the<br>
mailing list instead of continuing the discussion
in that PR.<br>
<br>
In my normal line of work, I usually encourage
projects to include<br>
developer documentation as part of the Git
repository. This allows any<br>
developer to access and modify the documentation
easily, and allows you<br>
to keep documentation in sync with relevant
commits (and one can ask<br>
developers to do so as part of the PR).<br>
<br>
The documentation is provided in markdown format
and is usually stored<br>
in a /doc folder. If there are multiple modules,
there can be<br>
specialized doc folders per module with a top
level doc folder which<br>
contains an index.md linking all the docs
together, and containing<br>
documentation that is not module specific.<br>
<br>
The documentation is intended for developers only,
not for users of<br>
JavaFX, and hence does not need to be published.
Markdown files can<br>
either be read directly in your IDE of choice or
online via GitHub/GitLab.<br>
<br>
The build documentation may be a good candidate to
place there as well.<br>
<br>
So, my suggestion would be:<br>
<br>
- Create a top level /doc folder, and create
module level /doc folders<br>
as needed when relevant documentation is written<br>
- In each /doc folder there is an index.md file
that links to all<br>
documentation in that folder<br>
- A higher level index.md also contains links to
child indexes<br>
- Consider moving the build and any onboarding
documentation there<br>
- The top level README.md should have a link to
/doc/index.md<br>
- Use only GitHub supported markdown features<br>
<br>
--John<br>
<br>
<br>
<o:p></o:p></span></p>
</div>
</div>
</div>
</div>
</div>
</div>
</blockquote>
<br>
</body>
</html>