Codewalk: How to Write a Codewalk

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.

The godoc web server translates an XML file like the one in the main window pane into the HTML page that you're viewing now.

The codewalk with URL path /doc/codewalk/name is loaded from the input file $GOROOT/doc/codewalk/name.xml.

This codewalk explains how to write a codewalk by examining its own source code, $GOROOT/doc/codewalk/codewalk.xml, shown in the main window pane to the left.

The codewalk input file is an XML file containing a single <codewalk> element. That element's title attribute gives the title that is used both on the codewalk page and in the codewalk list.

Each step in the codewalk is a <step> element nested inside the main <codewalk>. The step element's title attribute gives the step's title, which is shown in a shaded bar above the main step text. The element's src attribute specifies the source code to show in the main window pane and, optionally, a range of lines to highlight.

The first step in this codewalk does not highlight any lines: its src is just a file name.

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.

To specify a source line, use a src attribute of the form filename:address, where address is an address in the syntax used by the text editors sam and acme.

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 /title=/, which matches the first instance of that regular expression (title=) in the file.

To highlight a range of source lines, the simplest address to use is a pair of regular expressions /regexp1/,/regexp2/. The highlight begins with the line containing the first match for regexp1 and ends with the line containing the first match for regexp2 after the end of the match for regexp1. Ignoring the HTML quoting, The line containing the first match for regexp1 will be the first one highlighted, and the line containing the first match for regexp2.

The address /<step/,/step>/ looks for the first instance of <step in the file, and then starting after that point, looks for the first instance of step>. (Click on the “Steps” step above to see the highlight in action.) Note that the < and > had to be written using XML escapes in order to be valid XML.

The /regexp/ and /regexp1/,/regexp2/ forms suffice for most highlighting.

The full address syntax is summarized in this table (an excerpt of Table II from The text editor sam):

Simple addresses
#n	The empty string after character n
n	Line n
/regexp/	The first following match of the regular expression
$	The null string at the end of the file
Compound addresses
a1+a2	The address a2 evaluated starting at the right of a1
a1-a2	The address a2 evaluated in the reverse direction starting at the left of a1
a1,a2	From the left of a1 to the right of a2 (default 0,$).