Russ Cox | 2a591bd | 2010-04-26 22:35:12 -0700 | [diff] [blame] | 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 | |
Shenghou Ma | 26f43a0 | 2013-10-12 18:40:41 -0400 | [diff] [blame] | 45 | <step title="Specifying a source line" src='doc/codewalk/codewalk.xml:/title="Title"/'> |
Russ Cox | 2a591bd | 2010-04-26 22:35:12 -0700 | [diff] [blame] | 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 |
Andrew Gerrand | 39304eb | 2016-02-05 09:43:46 +1100 | [diff] [blame] | 94 | <a href="https://9p.io/sys/doc/sam/sam.html">The text editor <code>sam</code></a>): |
Russ Cox | 2a591bd | 2010-04-26 22:35:12 -0700 | [diff] [blame] | 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> |