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
