diff options
Diffstat (limited to 'doc/codewalk/codewalk.xml')
| -rw-r--r-- | doc/codewalk/codewalk.xml | 124 |
1 files changed, 0 insertions, 124 deletions
diff --git a/doc/codewalk/codewalk.xml b/doc/codewalk/codewalk.xml deleted file mode 100644 index 34e6e91938..0000000000 --- a/doc/codewalk/codewalk.xml +++ /dev/null @@ -1,124 +0,0 @@ -<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><codewalk></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:/<step/,/step>/"> - Each step in the codewalk is a <code><step></code> element - nested inside the main <code><codewalk></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="Specifying 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 “Title” 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>/<step/,/step>/</code> looks for the first instance of - <code><step</code> in the file, and then starting after that point, - looks for the first instance of <code>step></code>. - (Click on the “Steps” step above to see the highlight in action.) - Note that the <code><</code> and <code>></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>/"> - 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="https://9p.io/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> |