Repository: bazelbuild/bazel
Issue: Link to individual flags in command line reference 
Labels: type: documentation (cleanup)
P2
team-Bazel

We need be able to link to individual flags in the command line reference (https://docs.bazel.build/versions/master/command-line-reference.html) from elsewhere in the doc.

To keep info consistent and fresh, flags should only be documented in one place, and this doc should be generated from the code's in-line doc (which is what's done in that reference topic). When flags are discussed elsewhere in the doc, should be able to deep link to the flag on that reference page.

Issue comments:

Pull request review comments:

Patch that resolved the issue:
diff --git a/site/_sass/style.scss b/site/_sass/style.scss
index d2feac91d18882..6bbb8b755534d3 100644
--- a/site/_sass/style.scss
+++ b/site/_sass/style.scss
@@ -172,3 +172,10 @@ $md-shadow-3: rgba(0, 0, 0, .12);
     box-sizing: content-box !important;
   }
 }
+
+// Used for the Command-line Reference flag anchors. Linkifying the flag name
+// causes it to turn $link-color (green), but we turn it red here to be consistent
+// with the rest of the code block.
+dd > code > a, dl > dt > code > a {
+  color: #c7254e;
+}
diff --git a/src/main/java/com/google/devtools/common/options/OptionsUsage.java b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
index 6dee0eb7acc655..cd6a48fd680584 100644
--- a/src/main/java/com/google/devtools/common/options/OptionsUsage.java
+++ b/src/main/java/com/google/devtools/common/options/OptionsUsage.java
@@ -200,8 +200,20 @@ static void getUsageHtml(
     String flagName = getFlagName(optionDefinition);
     String valueDescription = optionDefinition.getValueTypeHelpText();
     String typeDescription = getTypeDescription(optionDefinition);
-    usage.append("<dt><code><a name=\"flag--").append(plainFlagName).append("\"></a>--");
-    usage.append(flagName);
+
+    usage
+        // Add the id of the flag to point anchor hrefs to it
+        .append("<dt id=\"flag--")
+        .append(plainFlagName)
+        .append("\">")
+        // Add the href to the id hash
+        .append("<code><a href=\"#flag--")
+        .append(plainFlagName)
+        .append("\">")
+        // Use the flag name as the link body
+        .append("--" + flagName)
+        .append("</a>");
+
     if (optionDefinition.usesBooleanValueSyntax() || optionDefinition.isVoidField()) {
       // Nothing for boolean, tristate, boolean_or_enum, or void options.
     } else if (!valueDescription.isEmpty()) {
@@ -249,14 +261,21 @@ static void getUsageHtml(
         Preconditions.checkArgument(!expansion.isEmpty());
         expandsMsg = new StringBuilder("Expands to:<br/>\n");
         for (String exp : expansion) {
-          // TODO(ulfjack): We should link to the expanded flags, but unfortunately we don't
+          // TODO(jingwen): We link to the expanded flags here, but unfortunately we don't
           // currently guarantee that all flags are only printed once. A flag in an OptionBase that
           // is included by 2 different commands, but not inherited through a parent command, will
-          // be printed multiple times.
+          // be printed multiple times. Clicking on the flag will bring the user to its first
+          // definition.
           expandsMsg
-              .append("&nbsp;&nbsp;<code>")
+              .append("&nbsp;&nbsp;")
+              .append("<code><a href=\"#flag")
+              // Link to the '#flag--flag_name' hash.
+              // Some expansions are in the form of '--flag_name=value', so we drop everything from
+              // '=' onwards.
+              .append(escaper.escape(exp).split("=")[0])
+              .append("\">")
               .append(escaper.escape(exp))
-              .append("</code><br/>\n");
+              .append("</a></code><br/>\n");
         }
       }
       usage.append(expandsMsg.toString());


Test patch:
diff --git a/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java b/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java
index 6f3550649bbe09..2520f80b31fc60 100644
--- a/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java
+++ b/src/test/java/com/google/devtools/common/options/OptionsUsageTest.java
@@ -100,15 +100,15 @@ public void stringValue_longTerminalOutput() {
   public void stringValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_string"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_string\"></a>"
-                + "--test_string=&lt;a string&gt</code> default: \"test string default\"</dt>\n"
+            "<dt id=\"flag--test_string\"><code><a href=\"#flag--test_string\">--test_string</a>"
+                + "=&lt;a string&gt</code> default: \"test string default\"</dt>\n"
                 + "<dd>\n"
                 + "a string-valued option to test simple option operations\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_string"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_string\"></a>"
-                + "--test_string=&lt;a string&gt</code> default: \"test string default\"</dt>\n"
+            "<dt id=\"flag--test_string\"><code><a href=\"#flag--test_string\">--test_string</a>"
+                + "=&lt;a string&gt</code> default: \"test string default\"</dt>\n"
                 + "<dd>\n"
                 + "a string-valued option to test simple option operations\n"
                 + "<br>Tags: \n"
@@ -149,15 +149,17 @@ public void intValue_longTerminalOutput() {
   public void intValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("expanded_c"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--expanded_c\"></a>"
-                + "--expanded_c=&lt;an integer&gt</code> default: \"12\"</dt>\n"
+            "<dt id=\"flag--expanded_c\"><code>"
+                + "<a href=\"#flag--expanded_c\">--expanded_c</a>"
+                + "=&lt;an integer&gt</code> default: \"12\"</dt>\n"
                 + "<dd>\n"
                 + "an int-value&#39;d flag used to test expansion logic\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("expanded_c"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--expanded_c\"></a>"
-                + "--expanded_c=&lt;an integer&gt</code> default: \"12\"</dt>\n"
+            "<dt id=\"flag--expanded_c\"><code>"
+                + "<a href=\"#flag--expanded_c\">--expanded_c</a>"
+                + "=&lt;an integer&gt</code> default: \"12\"</dt>\n"
                 + "<dd>\n"
                 + "an int-value&#39;d flag used to test expansion logic\n"
                 + "<br>Tags: \n"
@@ -197,8 +199,8 @@ public void booleanValue_longTerminalOutput() {
   public void booleanValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("expanded_a"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--expanded_a\"></a>"
-                + "--[no]expanded_a</code> default: \"true\"</dt>\n"
+            "<dt id=\"flag--expanded_a\"><code><a href=\"#flag--expanded_a\">"
+                + "--[no]expanded_a</a></code> default: \"true\"</dt>\n"
                 + "<dd>\n"
                 + "A boolean flag with unknown effect to test tagless usage text.\n"
                 + "</dd>\n");
@@ -238,16 +240,18 @@ public void multipleValue_longTerminalOutput() {
   public void multipleValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_multiple_string"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_multiple_string\"></a>"
-                + "--test_multiple_string=&lt;a string&gt</code> "
+            "<dt id=\"flag--test_multiple_string\"><code>"
+                + "<a href=\"#flag--test_multiple_string\">--test_multiple_string</a>"
+                + "=&lt;a string&gt</code> "
                 + "multiple uses are accumulated</dt>\n"
                 + "<dd>\n"
                 + "a repeatable string-valued flag with its own unhelpful help text\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_multiple_string"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_multiple_string\"></a>"
-                + "--test_multiple_string=&lt;a string&gt</code> "
+            "<dt id=\"flag--test_multiple_string\"><code>"
+                + "<a href=\"#flag--test_multiple_string\">--test_multiple_string</a>"
+                + "=&lt;a string&gt</code> "
                 + "multiple uses are accumulated</dt>\n"
                 + "<dd>\n"
                 + "a repeatable string-valued flag with its own unhelpful help text\n"
@@ -291,8 +295,9 @@ public void customConverterValue_longTerminalOutput() {
   public void customConverterValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_list_converters"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_list_converters\"></a>"
-                + "--test_list_converters=&lt;a list of strings&gt</code> "
+            "<dt id=\"flag--test_list_converters\"><code>"
+                + "<a href=\"#flag--test_list_converters\">--test_list_converters</a>"
+                + "=&lt;a list of strings&gt</code> "
                 + "multiple uses are accumulated</dt>\n"
                 + "<dd>\n"
                 + "a repeatable flag that accepts lists, but doesn&#39;t want to have lists of \n"
@@ -300,8 +305,9 @@ public void customConverterValue_htmlOutput() {
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_list_converters"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_list_converters\"></a>"
-                + "--test_list_converters=&lt;a list of strings&gt</code> "
+            "<dt id=\"flag--test_list_converters\"><code>"
+                + "<a href=\"#flag--test_list_converters\">--test_list_converters</a>"
+                + "=&lt;a list of strings&gt</code> "
                 + "multiple uses are accumulated</dt>\n"
                 + "<dd>\n"
                 + "a repeatable flag that accepts lists, but doesn&#39;t want to have lists of \n"
@@ -348,33 +354,33 @@ public void staticExpansionOption_longTerminalOutput() {
   public void staticExpansionOption_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_expansion"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_expansion\"></a>"
-                + "--test_expansion</code></dt>\n"
+            "<dt id=\"flag--test_expansion\"><code><a href=\"#flag--test_expansion\">"
+                + "--test_expansion</a></code></dt>\n"
                 + "<dd>\n"
                 + "this expands to an alphabet soup.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--noexpanded_a</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_b=false</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_c</code><br/>\n"
-                + "&nbsp;&nbsp;<code>42</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_d</code><br/>\n"
-                + "&nbsp;&nbsp;<code>bar</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--noexpanded_a\">--noexpanded_a</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_b\">--expanded_b=false</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_c\">--expanded_c</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag42\">42</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_d\">--expanded_d</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flagbar\">bar</a></code><br/>\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_expansion"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_expansion\"></a>"
-                + "--test_expansion</code></dt>\n"
+            "<dt id=\"flag--test_expansion\"><code><a href=\"#flag--test_expansion\">"
+                + "--test_expansion</a></code></dt>\n"
                 + "<dd>\n"
                 + "this expands to an alphabet soup.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--noexpanded_a</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_b=false</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_c</code><br/>\n"
-                + "&nbsp;&nbsp;<code>42</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_d</code><br/>\n"
-                + "&nbsp;&nbsp;<code>bar</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--noexpanded_a\">--noexpanded_a</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_b\">--expanded_b=false</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_c\">--expanded_c</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag42\">42</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_d\">--expanded_d</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flagbar\">bar</a></code><br/>\n"
                 + "<br>Tags: \n"
                 + "<a href=\"#effect_tag_NO_OP\"><code>no_op</code></a>"
                 + "</dd>\n");
@@ -424,25 +430,27 @@ public void recursiveExpansionOption_longTerminalOutput() {
   public void recursiveExpansionOption_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_recursive_expansion_top_level"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_recursive_expansion_top_level\"></a>"
-                + "--test_recursive_expansion_top_level</code></dt>\n"
+            "<dt id=\"flag--test_recursive_expansion_top_level\">"
+                + "<code><a href=\"#flag--test_recursive_expansion_top_level\">"
+                + "--test_recursive_expansion_top_level</a></code></dt>\n"
                 + "<dd>\n"
                 + "Lets the children do all the work.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--test_recursive_expansion_middle1</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--test_recursive_expansion_middle2</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_recursive_expansion_middle1\">--test_recursive_expansion_middle1</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_recursive_expansion_middle2\">--test_recursive_expansion_middle2</a></code><br/>\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_recursive_expansion_top_level"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_recursive_expansion_top_level\"></a>"
-                + "--test_recursive_expansion_top_level</code></dt>\n"
+            "<dt id=\"flag--test_recursive_expansion_top_level\">"
+                + "<code><a href=\"#flag--test_recursive_expansion_top_level\">"
+                + "--test_recursive_expansion_top_level</a></code></dt>\n"
                 + "<dd>\n"
                 + "Lets the children do all the work.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--test_recursive_expansion_middle1</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--test_recursive_expansion_middle2</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_recursive_expansion_middle1\">--test_recursive_expansion_middle1</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_recursive_expansion_middle2\">--test_recursive_expansion_middle2</a></code><br/>\n"
                 + "<br>Tags: \n"
                 + "<a href=\"#effect_tag_NO_OP\"><code>no_op</code></a>"
                 + "</dd>\n");
@@ -485,25 +493,25 @@ public void expansionToMultipleValue_longTerminalOutput() {
   public void expansionToMultipleValue_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_expansion_to_repeatable"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_expansion_to_repeatable\"></a>"
-                + "--test_expansion_to_repeatable</code></dt>\n"
+            "<dt id=\"flag--test_expansion_to_repeatable\"><code><a href=\"#flag--test_expansion_to_repeatable\">--test_expansion_to_repeatable</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Go forth and multiply, they said.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--test_multiple_string=expandedFirstValue</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--test_multiple_string=expandedSecondValue</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_multiple_string\">--test_multiple_string=expandedFirstValue</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_multiple_string\">--test_multiple_string=expandedSecondValue</a></code><br/>\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_expansion_to_repeatable"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_expansion_to_repeatable\"></a>"
-                + "--test_expansion_to_repeatable</code></dt>\n"
+            "<dt id=\"flag--test_expansion_to_repeatable\"><code><a href=\"#flag--test_expansion_to_repeatable\">--test_expansion_to_repeatable</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Go forth and multiply, they said.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--test_multiple_string=expandedFirstValue</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--test_multiple_string=expandedSecondValue</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_multiple_string\">--test_multiple_string=expandedFirstValue</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--test_multiple_string\">--test_multiple_string=expandedSecondValue</a></code><br/>\n"
                 + "<br>Tags: \n"
                 + "<a href=\"#effect_tag_NO_OP\"><code>no_op</code></a>"
                 + "</dd>\n");
@@ -546,16 +554,18 @@ public void implicitRequirementOption_longTerminalOutput() {
   public void implicitRequirementOption_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_implicit_requirement"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_implicit_requirement\"></a>"
-                + "--test_implicit_requirement=&lt;a string&gt</code> "
+            "<dt id=\"flag--test_implicit_requirement\"><code>"
+                + "<a href=\"#flag--test_implicit_requirement\">--test_implicit_requirement</a>"
+                + "=&lt;a string&gt</code> "
                 + "default: \"direct implicit\"</dt>\n"
                 + "<dd>\n"
                 + "this option really needs that other one, isolation of purpose has failed.\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_implicit_requirement"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_implicit_requirement\"></a>"
-                + "--test_implicit_requirement=&lt;a string&gt</code> "
+            "<dt id=\"flag--test_implicit_requirement\"><code>"
+                + "<a href=\"#flag--test_implicit_requirement\">--test_implicit_requirement</a>"
+                + "=&lt;a string&gt</code> "
                 + "default: \"direct implicit\"</dt>\n"
                 + "<dd>\n"
                 + "this option really needs that other one, isolation of purpose has failed.\n"
@@ -599,25 +609,27 @@ public void expansionFunctionOptionThatExpandsBasedOnOtherLoadedOptions_longTerm
   public void expansionFunctionOptionThatExpandsBasedOnOtherLoadedOptions_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("prefix_expansion"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--prefix_expansion\"></a>"
-                + "--prefix_expansion</code></dt>\n"
+            "<dt id=\"flag--prefix_expansion\"><code>"
+                + "<a href=\"#flag--prefix_expansion\">--prefix_expansion</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Expands to all options with a specific prefix.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--specialexp_bar</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--specialexp_foo</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--specialexp_bar\">--specialexp_bar</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--specialexp_foo\">--specialexp_foo</a></code><br/>\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("prefix_expansion"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--prefix_expansion\"></a>"
-                + "--prefix_expansion</code></dt>\n"
+            "<dt id=\"flag--prefix_expansion\"><code>"
+                + "<a href=\"#flag--prefix_expansion\">--prefix_expansion</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Expands to all options with a specific prefix.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--specialexp_bar</code><br/>\n"
-                + "&nbsp;&nbsp;<code>--specialexp_foo</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--specialexp_bar\">--specialexp_bar</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--specialexp_foo\">--specialexp_foo</a></code><br/>\n"
                 + "<br>Tags: \n"
                 + "<a href=\"#effect_tag_NO_OP\"><code>no_op</code></a>"
                 + "</dd>\n");
@@ -658,25 +670,27 @@ public void tagHeavyExpansionOption_longTerminalOutput() {
   public void tagHeavyExpansionOption_htmlOutput() {
     assertThat(getHtmlUsageWithoutTags("test_void_expansion_function"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_void_expansion_function\"></a>"
-                + "--test_void_expansion_function</code></dt>\n"
+            "<dt id=\"flag--test_void_expansion_function\"><code>"
+                + "<a href=\"#flag--test_void_expansion_function\">--test_void_expansion_function</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Listing a ton of random tags to test the usage output.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_d</code><br/>\n"
-                + "&nbsp;&nbsp;<code>void expanded</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_d\">--expanded_d</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flagvoid expanded\">void expanded</a></code><br/>\n"
                 + "</dd>\n");
     assertThat(getHtmlUsageWithTags("test_void_expansion_function"))
         .isEqualTo(
-            "<dt><code><a name=\"flag--test_void_expansion_function\"></a>"
-                + "--test_void_expansion_function</code></dt>\n"
+            "<dt id=\"flag--test_void_expansion_function\"><code>"
+                + "<a href=\"#flag--test_void_expansion_function\">--test_void_expansion_function</a>"
+                + "</code></dt>\n"
                 + "<dd>\n"
                 + "Listing a ton of random tags to test the usage output.\n"
                 + "<br/>\n"
                 + "Expands to:<br/>\n"
-                + "&nbsp;&nbsp;<code>--expanded_d</code><br/>\n"
-                + "&nbsp;&nbsp;<code>void expanded</code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flag--expanded_d\">--expanded_d</a></code><br/>\n"
+                + "&nbsp;&nbsp;<code><a href=\"#flagvoid expanded\">void expanded</a></code><br/>\n"
                 + "<br>Tags: \n"
                 + "<a href=\"#effect_tag_ACTION_COMMAND_LINES\"><code>action_command_lines</code>"
                 + "</a>, "