godoc: specify HTML page metadata with a JSON blob

This allows HTML pages to specify arbitrary data in a header:

<!--{
        "Title": "The page title",
        ...
}-->

replacing the old style comments:

<!-- title The page title -->

R=gri, rsc, r, bradfitz, dsymonds
CC=golang-dev
https://golang.org/cl/5532093

doc/articles/defer_panic_recover.html

@@ -1,4 +1,6 @@
-<!-- Defer, Panic, and Recover -->
+<!--{
+	"Title": "Defer, Panic, and Recover"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml articles/defer_panic_recover.tmpl

doc/articles/defer_panic_recover.tmpl

@@ -1,4 +1,6 @@
-<!-- Defer, Panic, and Recover -->
+<!--{
+	"Title": "Defer, Panic, and Recover"
+}-->
 {{donotedit}}
 <p>
 Go has the usual mechanisms for control flow: if, for, switch, goto.  It also

doc/articles/error_handling.html

@@ -1,4 +1,6 @@
-<!-- Error Handling and Go -->
+<!--{
+	"Title": "Error Handling and Go"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml articles/error_handling.tmpl

doc/articles/error_handling.tmpl

@@ -1,4 +1,6 @@
-<!-- Error Handling and Go -->
+<!--{
+	"Title": "Error Handling and Go"
+}-->
 {{donotedit}}
 <p>
 If you have written any Go code you have probably encountered the built-in

doc/articles/slices_usage_and_internals.html

@@ -1,4 +1,6 @@
-<!-- Slices: usage and internals -->
+<!--{
+	"Title": "Slices: usage and internals"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml articles/slices_usage_and_internals.tmpl

doc/articles/slices_usage_and_internals.tmpl

@@ -1,4 +1,6 @@
-<!-- Slices: usage and internals -->
+<!--{
+	"Title": "Slices: usage and internals"
+}-->
 {{donotedit}}
 
 <p>

doc/code.html

@@ -1,4 +1,6 @@
-<!-- How to Write Go Code -->
+<!--{
+	"Title": "How to Write Go Code"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 

doc/codereview_with_mq.html

@@ -1,4 +1,6 @@
-<!-- Using Mercurial Queues with Codereview -->
+<!--{
+	"Title": "Using Mercurial Queues with Codereview"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 

doc/community.html

@@ -1,4 +1,6 @@
-<!-- title Community -->
+<!--{
+	"Title": "Community"
+}-->
 
 <div class="left-column">
 

doc/contrib.html

@@ -1,4 +1,6 @@
-<!-- title Contributing -->
+<!--{
+	"Title": "Contributing"
+}-->
 
 <div class="left-column">
 

doc/contribute.html

@@ -1,4 +1,6 @@
-<!-- Contribution Guidelines -->
+<!--{
+	"Title": "Contribution Guidelines"
+}-->
 
 <h2 id="Introduction">Introduction</h2>
 

doc/debugging_with_gdb.html

@@ -1,4 +1,6 @@
-<!-- title Debugging Go Code with GDB -->
+<!--{
+	"Title": "Debugging Go Code with GDB"
+}-->
 
 <p><i>
 This applies to the 6g toolchain. Gccgo has native gdb support. Besides this

doc/docs.html

@@ -1,4 +1,6 @@
-<!-- title Documentation -->
+<!--{
+	"Title": "Documentation"
+}-->
 
 <div class="left-column">
 

doc/effective_go.html

@@ -1,4 +1,6 @@
-<!-- Effective Go -->
+<!--{
+	"Title": "Effective Go"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml effective_go.tmpl

doc/effective_go.tmpl

@@ -1,4 +1,6 @@
-<!-- Effective Go -->
+<!--{
+	"Title": "Effective Go"
+}-->
 {{donotedit}}
 
 <h2 id="introduction">Introduction</h2>

doc/gccgo_contribute.html

@@ -1,4 +1,6 @@
-<!-- Contributing to the gccgo frontend -->
+<!--{
+	"Title": "Contributing to the gccgo frontend"
+}-->
 
 <h2>Introduction</h2>
 

doc/gccgo_install.html

@@ -1,4 +1,6 @@
-<!-- Setting up and using gccgo -->
+<!--{
+	"Title": "Setting up and using gccgo"
+}-->
 
 <p>
 This document explains how to use <code>gccgo</code>, a compiler for

doc/go1.html

@@ -1,4 +1,6 @@
-<!-- Go 1 Release Notes -->
+<!--{
+	"Title": "Go 1 Release Notes"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml go1.tmpl

doc/go1.tmpl

@@ -1,4 +1,6 @@
-<!-- Go 1 Release Notes -->
+<!--{
+	"Title": "Go 1 Release Notes"
+}-->
 {{donotedit}}
 
 <h2 id="introduction">Introduction to Go 1</h2>

doc/go_faq.html

@@ -1,4 +1,6 @@
-<!-- FAQ -->
+<!--{
+	"Title": "FAQ"
+}-->
 
 <h2 id="Origins">Origins</h2>
 

doc/go_for_cpp_programmers.html

@@ -1,4 +1,6 @@
-<!-- Go For C++ Programmers -->
+<!--{
+	"Title": "Go For C++ Programmers"
+}-->
 
 <p>
 Go is a systems programming language intended to be a general-purpose

doc/go_mem.html

@@ -1,5 +1,7 @@
-<!-- The Go Memory Model -->
+<!--{
-<!-- subtitle Version of June 10, 2011 -->
+	"Title": "The Go Memory Model",
+	"Subtitle": "Version of June 10, 2011"
+}-->
 
 <style>
 p.rule {

doc/go_spec.html

@@ -1,5 +1,7 @@
-<!-- title The Go Programming Language Specification -->
+<!--{
-<!-- subtitle Version of January 13, 2012 -->
+	"Title": "The Go Programming Language Specification",
+	"Subtitle": "Version of January 13, 2012"
+}-->
 
 <!--
 TODO

doc/go_tutorial.html

@@ -1,4 +1,6 @@
-<!-- A Tutorial for the Go Programming Language -->
+<!--{
+	"Title": "A Tutorial for the Go Programming Language"
+}-->
 <!--
   DO NOT EDIT: created by
     tmpltohtml go_tutorial.tmpl

doc/go_tutorial.tmpl

@@ -1,4 +1,6 @@
-<!-- A Tutorial for the Go Programming Language -->
+<!--{
+	"Title": "A Tutorial for the Go Programming Language"
+}-->
 {{donotedit}}
 
 <h2>Introduction</h2>

doc/install.html

@@ -1,4 +1,6 @@
-<!-- Getting Started -->
+<!--{
+	"Title": "Getting Started"
+}-->
 
 <h2 id="introduction">Introduction</h2>
 

doc/playground.html

@@ -1,4 +1,6 @@
-<!-- About the Go Playground -->
+<!--{
+	"Title": "About the Go Playground"
+}-->
 
 <div class="left-column">
 <p>

src/cmd/godoc/godoc.go

@@ -6,6 +6,7 @@ package main
 
 import (
 	"bytes"
+	"encoding/json"
 	"flag"
 	"fmt"
 	"go/ast"
@@ -692,17 +693,14 @@ func serveText(w http.ResponseWriter, text []byte) {
 // Files
 
 var (
-	titleRx        = regexp.MustCompile(`<!-- title ([^\-]*)-->`)
+	doctype   = []byte("<!DOCTYPE ")
-	subtitleRx     = regexp.MustCompile(`<!-- subtitle ([^\-]*)-->`)
+	jsonStart = []byte("<!--{")
-	firstCommentRx = regexp.MustCompile(`<!--([^\-]*)-->`)
+	jsonEnd   = []byte("}-->")
 )
 
-func extractString(src []byte, rx *regexp.Regexp) (s string) {
+type Metadata struct {
-	m := rx.FindSubmatch(src)
+	Title    string
-	if m != nil {
+	Subtitle string
-		s = strings.TrimSpace(string(m[1]))
-	}
-	return
 }
 
 func serveHTMLDoc(w http.ResponseWriter, r *http.Request, abspath, relpath string) {
@@ -716,11 +714,23 @@ func serveHTMLDoc(w http.ResponseWriter, r *http.Request, abspath, relpath strin
 
 	// if it begins with "<!DOCTYPE " assume it is standalone
 	// html that doesn't need the template wrapping.
-	if bytes.HasPrefix(src, []byte("<!DOCTYPE ")) {
+	if bytes.HasPrefix(src, doctype) {
 		w.Write(src)
 		return
 	}
 
+	// if it begins with a JSON blob, read in the metadata.
+	var meta Metadata
+	if bytes.HasPrefix(src, jsonStart) {
+		if end := bytes.Index(src, jsonEnd); end > -1 {
+			b := src[len(jsonStart)-1 : end+1] // drop leading <!-- and include trailing }
+			if err := json.Unmarshal(b, &meta); err != nil {
+				log.Printf("decoding metadata for %s: %v", relpath, err)
+			}
+			src = src[end+len(jsonEnd):]
+		}
+	}
+
 	// if it's the language spec, add tags to EBNF productions
 	if strings.HasSuffix(abspath, "go_spec.html") {
 		var buf bytes.Buffer
@@ -728,15 +738,7 @@ func serveHTMLDoc(w http.ResponseWriter, r *http.Request, abspath, relpath strin
 		src = buf.Bytes()
 	}
 
-	// get title and subtitle, if any
+	servePage(w, meta.Title, meta.Subtitle, "", src)
-	title := extractString(src, titleRx)
-	if title == "" {
-		// no title found; try first comment for backward-compatibility
-		title = extractString(src, firstCommentRx)
-	}
-	subtitle := extractString(src, subtitleRx)
-
-	servePage(w, title, subtitle, "", src)
 }
 
 func applyTemplate(t *template.Template, name string, data interface{}) []byte {