go/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>