<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 15 (filtered medium)">
<style><!--
/* Font Definitions */
@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;}
/* Style Definitions */
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;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="blue" vlink="purple" style="word-wrap:break-word">
<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">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 <openjfx-dev-retn@openjdk.org> on behalf of Marius Hanl <mariushanl@web.de><br>
<b>Date: </b>Friday, May 12, 2023 at 13:57<br>
<b>To: </b>John Hendrikx <john.hendrikx@gmail.com><br>
<b>Cc: </b>openjfx-dev@openjdk.org <openjfx-dev@openjdk.org><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: https://github.com/openjdk/jdk/tree/master/doc<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: https://github.com/openjdk/jdk/blob/master/doc/building.md<br>
And: https://github.com/openjdk/jdk/blob/master/doc/building.html<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" <john.hendrikx@gmail.com><br>
<b>An:</b> openjfx-dev@openjdk.org<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">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>
</body>
</html>