RFR: docs/build JDK-8223663 Update links for tool guides

Jonathan Gibbons jonathan.gibbons at oracle.com
Sat May 18 00:16:47 UTC 2019


In JDK 13, the pages for the Tools Reference guides are moving, and so 
the links from the API pages to these guides needs to be updated.

Please review a two-part change.

1. A new taglet is introduced that can generates links from API pages to 
pages in the sibling specs/man directory, which is the new home for the 
pages known as "Tool Guides" a.k.a "man" pages.

     The new taglet is used as follows:   @toolGuide <tool-name>
     This generates a section in the specification similar to what was 
generated before, although previously it was done in a more complicated 
manner.

     The taglet is placed in the build.tools package, alongside other 
recent custom taglets.

     make/Docs.gmk is updated to use the new taglet.


2. All the references in the various module-info.java files to the old 
"Tools Reference" pages are replaced with usages of the new taglet.

     Although this is generally a case of replacing old references with 
new references, there are some anomalies that had to be taken into account.

     a. There is not, and apparently never was, a Tools Reference page 
for "jfr". The reference was 404. The link is removed for now, and can 
be replaced if such a page becomes available.

     b. Some of the links under the "Tools Reference" heading were to 
pages that were not "man" pages, and which are not being migrated at 
this time. These links are left alone, although it has meant separating 
the two kinds of links into two separate lists, one for the old-style 
links which remain, and one for the new "man" pages.

-- Jon


JBS: https://bugs.openjdk.java.net/browse/JDK-8223663
Webrev: http://cr.openjdk.java.net/~jjg/8223663-toolguides/webrev.00/
Sample docs: 
http://cr.openjdk.java.net/~jjg/8223663-toolguides/docs/api/index.html






More information about the build-dev mailing list