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

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; }

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}}

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)