<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>