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

[Joe Darcy]

Good docs cleanup Jon; thanks,

-Joe

On 5/17/2019 5:16 PM, Jonathan Gibbons wrote:
> 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
>
>
>