8223663: Update links for tool guides

Reviewed-by: alanb, erikj, darcy

make/Docs.gmk

@@ -86,6 +86,7 @@ JAVADOC_TAGS := \
     -tag return \
     -tag throws \
     -taglet build.tools.taglet.ModuleGraph \
+    -taglet build.tools.taglet.ToolGuide \
     -tag since \
     -tag serialData \
     -tag factory \

make/jdk/src/classes/build/tools/taglet/ToolGuide.java

@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package build.tools.taglet;
+
+import java.util.EnumSet;
+import java.util.List;
+import java.util.Set;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+import javax.lang.model.element.Element;
+import javax.lang.model.element.ModuleElement;
+import javax.lang.model.element.PackageElement;
+
+import com.sun.source.doctree.DocTree;
+import com.sun.source.doctree.UnknownBlockTagTree;
+import jdk.javadoc.doclet.Taglet;
+
+import static com.sun.source.doctree.DocTree.Kind.*;
+import static jdk.javadoc.doclet.Taglet.Location.*;
+
+/**
+ * A block tag to insert a link to tool guide in a nearby directory.
+ * The tag can be used as follows:
+ * <ul>
+ * <li>&commat;toolGuide tool-name label
+ * </ul>
+ *
+ * If the label is omitted, it defaults to the tool name.
+ *
+ * For example
+ * <p>
+ * &commat;toolGuide javac
+ * <p>
+ * will produce the following html, depending on the file containing
+ * the tag.
+ * <p>
+ * {@code
+ * <dt>Tool Guides:
+ * <dd><a href="../../specs/man/javac.html">javac</a>
+ * }
+ */
+public class ToolGuide implements Taglet {
+
+    static final String TAG_NAME = "toolGuide";
+
+    static final String BASE_URL = "../specs/man";
+
+    static final Pattern TAG_PATTERN = Pattern.compile("(?s)(?<name>[A-Za-z0-9]+)\\s*(?<label>.*)$");
+
+    /**
+     * Returns the set of locations in which the tag may be used.
+     */
+    @Override
+    public Set<Location> getAllowedLocations() {
+        return EnumSet.of(MODULE, PACKAGE);
+    }
+
+    @Override
+    public boolean isInlineTag() {
+        return false;
+    }
+
+    @Override
+    public String getName() {
+        return TAG_NAME;
+    }
+
+    @Override
+    public String toString(List<? extends DocTree> tags, Element elem) {
+
+        if (tags.isEmpty())
+            return "";
+
+        StringBuilder sb = new StringBuilder();
+        sb.append("<dt class=\"simpleTagLabel\">Tool Guides:</dt>\n")
+                .append("<dd>");
+
+        boolean needComma = false;
+        for (DocTree tag : tags) {
+
+            if (tag.getKind() != UNKNOWN_BLOCK_TAG) {
+                continue;
+            }
+
+            UnknownBlockTagTree blockTag = (UnknownBlockTagTree)tag;
+            String tagText = blockTag.getContent().toString().trim();
+            Matcher m = TAG_PATTERN.matcher(tagText);
+            if (m.matches()) {
+                String name = m.group("name");
+                String label = m.group("label");
+                if (label.isEmpty()) {
+                    label = name;
+                }
+
+                String url = String.format("%s/%s/%s.html",
+                        docRoot(elem), BASE_URL, name);
+
+                if (needComma) {
+                    sb.append(",\n");
+                } else {
+                    needComma = true;
+                }
+
+                sb.append("<a href=\"")
+                        .append(url)
+                        .append("\">")
+                        .append(label)
+                        .append("</a>");
+            }
+        }
+
+        sb.append("</dd>\n");
+
+        return sb.toString();
+    }
+
+    private String docRoot(Element elem) {
+        switch (elem.getKind()) {
+            case MODULE:
+                return "..";
+
+            case PACKAGE:
+                PackageElement pe = (PackageElement)elem;
+                String pkgPart = pe.getQualifiedName()
+                        .toString()
+                        .replace('.', '/')
+                        .replaceAll("[^/]+", "..");
+                return pe.getEnclosingElement() != null
+                        ? "../" + pkgPart
+                        : pkgPart;
+
+            default:
+                throw new IllegalArgumentException(elem.getKind().toString());
+        }
+    }
+}

src/java.base/share/classes/module-info.java

@@ -36,11 +36,11 @@
  *      {@link java.nio.file.FileSystems#newFileSystem
  *      FileSystems.newFileSystem(URI.create("jrt:/"))}.
  *      </dd>
- * <dt class="simpleTagLabel" style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">Tool Guides:</dt>
- * <dd style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif"> {@extLink java_tool_reference java launcher},
- *      {@extLink keytool_tool_reference keytool}</dd>
  * </dl>
  *
+ * @toolGuide java java launcher
+ * @toolGuide keytool
+ *
  * @provides java.nio.file.spi.FileSystemProvider
  *
  * @uses java.lang.System.LoggerFinder

src/java.rmi/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,12 +31,8 @@
  * object registry, and the <em>{@index rmid rmid tool}</em> tool to start
  * the activation system daemon.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide rmiregistry
- * <dt class="simpleTagLabel">Tool Guides:</dt>
+ * @toolGuide rmid
- * <dd> {@extLink rmiregistry_tool_reference rmiregistry},
- *      {@extLink rmid_tool_reference rmid}
- * </dd>
- * </dl>
  *
  * @uses java.rmi.server.RMIClassLoaderSpi
  *

src/java.scripting/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -31,10 +31,7 @@
  * that supports executing JavaScript and other languages if its corresponding
  * script engine is installed.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jrunscript
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd> {@extLink jrunscript_tool_reference jrunscript}</dd>
- * </dl>
  *
  * @uses javax.script.ScriptEngineFactory
  *

src/jdk.compiler/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -55,10 +55,7 @@
  * {@code jdk.zipfs} module, must be available if the compiler is to be able
  * to read JAR files.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide javac
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink javac_tool_reference javac}
- * </dl>
  *
  * @provides java.util.spi.ToolProvider
  * @provides com.sun.tools.javac.platform.PlatformProvider

src/jdk.hotspot.agent/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -30,10 +30,7 @@
  * attach to a running Java Virtual Machine (JVM) or launch a postmortem
  * debugger to analyze the content of a core-dump from a crashed JVM.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jhsdb
- * <dt class="simpleTagLabel">Tool Guides:</dt>
- * <dd> {@extLink jhsdb_tool_reference jhsdb}</dd>
- * </dl>
  *
  * @moduleGraph
  * @since 9

src/jdk.jartool/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -36,11 +36,8 @@
  * or the {@linkplain java.util.ServiceLoader service loader} with the name
  * {@code "jar"}.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jar
- * <dt class="simpleTagLabel">Tool Guides:
+ * @toolGuide jarsigner
- * <dd>{@extLink jar_tool_reference jar},
- *     {@extLink jarsigner_tool_reference jarsigner}
- * </dl>
  *
  * @moduleGraph
  * @since 9

src/jdk.javadoc/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,10 +42,7 @@
  * or the {@linkplain java.util.ServiceLoader service loader} with the name
  * {@code "javadoc"}.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide javadoc
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink javadoc_tool_reference javadoc}
- * </dl>
  *
  * @provides java.util.spi.ToolProvider
  * @provides javax.tools.DocumentationTool

src/jdk.jcmd/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,16 +28,12 @@
  * such as the <em>{@index jcmd jcmd tool}</em>, <em>{@index jps jps tool}</em>,
  * <em>{@index jstat jstat tool}</em> tools.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jcmd
- * <dt class="simpleTagLabel">Tool Guides:
+ * @toolGuide jinfo
- * <dd>
+ * @toolGuide jmap
- * {@extLink jcmd_tool_reference jcmd},
+ * @toolGuide jps
- * {@extLink jinfo_tool_reference jinfo},
+ * @toolGuide jstack
- * {@extLink jmap_tool_reference jmap},
+ * @toolGuide jstat
- * {@extLink jps_tool_reference jps},
- * {@extLink jstack_tool_reference jstack},
- * {@extLink jstat_tool_reference jstat}
- * </dl>
  *
  * @moduleGraph
  * @since 9

src/jdk.jconsole/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -28,11 +28,12 @@
  * for monitoring and managing a running application.
  *
  * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
- * <dt class="simpleTagLabel">Tool Guides:
+ * <dt class="simpleTagLabel">See Also:
- * <dd>{@extLink jconsole_tool_reference jconsole},
+ * <dd>{@extLink using_jconsole Using JConsole}
- *     {@extLink using_jconsole Using JConsole}
  * </dl>
  *
+ * @toolGuide jconsole
+ *
  * @uses com.sun.tools.jconsole.JConsolePlugin
  *
  * @moduleGraph

src/jdk.jdeps/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -44,12 +44,9 @@
  * <em>jdeprscan</em> only exists as a command line tool, and does not provide
  * any direct API.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide javap
- * <dt class="simpleTagLabel">Tool Guides:
+ * @toolGuide jdeprscan
- * <dd>{@extLink javap_tool_reference javap},
+ * @toolGuide jdeps
- *     {@extLink jdeprscan_tool_reference jdeprscan},
- *     {@extLink jdeps_tool_reference jdeps}
- * </dl>
  *
  * @provides java.util.spi.ToolProvider
  *

src/jdk.jdi/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -104,10 +104,7 @@
  * </blockquote>
  *
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jdb
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink jdb_tool_reference jdb}
- * </dl>
  *
  * @provides com.sun.jdi.connect.Connector
  *

src/jdk.jfr/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,11 +27,6 @@
  * Defines the API for JDK Flight Recorder.
  * <p>
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink jfr_tool_reference jfr}
- * </dl>
- *
  * @moduleGraph
  * @since 9
  */

src/jdk.jlink/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -30,8 +30,7 @@
  * the JDK implementation-specific container file for classes and resources.
  *
  * <p> This module provides the equivalent of command-line access to the
- * <em>{@extLink jlink_tool_reference jlink}</em> and
+ * <em>jlink</em> and <em>jmod</em> tools via the
- * <em>{@extLink jmod_tool_reference jmod}</em> tools via the
  * {@link java.util.spi.ToolProvider ToolProvider} SPI.
  * Instances of the tools can be obtained by calling
  * {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst}
@@ -41,11 +40,8 @@
  * <p> <em>jimage</em> only exists
  * as a command-line tool, and does not provide any direct API.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jlink
- * <dt class="simpleTagLabel">Tool Guides:
+ * @toolGuide jmod
- * <dd>{@extLink jlink_tool_reference jlink},
- *     {@extLink jmod_tool_reference jmod}
- * </dl>
  *
  * @provides java.util.spi.ToolProvider
  *

src/jdk.jshell/share/classes/module-info.java

@@ -54,10 +54,7 @@
  *     definitions.
  * </p>
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jshell
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink jshell_tool_reference jshell}
- * </dl>
  *
  * @provides javax.tools.Tool
  * @provides jdk.jshell.spi.ExecutionControlProvider

src/jdk.jstatd/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,10 +27,7 @@
  * Defines the <em>{@index jstatd jstatd tool}</em> tool for starting a daemon
  * for the jstat tool to monitor JVM statistics remotely.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jstatd
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink jstatd_tool_reference jstatd}
- * </dl>
  *
  * @moduleGraph
  * @since 9

src/jdk.pack/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -29,11 +29,8 @@
  * <em>{@index pack200 pack200 tool}</em> and
  * <em>{@index unpack200 unpack200 tool}</em> tools.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide pack200
- * <dt class="simpleTagLabel">Tool Guides:
+ * @toolGuide unpack200
- * <dd>{@extLink pack200_tool_reference pack200},
- *     {@extLink unpack200_tool_reference unpack200}
- * </dl>
  *
  * @moduleGraph
  * @deprecated This module is deprecated, and is planned for removal in a

src/jdk.rmic/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,10 +27,7 @@
  * Defines the <em>{@index rmic rmic}</em> compiler for generating stubs and
  * skeletons using the Java Remote Method Protocol (JRMP) for remote objects.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide rmic
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink rmic_tool_reference rmic}
- * </dl>
  *
  * @moduleGraph
  * @since 9

src/jdk.scripting.nashorn.shell/share/classes/module-info.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 2019, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -29,10 +29,7 @@
  * <p>This module includes the command line tool <em>{@index jjs jjs tool}</em>
  * to invoke the Nashorn engine.
  *
- * <dl style="font-family:'DejaVu Sans', Arial, Helvetica, sans serif">
+ * @toolGuide jjs
- * <dt class="simpleTagLabel">Tool Guides:
- * <dd>{@extLink jjs_tool_reference jjs}
- * </dl>
  *
  * @moduleGraph
  * @since 9