godoc: add codewalk support

R=adg, gri
CC=golang-dev, r
https://golang.org/cl/1008042

doc/codewalk/codewalk.css

+/*
+   Copyright 2010 The Go Authors. All rights reserved.
+   Use of this source code is governed by a BSD-style
+   license that can be found in the LICENSE file.
+*/
+
+#codewalk-main {
+  text-align: left;
+  width: 100%;
+  overflow: auto;
+}
+
+#code-display {
+  border: 0;
+  width: 100%;
+}
+
+.setting {
+  font-size: 8pt;
+  color: #888888;
+  padding: 5px;
+}
+
+.hotkey {
+  text-decoration: underline;
+}
+
+/* Style for Comments (the left-hand column) */
+
+#comment-column {
+  margin: 0pt;
+  width: 30%;
+}
+
+#comment-column.right {
+  float: right;
+}
+
+#comment-column.left {
+  float: left;
+}
+
+#comment-area {
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+.comment {
+  cursor: pointer;
+  font-size: 16px;
+  border: 2px solid #ba9836;
+  margin-bottom: 10px;
+  margin-right: 10px;  /* yes, for both .left and .right */
+}
+
+.comment:last-child {
+  margin-bottom: 0px;
+}
+
+.right .comment {
+  margin-left: 10px;
+}
+
+.right .comment.first {
+}
+
+.right .comment.last {
+}
+
+.left .comment.first {
+}
+
+.left .comment.last {
+}
+
+.comment.selected {
+  border-color: #99b2cb;
+}
+
+.right .comment.selected {
+  border-left-width: 12px;
+  margin-left: 0px;
+}
+
+.left .comment.selected {
+  border-right-width: 12px;
+  margin-right: 0px;
+}
+
+.comment-link {
+  display: none;
+}
+
+.comment-title {
+  font-size: small;
+  font-weight: bold;
+  background-color: #fffff0;
+  padding-right: 10px;
+  padding-left: 10px;
+  padding-top: 5px;
+  padding-bottom: 5px;
+}
+
+.right .comment-title {
+}
+
+.left .comment-title {
+}
+
+.comment.selected .comment-title {
+  background-color: #f8f8ff;
+}
+
+.comment-text {
+  overflow: auto;
+  padding-left: 10px;
+  padding-right: 10px;
+  padding-top: 10px;
+  padding-bottom: 5px;
+  font-size: small;
+  line-height: 1.3em;
+}
+
+.comment-text p {
+  margin-top: 0em;
+  margin-bottom: 0.5em;
+}
+
+.comment-text p:last-child {
+  margin-bottom: 0em;
+}
+
+.file-name {
+  font-size: x-small;
+  padding-top: 0px;
+  padding-bottom: 5px;
+}
+
+.hidden-filepaths .file-name {
+  display: none;
+}
+
+.path-dir {
+  color: #555;
+}
+
+.path-file {
+  color: #555;
+}
+
+
+/* Style for Code (the right-hand column) */
+
+/* Wrapper for the code column to make widths get calculated correctly */
+#code-column {
+  display: block;
+  position: relative;
+  margin: 0pt;
+  width: 70%;
+}
+
+#code-column.left {
+  float: left;
+}
+
+#code-column.right {
+  float: right;
+}
+
+#code-area {
+  background-color: #f8f8ff;
+  border: 2px solid #99b2cb;
+  padding: 5px;
+}
+
+.left #code-area {
+  margin-right: -1px;
+}
+
+.right #code-area {
+  margin-left: -1px;
+}
+
+#code-header {
+  margin-bottom: 5px;
+}
+
+#code {
+  background-color: white;
+}
+
+code {
+  font-size: 100%;
+}
+
+.codewalkhighlight {
+  font-weight: bold;
+  background-color: #f8f8ff;
+}
+
+#code-display {
+  margin-top: 0px;
+  margin-bottom: 0px;
+}
+
+#sizer {
+  position: absolute;
+  cursor: col-resize;
+  left: 0px;
+  top: 0px;
+  width: 8px;
+}
+
+/* Style for options (bottom strip) */
+
+#code-options {
+  display: none;
+}
+
+#code-options > span {
+  padding-right: 20px;
+}
+
+#code-options .selected {
+  border-bottom: 1px dotted;
+}
+
+#comment-options {
+  text-align: center;
+}
+
+div#content {
+  padding-bottom: 0em;
+}

doc/codewalk/codewalk.xml

+<codewalk title="How to Write a Codewalk">
+
+<step title="Introduction" src="doc/codewalk/codewalk.xml">
+	A codewalk is a guided tour through a piece of code.
+	It consists of a sequence of steps, each typically explaining
+	a highlighted section of code.
+	<br/><br/>
+	
+	The <a href="/cmd/godoc">godoc</a> web server translates
+	an XML file like the one in the main window pane into the HTML
+	page that you're viewing now.
+	<br/><br/>
+	
+	The codewalk with URL path <code>/doc/codewalk/</code><i>name</i>
+	is loaded from the input file <code>$GOROOT/doc/codewalk/</code><i>name</i><code>.xml</code>.
+	<br/><br/>
+	
+	This codewalk explains how to write a codewalk by examining
+	its own source code,
+	<code><a href="/doc/codewalk/codewalk.xml">$GOROOT/doc/codewalk/codewalk.xml</a></code>,
+	shown in the main window pane to the left.	
+</step>
+
+<step title="Title" src="doc/codewalk/codewalk.xml:/title=/">
+	The codewalk input file is an XML file containing a single
+	<code>&lt;codewalk&gt;</code> element.
+	That element's <code>title</code> attribute gives the title
+	that is used both on the codewalk page and in the codewalk list.
+</step>
+
+<step title="Steps" src="doc/codewalk/codewalk.xml:/&lt;step/,/step&gt;/">
+	Each step in the codewalk is a <code>&lt;step&gt;</code> element 
+	nested inside the main <code>&lt;codewalk&gt;</code>.
+	The step element's <code>title</code> attribute gives the step's title,
+	which is shown in a shaded bar above the main step text.
+	The element's <code>src</code> attribute specifies the source
+	code to show in the main window pane and, optionally, a range of 
+	lines to highlight.
+	<br/><br/>
+	
+	The first step in this codewalk does not highlight any lines:
+	its <code>src</code> is just a file name.
+</step>
+
+<step title="Specifiying a source line" src='doc/codewalk/codewalk.xml:/title="Title"/'>
+	The most complex part of the codewalk specification is
+	saying what lines to highlight.
+	Instead of ordinary line numbers,
+	the codewalk uses an address syntax that makes it possible
+	to describe the match by its content.
+	As the file gets edited, this descriptive address has a better
+	chance to continue to refer to the right section of the file.
+	<br/><br/>
+
+	To specify a source line, use a <code>src</code> attribute of the form
+	<i>filename</i><code>:</code><i>address</i>,
+	where <i>address</i> is an address in the syntax used by the text editors <i>sam</i> and <i>acme</i>.
+	<br/><br/>
+	
+	The simplest address is a single regular expression.
+	The highlighted line in the main window pane shows that the
+	address for the &ldquo;Title&rdquo; step was <code>/title=/</code>,
+	which matches the first instance of that <a href="/pkg/regexp">regular expression</a> (<code>title=</code>) in the file.
+</step>
+
+<step title="Specifying a source range" src='doc/codewalk/codewalk.xml:/title="Steps"/'>
+	To highlight a range of source lines, the simplest address to use is
+	a pair of regular expressions
+	<code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>.
+	The highlight begins with the line containing the first match for <i>regexp1</i>
+	and ends with the line containing the first match for <i>regexp2</i>
+	after the end of the match for <i>regexp1</i>.
+	Ignoring the HTML quoting, 
+	The line containing the first match for <i>regexp1</i> will be the first one highlighted,
+	and the line containing the first match for <i>regexp2</i>.
+	<br/><br/>
+	
+	The address <code>/&lt;step/,/step&gt;/</code> looks for the first instance of
+	<code>&lt;step</code> in the file, and then starting after that point,
+	looks for the first instance of <code>step&gt;</code>.
+	(Click on the &ldquo;Steps&rdquo; step above to see the highlight in action.)
+	Note that the <code>&lt;</code> and <code>&gt;</code> had to be written
+	using XML escapes in order to be valid XML.
+</step>
+
+<step title="Advanced addressing" src="doc/codewalk/codewalk.xml:/Advanced/,/step&gt;/">
+	The <code>/</code><i>regexp</i><code>/</code>
+ 	and <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>
+ 	forms suffice for most highlighting.
+ 	<br/><br/>
+
+	The full address syntax is summarized in this table
+	(an excerpt of Table II from
+	<a href="http://plan9.bell-labs.com/sys/doc/sam/sam.html">The text editor <code>sam</code></a>):
+	<br/><br/>
+
+	<table>
+	<tr><td colspan="2"><b>Simple addresses</b></td></tr>
+	<tr><td><code>#</code><i>n</i></td>
+	    <td>The empty string after character <i>n</i></td></tr>
+	<tr><td><i>n</i></td>
+	    <td>Line <i>n</i></td></tr>
+	<tr><td><code>/</code><i>regexp</i><code>/</code></td>
+	    <td>The first following match of the regular expression</td></tr>
+	<!-- not supported (yet?)
+	<tr><td><code>–/</code><i>regexp</i><code>/</code></td>
+	    <td>The first previous match of the regular expression</td></tr>
+	-->
+	<tr><td><code>$</code></td>
+	    <td>The null string at the end of the file</td></tr>
+
+	<tr><td colspan="2"><b>Compound addresses</b></td></tr>
+	<tr><td><i>a1</i><code>+</code><i>a2</i></td>
+	    <td>The address <i>a2</i> evaluated starting at the right of <i>a1</i></td></tr>
+	<tr><td><i>a1</i><code>-</code><i>a2</i></td>
+	    <td>The address <i>a2</i> evaluated in the reverse direction starting at the left of <i>a1</i></td></tr>
+	<tr><td><i>a1</i><code>,</code><i>a2</i></td>
+	    <td>From the left of <i>a1</i> to the right of <i>a2</i> (default <code>0,$</code>).</td></tr>
+	</table>
+</step>
+
+
+	
+</codewalk>

doc/style.css

@@ -45,6 +45,7 @@ span.alert {
 
 body {
   font: 13px Helvetica, Arial, sans-serif;
+  margin-bottom: 0px;
 }
 
 h1 {
@@ -102,6 +103,7 @@ div#content {
   margin-left: 20%;
   padding: 0 1em 2em 1em;
   margin-top: 0px;
+  margin-bottom: 0px;
 /*
   border-left: 2px solid #e5ecf9;
   border-right: 2px solid #e5ecf9;
@@ -156,12 +158,16 @@ div#linkList li.navhead {
 }
 
 #footer {
-  margin: 2em;
+  margin: 2em 0 0 0;
   text-align: center;
   color: #555;
   font-size: small;
 }
 
+#footer p {
+  margin: 0px;
+}
+
 #footer a {
   color: #555;
 }

lib/godoc/codewalk.html

+<!--
+	Copyright 2010 The Go Authors. All rights reserved.
+	Use of this source code is governed by a BSD-style
+	license that can be found in the LICENSE file.
+-->
+
+<script src="http://www.google.com/jsapi"></script>
+<script>google.load("jquery", "1.3.2");</script>
+<style type='text/css'>@import "/doc/codewalk/codewalk.css";</style>
+<script type="text/javascript" src="/doc/codewalk/codewalk.js"></script>
+
+<div id="codewalk-main">
+  <div class="left" id="code-column">
+    <div id='sizer'></div>
+    <div id="code-area">
+      <div id="code-header" align="center">
+        <a id="code-popout-link" href="" target="_blank">
+          <img title="View code in new window" alt="Pop Out Code" src="popout.png" style="display: block; float: right;"/>
+        </a>
+        <select id="code-selector">
+          {.repeated section File}
+          <option value="/doc/codewalk/?fileprint=/{@|html-esc}">{@|html-esc}</option>
+          {.end}
+        </select>
+      </div>
+      <div id="code">
+        <iframe class="code-display" name="code-display" id="code-display"></iframe>
+      </div>
+    </div>
+    <div id="code-options" class="setting">
+      <span>code on <a id="set-code-left" class="selected" href="#">left</a> &bull; <a id="set-code-right" href="#">right</a></span>
+      <span>code width <span id="code-column-width">70%</span></span>
+      <span>filepaths <a id="show-filepaths" class="selected" href="#">shown</a> &bull; <a id="hide-filepaths" href="#">hidden</a></span>
+    </div>
+  </div>
+  <div class="right" id="comment-column">
+    <div id="comment-area">
+      {.repeated section Step}
+      <div class="comment first last">
+        <a class="comment-link" href="/doc/codewalk/?fileprint=/{File|html-esc}&lo={Lo|html-esc}&hi={Hi|html-esc}#mark" target="code-display"></a>
+        <div class="comment-title">{Title|html-esc}</div>
+        <div class="comment-text">
+        {.section Err}
+        ERROR LOADING FILE: {Err|html-esc}<br/><br/>
+        {.end}
+        {XML}
+        </div>
+        <div class="comment-text file-name"><span class="path-file">{@|html-esc}</span></div>
+      </div>
+      {.end}
+    </div>
+    <div id="comment-options" class="setting">
+      <a id="prev-comment" href="#"><span class="hotkey">p</span>revious step</a>
+      &bull;
+      <a id="next-comment" href="#"><span class="hotkey">n</span>ext step</a>
+    </div>
+  </div>
+</div>

lib/godoc/codewalkdir.html

+<!--
+	Copyright 2010 The Go Authors. All rights reserved.
+	Use of this source code is governed by a BSD-style
+	license that can be found in the LICENSE file.
+-->
+
+<table class="layout">
+{.repeated section @}
+<tr>
+    <td><a href="{Name|html-esc}">{Name|html-esc}</a></td>
+    <td width="25">&nbsp;</td>
+    <td>{Title|html-esc}</td>
+</tr>
+{.end}
+</table>

src/cmd/godoc/Makefile

@@ -6,6 +6,7 @@ include ../../Make.$(GOARCH)
 
 TARG=godoc
 GOFILES=\
+	codewalk.go\
 	godoc.go\
 	index.go\
 	main.go\

src/cmd/godoc/godoc.go

@@ -108,8 +108,9 @@ func initHandlers() {
 func registerPublicHandlers(mux *http.ServeMux) {
 	mux.Handle(cmdHandler.pattern, &cmdHandler)
 	mux.Handle(pkgHandler.pattern, &pkgHandler)
-	mux.Handle("/search", http.HandlerFunc(search))
-	mux.Handle("/", http.HandlerFunc(serveFile))
+	mux.HandleFunc("/doc/codewalk/", codewalk)
+	mux.HandleFunc("/search", search)
+	mux.HandleFunc("/", serveFile)
 }
 
 
@@ -849,6 +850,8 @@ func readTemplate(name string) *template.Template {
 
 
 var (
+	codewalkHTML,
+	codewalkdirHTML,
 	dirlistHTML,
 	errorHTML,
 	godocHTML,
@@ -861,6 +864,8 @@ var (
 
 func readTemplates() {
 	// have to delay until after flags processing since paths depend on goroot
+	codewalkHTML = readTemplate("codewalk.html")
+	codewalkdirHTML = readTemplate("codewalkdir.html")
 	dirlistHTML = readTemplate("dirlist.html")
 	errorHTML = readTemplate("error.html")
 	godocHTML = readTemplate("godoc.html")