Text file
doc/codewalk/codewalk.xml
1 <codewalk title="How to Write a Codewalk">
2
3 <step title="Introduction" src="doc/codewalk/codewalk.xml">
4 A codewalk is a guided tour through a piece of code.
5 It consists of a sequence of steps, each typically explaining
6 a highlighted section of code.
7 <br/><br/>
8
9 The <a href="/cmd/godoc">godoc</a> web server translates
10 an XML file like the one in the main window pane into the HTML
11 page that you're viewing now.
12 <br/><br/>
13
14 The codewalk with URL path <code>/doc/codewalk/</code><i>name</i>
15 is loaded from the input file <code>$GOROOT/doc/codewalk/</code><i>name</i><code>.xml</code>.
16 <br/><br/>
17
18 This codewalk explains how to write a codewalk by examining
19 its own source code,
20 <code><a href="/doc/codewalk/codewalk.xml">$GOROOT/doc/codewalk/codewalk.xml</a></code>,
21 shown in the main window pane to the left.
22 </step>
23
24 <step title="Title" src="doc/codewalk/codewalk.xml:/title=/">
25 The codewalk input file is an XML file containing a single
26 <code><codewalk></code> element.
27 That element's <code>title</code> attribute gives the title
28 that is used both on the codewalk page and in the codewalk list.
29 </step>
30
31 <step title="Steps" src="doc/codewalk/codewalk.xml:/<step/,/step>/">
32 Each step in the codewalk is a <code><step></code> element
33 nested inside the main <code><codewalk></code>.
34 The step element's <code>title</code> attribute gives the step's title,
35 which is shown in a shaded bar above the main step text.
36 The element's <code>src</code> attribute specifies the source
37 code to show in the main window pane and, optionally, a range of
38 lines to highlight.
39 <br/><br/>
40
41 The first step in this codewalk does not highlight any lines:
42 its <code>src</code> is just a file name.
43 </step>
44
45 <step title="Specifying a source line" src='doc/codewalk/codewalk.xml:/title="Title"/'>
46 The most complex part of the codewalk specification is
47 saying what lines to highlight.
48 Instead of ordinary line numbers,
49 the codewalk uses an address syntax that makes it possible
50 to describe the match by its content.
51 As the file gets edited, this descriptive address has a better
52 chance to continue to refer to the right section of the file.
53 <br/><br/>
54
55 To specify a source line, use a <code>src</code> attribute of the form
56 <i>filename</i><code>:</code><i>address</i>,
57 where <i>address</i> is an address in the syntax used by the text editors <i>sam</i> and <i>acme</i>.
58 <br/><br/>
59
60 The simplest address is a single regular expression.
61 The highlighted line in the main window pane shows that the
62 address for the “Title” step was <code>/title=/</code>,
63 which matches the first instance of that <a href="/pkg/regexp">regular expression</a> (<code>title=</code>) in the file.
64 </step>
65
66 <step title="Specifying a source range" src='doc/codewalk/codewalk.xml:/title="Steps"/'>
67 To highlight a range of source lines, the simplest address to use is
68 a pair of regular expressions
69 <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>.
70 The highlight begins with the line containing the first match for <i>regexp1</i>
71 and ends with the line containing the first match for <i>regexp2</i>
72 after the end of the match for <i>regexp1</i>.
73 Ignoring the HTML quoting,
74 The line containing the first match for <i>regexp1</i> will be the first one highlighted,
75 and the line containing the first match for <i>regexp2</i>.
76 <br/><br/>
77
78 The address <code>/<step/,/step>/</code> looks for the first instance of
79 <code><step</code> in the file, and then starting after that point,
80 looks for the first instance of <code>step></code>.
81 (Click on the “Steps” step above to see the highlight in action.)
82 Note that the <code><</code> and <code>></code> had to be written
83 using XML escapes in order to be valid XML.
84 </step>
85
86 <step title="Advanced addressing" src="doc/codewalk/codewalk.xml:/Advanced/,/step>/">
87 The <code>/</code><i>regexp</i><code>/</code>
88 and <code>/</code><i>regexp1</i><code>/,/</code><i>regexp2</i><code>/</code>
89 forms suffice for most highlighting.
90 <br/><br/>
91
92 The full address syntax is summarized in this table
93 (an excerpt of Table II from
94 <a href="https://9p.io/sys/doc/sam/sam.html">The text editor <code>sam</code></a>):
95 <br/><br/>
96
97 <table>
98 <tr><td colspan="2"><b>Simple addresses</b></td></tr>
99 <tr><td><code>#</code><i>n</i></td>
100 <td>The empty string after character <i>n</i></td></tr>
101 <tr><td><i>n</i></td>
102 <td>Line <i>n</i></td></tr>
103 <tr><td><code>/</code><i>regexp</i><code>/</code></td>
104 <td>The first following match of the regular expression</td></tr>
105 <!-- not supported (yet?)
106 <tr><td><code>–/</code><i>regexp</i><code>/</code></td>
107 <td>The first previous match of the regular expression</td></tr>
108 -->
109 <tr><td><code>$</code></td>
110 <td>The null string at the end of the file</td></tr>
111
112 <tr><td colspan="2"><b>Compound addresses</b></td></tr>
113 <tr><td><i>a1</i><code>+</code><i>a2</i></td>
114 <td>The address <i>a2</i> evaluated starting at the right of <i>a1</i></td></tr>
115 <tr><td><i>a1</i><code>-</code><i>a2</i></td>
116 <td>The address <i>a2</i> evaluated in the reverse direction starting at the left of <i>a1</i></td></tr>
117 <tr><td><i>a1</i><code>,</code><i>a2</i></td>
118 <td>From the left of <i>a1</i> to the right of <i>a2</i> (default <code>0,$</code>).</td></tr>
119 </table>
120 </step>
121
122
123
124 </codewalk>
125
View as plain text