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
