godoc: add anchors to cmd documentation headings

Also, disable server-side generation of TOC for commands as they would
only ever show Overview. The JS does a better job (for now).

Fixes #2732.

R=gri, dsymonds
CC=golang-dev
https://golang.org/cl/5558046

diff --git a/doc/godocs.js b/doc/godocs.js
index bbf5ea289313ca074a8654f5bba035378dcd4411..3b8625a58d70b31609df6cfe3f8929728d1fa02d 100644 (file)
--- a/doc/godocs.js
+++ b/doc/godocs.js
@@ -66,44 +66,32 @@ function godocs_generateTOC() {
   var i;
   for (i = 0; i < navbar.parentNode.childNodes.length; i++) {
     var node = navbar.parentNode.childNodes[i];
-    if ((node.tagName == 'h2') || (node.tagName == 'H2')) {
-      if (!node.id) {
-        node.id = 'tmp_' + i;
-      }
-      var text = godocs_nodeToText(node);
-      if (!text) { continue; }
-
-      var textNode = document.createTextNode(text);
-
-      var link = document.createElement('a');
-      link.href = '#' + node.id;
-      link.appendChild(textNode);
-
-      // Then create the item itself
-      var item = document.createElement('dt');
-
-      item.appendChild(link);
-      toc_items.push(item);
+    if ((node.tagName != 'h2') && (node.tagName != 'H2') &&
+        (node.tagName != 'h3') && (node.tagName != 'H3')) {
+      continue;
     }
-    if ((node.tagName == 'h3') || (node.tagName == 'H3')) {
-      if (!node.id) {
-        node.id = 'tmp_' + i;
-      }
-      var text = godocs_nodeToText(node);
-      if (!text) { continue; }
-
-      var textNode = document.createTextNode(text);
+    if (!node.id) {
+      node.id = 'tmp_' + i;
+    }
+    var text = godocs_nodeToText(node);
+    if (!text) { continue; }
 
-      var link = document.createElement('a');
-      link.href = '#' + node.id;
-      link.appendChild(textNode);
+    var textNode = document.createTextNode(text);
 
-      // Then create the item itself
-      var item = document.createElement('dd');
+    var link = document.createElement('a');
+    link.href = '#' + node.id;
+    link.appendChild(textNode);
 
-      item.appendChild(link);
-      toc_items.push(item);
+    // Then create the item itself
+    var item;
+    if ((node.tagName == 'h2') || (node.tagName == 'H2')) {
+      item = document.createElement('dt');
+    } else { // h3
+      item = document.createElement('dd');
     }
+
+    item.appendChild(link);
+    toc_items.push(item);
   }
 
   if (toc_items.length <= 1) { return; }

diff --git a/lib/godoc/package.html b/lib/godoc/package.html
index 155f24032ab3076ccae2989826e9725efcb0886b..5a7f3ef976d40a4c637c573d9e86fb4129fb7805 100644 (file)
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -3,6 +3,7 @@
        Use of this source code is governed by a BSD-style
        license that can be found in the LICENSE file.
 -->
+{{if .IsPkg}}
 <!-- Table of contents; must be named manual-nav to turn off auto nav. -->
 <div id="manual-nav">
 {{with .PDoc}}
@@ -37,6 +38,7 @@
        </dl>
 {{end}}
 </div>
+{{end}}
 
 <!-- Main page -->             
 {{with .PAst}}

diff --git a/src/pkg/go/doc/comment.go b/src/pkg/go/doc/comment.go
index 060e37bff148d21b2c9c4ab313c4276ee3b80866..d73b1315954bc7d5820b72d6cf368eb3bb9c0736 100644 (file)
--- a/src/pkg/go/doc/comment.go
+++ b/src/pkg/go/doc/comment.go
@@ -68,7 +68,8 @@ var (
        html_endp   = []byte("</p>\n")
        html_pre    = []byte("<pre>")
        html_endpre = []byte("</pre>\n")
-       html_h      = []byte("<h3>")
+       html_h      = []byte(`<h3 id="`)
+       html_hq     = []byte(`">`)
        html_endh   = []byte("</h3>\n")
 )
 
@@ -225,6 +226,12 @@ type block struct {
        lines []string
 }
 
+var nonAlphaNumRx = regexp.MustCompile(`[^a-zA-Z0-9]`)
+
+func anchorID(line string) string {
+       return nonAlphaNumRx.ReplaceAllString(line, "_")
+}
+
 // ToHTML converts comment text to formatted HTML.
 // The comment was prepared by DocReader,
 // so it is known not to have leading, trailing blank lines
@@ -253,9 +260,18 @@ func ToHTML(w io.Writer, text string, words map[string]string) {
                        w.Write(html_endp)
                case opHead:
                        w.Write(html_h)
+                       id := ""
                        for _, line := range b.lines {
+                               if id == "" {
+                                       id = anchorID(line)
+                                       w.Write([]byte(id))
+                                       w.Write(html_hq)
+                               }
                                commentEscape(w, line, true)
                        }
+                       if id == "" {
+                               w.Write(html_hq)
+                       }
                        w.Write(html_endh)
                case opPre:
                        w.Write(html_pre)