<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<p>Apart from the first line which may have special significance,
GitHub renders this nicely enough when you activate the preview.</p>
<p>I didn't mean to specifically suggest a special flavor of
markdown, just that we should ensure it looks okay on GitHub as
that will often be the viewer used.</p>
<p>--John<br>
</p>
<div class="moz-cite-prefix">On 12/05/2023 23:00, Andy Goryachev
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:DM5PR1001MB2172064331B96AFC8865F746E5759@DM5PR1001MB2172.namprd10.prod.outlook.com">
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<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>
</body>
</html>