diff options
Diffstat (limited to 'doc/codewalk/codewalk.xml')
| -rw-r--r-- | doc/codewalk/codewalk.xml | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/codewalk/codewalk.xml b/doc/codewalk/codewalk.xml new file mode 100644 index 000000000..9cd8361e8 --- /dev/null +++ b/doc/codewalk/codewalk.xml @@ -0,0 +1,124 @@ +<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><codewalk></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:/<step/,/step>/"> + Each step in the codewalk is a <code><step></code> element + nested inside the main <code><codewalk></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 “Title” 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>/<step/,/step>/</code> looks for the first instance of + <code><step</code> in the file, and then starting after that point, + looks for the first instance of <code>step></code>. + (Click on the “Steps” step above to see the highlight in action.) + Note that the <code><</code> and <code>></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>/"> + 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> |