1.1 --- a/en/ch10-template.xml	Thu Mar 19 20:54:12 2009 -0700
     1.2 +++ b/en/ch10-template.xml	Thu Mar 19 21:18:52 2009 -0700
     1.3 @@ -4,7 +4,7 @@
     1.4    <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
     1.5    <title>Customising the output of Mercurial</title>
     1.6  
     1.7 -  <para>Mercurial provides a powerful mechanism to let you control how
     1.8 +  <para id="x_578">Mercurial provides a powerful mechanism to let you control how
     1.9      it displays information.  The mechanism is based on templates.
    1.10      You can use templates to generate specific output for a single
    1.11      command, or to customise the entire appearance of the built-in web
    1.12 @@ -13,37 +13,37 @@
    1.13    <sect1 id="sec:style">
    1.14      <title>Using precanned output styles</title>
    1.15  
    1.16 -    <para>Packaged with Mercurial are some output styles that you can
    1.17 +    <para id="x_579">Packaged with Mercurial are some output styles that you can
    1.18        use immediately.  A style is simply a precanned template that
    1.19        someone wrote and installed somewhere that Mercurial can
    1.20        find.</para>
    1.21  
    1.22 -    <para>Before we take a look at Mercurial's bundled styles, let's
    1.23 +    <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
    1.24        review its normal output.</para>
    1.25  
    1.26      &interaction.template.simple.normal;
    1.27  
    1.28 -    <para>This is somewhat informative, but it takes up a lot of
    1.29 +    <para id="x_57b">This is somewhat informative, but it takes up a lot of
    1.30        space&emdash;five lines of output per changeset.  The
    1.31        <literal>compact</literal> style reduces this to three lines,
    1.32        presented in a sparse manner.</para>
    1.33  
    1.34      &interaction.template.simple.compact;
    1.35  
    1.36 -    <para>The <literal>changelog</literal> style hints at the
    1.37 +    <para id="x_57c">The <literal>changelog</literal> style hints at the
    1.38        expressive power of Mercurial's templating engine.  This style
    1.39        attempts to follow the GNU Project's changelog
    1.40        guidelines<citation>web:changelog</citation>.</para>
    1.41  
    1.42      &interaction.template.simple.changelog;
    1.43  
    1.44 -    <para>You will not be shocked to learn that Mercurial's default
    1.45 +    <para id="x_57d">You will not be shocked to learn that Mercurial's default
    1.46        output style is named <literal>default</literal>.</para>
    1.47  
    1.48      <sect2>
    1.49        <title>Setting a default style</title>
    1.50  
    1.51 -      <para>You can modify the output style that Mercurial will use
    1.52 +      <para id="x_57e">You can modify the output style that Mercurial will use
    1.53  	for every command by editing your <filename
    1.54  	  role="special">~/.hgrc</filename> file, naming the style
    1.55  	you would prefer to use.</para>
    1.56 @@ -51,7 +51,7 @@
    1.57        <programlisting>[ui]
    1.58  style = compact</programlisting>
    1.59  
    1.60 -      <para>If you write a style of your own, you can use it by either
    1.61 +      <para id="x_57f">If you write a style of your own, you can use it by either
    1.62  	providing the path to your style file, or copying your style
    1.63  	file into a location where Mercurial can find it (typically
    1.64  	the <literal>templates</literal> subdirectory of your
    1.65 @@ -62,14 +62,14 @@
    1.66    <sect1>
    1.67      <title>Commands that support styles and templates</title>
    1.68  
    1.69 -    <para>All of Mercurial's
    1.70 +    <para id="x_580">All of Mercurial's
    1.71        <quote><literal>log</literal>-like</quote> commands let you use
    1.72        styles and templates: <command role="hg-cmd">hg
    1.73  	incoming</command>, <command role="hg-cmd">hg log</command>,
    1.74        <command role="hg-cmd">hg outgoing</command>, and <command
    1.75  	role="hg-cmd">hg tip</command>.</para>
    1.76  
    1.77 -    <para>As I write this manual, these are so far the only commands
    1.78 +    <para id="x_581">As I write this manual, these are so far the only commands
    1.79        that support styles and templates.  Since these are the most
    1.80        important commands that need customisable output, there has been
    1.81        little pressure from the Mercurial user community to add style
    1.82 @@ -79,22 +79,22 @@
    1.83    <sect1>
    1.84      <title>The basics of templating</title>
    1.85  
    1.86 -    <para>At its simplest, a Mercurial template is a piece of text.
    1.87 +    <para id="x_582">At its simplest, a Mercurial template is a piece of text.
    1.88        Some of the text never changes, while other parts are
    1.89        <emphasis>expanded</emphasis>, or replaced with new text, when
    1.90        necessary.</para>
    1.91  
    1.92 -    <para>Before we continue, let's look again at a simple example of
    1.93 +    <para id="x_583">Before we continue, let's look again at a simple example of
    1.94        Mercurial's normal output.</para>
    1.95  
    1.96      &interaction.template.simple.normal;
    1.97  
    1.98 -    <para>Now, let's run the same command, but using a template to
    1.99 +    <para id="x_584">Now, let's run the same command, but using a template to
   1.100        change its output.</para>
   1.101  
   1.102      &interaction.template.simple.simplest;
   1.103  
   1.104 -    <para>The example above illustrates the simplest possible
   1.105 +    <para id="x_585">The example above illustrates the simplest possible
   1.106        template; it's just a piece of static text, printed once for
   1.107        each changeset.  The <option
   1.108  	role="hg-opt-log">--template</option> option to the <command
   1.109 @@ -102,7 +102,7 @@
   1.110        the given text as the template when printing each
   1.111        changeset.</para>
   1.112  
   1.113 -    <para>Notice that the template string above ends with the text
   1.114 +    <para id="x_586">Notice that the template string above ends with the text
   1.115        <quote><literal>\n</literal></quote>.  This is an
   1.116        <emphasis>escape sequence</emphasis>, telling Mercurial to print
   1.117        a newline at the end of each template item.  If you omit this
   1.118 @@ -110,13 +110,13 @@
   1.119        section <xref linkend="sec:template:escape"/> for more details
   1.120        of escape sequences.</para>
   1.121  
   1.122 -    <para>A template that prints a fixed string of text all the time
   1.123 +    <para id="x_587">A template that prints a fixed string of text all the time
   1.124        isn't very useful; let's try something a bit more
   1.125        complex.</para>
   1.126  
   1.127      &interaction.template.simple.simplesub;
   1.128  
   1.129 -    <para>As you can see, the string
   1.130 +    <para id="x_588">As you can see, the string
   1.131        <quote><literal>{desc}</literal></quote> in the template has
   1.132        been replaced in the output with the description of each
   1.133        changeset.  Every time Mercurial finds text enclosed in curly
   1.134 @@ -131,21 +131,21 @@
   1.135    <sect1 id="sec:template:keyword">
   1.136      <title>Common template keywords</title>
   1.137  
   1.138 -    <para>You can start writing simple templates immediately using the
   1.139 +    <para id="x_589">You can start writing simple templates immediately using the
   1.140        keywords below.</para>
   1.141  
   1.142      <itemizedlist>
   1.143 -      <listitem><para><literal
   1.144 +      <listitem><para id="x_58a"><literal
   1.145  	    role="template-keyword">author</literal>: String.  The
   1.146  	  unmodified author of the changeset.</para>
   1.147        </listitem>
   1.148 -      <listitem><para><literal
   1.149 +      <listitem><para id="x_58b"><literal
   1.150  	    role="template-keyword">branches</literal>: String.  The
   1.151  	  name of the branch on which the changeset was committed.
   1.152  	  Will be empty if the branch name was
   1.153  	  <literal>default</literal>.</para>
   1.154        </listitem>
   1.155 -      <listitem><para><literal role="template-keyword">date</literal>:
   1.156 +      <listitem><para id="x_58c"><literal role="template-keyword">date</literal>:
   1.157  	  Date information.  The date when the changeset was
   1.158  	  committed.  This is <emphasis>not</emphasis> human-readable;
   1.159  	  you must pass it through a filter that will render it
   1.160 @@ -156,45 +156,45 @@
   1.161  	  1, 1970); the second is the offset of the committer's
   1.162  	  timezone from UTC, in seconds.</para>
   1.163        </listitem>
   1.164 -      <listitem><para><literal role="template-keyword">desc</literal>:
   1.165 +      <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>:
   1.166  	  String.  The text of the changeset description.</para>
   1.167        </listitem>
   1.168 -      <listitem><para><literal
   1.169 +      <listitem><para id="x_58e"><literal
   1.170  	    role="template-keyword">files</literal>: List of strings.
   1.171  	  All files modified, added, or removed by this
   1.172  	  changeset.</para>
   1.173        </listitem>
   1.174 -      <listitem><para><literal
   1.175 +      <listitem><para id="x_58f"><literal
   1.176  	    role="template-keyword">file_adds</literal>: List of
   1.177  	  strings.  Files added by this changeset.</para>
   1.178        </listitem>
   1.179 -      <listitem><para><literal
   1.180 +      <listitem><para id="x_590"><literal
   1.181  	    role="template-keyword">file_dels</literal>: List of
   1.182  	  strings.  Files removed by this changeset.</para>
   1.183        </listitem>
   1.184 -      <listitem><para><literal role="template-keyword">node</literal>:
   1.185 +      <listitem><para id="x_591"><literal role="template-keyword">node</literal>:
   1.186  	  String.  The changeset identification hash, as a
   1.187  	  40-character hexadecimal string.</para>
   1.188        </listitem>
   1.189 -      <listitem><para><literal
   1.190 +      <listitem><para id="x_592"><literal
   1.191  	    role="template-keyword">parents</literal>: List of
   1.192  	  strings.  The parents of the changeset.</para>
   1.193        </listitem>
   1.194 -      <listitem><para><literal role="template-keyword">rev</literal>:
   1.195 +      <listitem><para id="x_593"><literal role="template-keyword">rev</literal>:
   1.196  	  Integer.  The repository-local changeset revision
   1.197  	  number.</para>
   1.198        </listitem>
   1.199 -      <listitem><para><literal role="template-keyword">tags</literal>:
   1.200 +      <listitem><para id="x_594"><literal role="template-keyword">tags</literal>:
   1.201  	  List of strings.  Any tags associated with the
   1.202  	  changeset.</para>
   1.203        </listitem></itemizedlist>
   1.204  
   1.205 -    <para>A few simple experiments will show us what to expect when we
   1.206 +    <para id="x_595">A few simple experiments will show us what to expect when we
   1.207        use these keywords; you can see the results below.</para>
   1.208  
   1.209  &interaction.template.simple.keywords;
   1.210  
   1.211 -    <para>As we noted above, the date keyword does not produce
   1.212 +    <para id="x_596">As we noted above, the date keyword does not produce
   1.213        human-readable output, so we must treat it specially.  This
   1.214        involves using a <emphasis>filter</emphasis>, about which more
   1.215        in section <xref
   1.216 @@ -206,39 +206,39 @@
   1.217    <sect1 id="sec:template:escape">
   1.218      <title>Escape sequences</title>
   1.219  
   1.220 -    <para>Mercurial's templating engine recognises the most commonly
   1.221 +    <para id="x_597">Mercurial's templating engine recognises the most commonly
   1.222        used escape sequences in strings.  When it sees a backslash
   1.223        (<quote><literal>\</literal></quote>) character, it looks at the
   1.224        following character and substitutes the two characters with a
   1.225        single replacement, as described below.</para>
   1.226  
   1.227      <itemizedlist>
   1.228 -      <listitem><para><literal>\</literal>:
   1.229 +      <listitem><para id="x_598"><literal>\</literal>:
   1.230  	  Backslash, <quote><literal>\</literal></quote>, ASCII
   1.231  	  134.</para>
   1.232        </listitem>
   1.233 -      <listitem><para><literal>\n</literal>: Newline,
   1.234 +      <listitem><para id="x_599"><literal>\n</literal>: Newline,
   1.235  	  ASCII 12.</para>
   1.236        </listitem>
   1.237 -      <listitem><para><literal>\r</literal>: Carriage
   1.238 +      <listitem><para id="x_59a"><literal>\r</literal>: Carriage
   1.239  	  return, ASCII 15.</para>
   1.240        </listitem>
   1.241 -      <listitem><para><literal>\t</literal>: Tab, ASCII
   1.242 +      <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII
   1.243  	  11.</para>
   1.244        </listitem>
   1.245 -      <listitem><para><literal>\v</literal>: Vertical
   1.246 +      <listitem><para id="x_59c"><literal>\v</literal>: Vertical
   1.247  	  tab, ASCII 13.</para>
   1.248        </listitem>
   1.249 -      <listitem><para><literal>{</literal>: Open curly
   1.250 +      <listitem><para id="x_59d"><literal>{</literal>: Open curly
   1.251  	  brace, <quote><literal>{</literal></quote>, ASCII
   1.252  	  173.</para>
   1.253        </listitem>
   1.254 -      <listitem><para><literal>}</literal>: Close curly
   1.255 +      <listitem><para id="x_59e"><literal>}</literal>: Close curly
   1.256  	  brace, <quote><literal>}</literal></quote>, ASCII
   1.257  	  175.</para>
   1.258        </listitem></itemizedlist>
   1.259  
   1.260 -    <para>As indicated above, if you want the expansion of a template
   1.261 +    <para id="x_59f">As indicated above, if you want the expansion of a template
   1.262        to contain a literal <quote><literal>\</literal></quote>,
   1.263        <quote><literal>{</literal></quote>, or
   1.264        <quote><literal>{</literal></quote> character, you must escape
   1.265 @@ -248,35 +248,35 @@
   1.266    <sect1 id="sec:template:filter">
   1.267      <title>Filtering keywords to change their results</title>
   1.268  
   1.269 -    <para>Some of the results of template expansion are not
   1.270 +    <para id="x_5a0">Some of the results of template expansion are not
   1.271        immediately easy to use.  Mercurial lets you specify an optional
   1.272        chain of <emphasis>filters</emphasis> to modify the result of
   1.273        expanding a keyword.  You have already seen a common filter,
   1.274        <literal role="template-kw-filt-date">isodate</literal>, in
   1.275        action above, to make a date readable.</para>
   1.276  
   1.277 -    <para>Below is a list of the most commonly used filters that
   1.278 +    <para id="x_5a1">Below is a list of the most commonly used filters that
   1.279        Mercurial supports.  While some filters can be applied to any
   1.280        text, others can only be used in specific circumstances.  The
   1.281        name of each filter is followed first by an indication of where
   1.282        it can be used, then a description of its effect.</para>
   1.283  
   1.284      <itemizedlist>
   1.285 -      <listitem><para><literal
   1.286 +      <listitem><para id="x_5a2"><literal
   1.287  	    role="template-filter">addbreaks</literal>: Any text. Add
   1.288  	  an XHTML <quote><literal>&lt;br/&gt;</literal></quote> tag
   1.289  	  before the end of every line except the last.  For example,
   1.290  	  <quote><literal>foo\nbar</literal></quote> becomes
   1.291  	  <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.</para>
   1.292        </listitem>
   1.293 -      <listitem><para><literal
   1.294 +      <listitem><para id="x_5a3"><literal
   1.295  	    role="template-kw-filt-date">age</literal>: <literal
   1.296  	    role="template-keyword">date</literal> keyword.  Render
   1.297  	  the age of the date, relative to the current time.  Yields a
   1.298  	  string like <quote><literal>10
   1.299  	      minutes</literal></quote>.</para>
   1.300        </listitem>
   1.301 -      <listitem><para><literal
   1.302 +      <listitem><para id="x_5a4"><literal
   1.303  	    role="template-filter">basename</literal>: Any text, but
   1.304  	  most useful for the <literal
   1.305  	    role="template-keyword">files</literal> keyword and its
   1.306 @@ -285,7 +285,7 @@
   1.307  	  <quote><literal>foo/bar/baz</literal></quote> becomes
   1.308  	  <quote><literal>baz</literal></quote>.</para>
   1.309        </listitem>
   1.310 -      <listitem><para><literal
   1.311 +      <listitem><para id="x_5a5"><literal
   1.312  	    role="template-kw-filt-date">date</literal>: <literal
   1.313  	    role="template-keyword">date</literal> keyword.  Render a
   1.314  	  date in a similar format to the Unix <literal
   1.315 @@ -293,7 +293,7 @@
   1.316  	  timezone included.  Yields a string like <quote><literal>Mon
   1.317  	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
   1.318        </listitem>
   1.319 -      <listitem><para><literal
   1.320 +      <listitem><para id="x_5a6"><literal
   1.321  	    role="template-kw-filt-author">domain</literal>: Any text,
   1.322  	  but most useful for the <literal
   1.323  	    role="template-keyword">author</literal> keyword.  Finds
   1.324 @@ -303,7 +303,7 @@
   1.325  	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.326  	  <quote><literal>serpentine.com</literal></quote>.</para>
   1.327        </listitem>
   1.328 -      <listitem><para><literal
   1.329 +      <listitem><para id="x_5a7"><literal
   1.330  	    role="template-kw-filt-author">email</literal>: Any text,
   1.331  	  but most useful for the <literal
   1.332  	    role="template-keyword">author</literal> keyword.  Extract
   1.333 @@ -312,7 +312,7 @@
   1.334  	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.335  	  <quote><literal>bos@serpentine.com</literal></quote>.</para>
   1.336        </listitem>
   1.337 -      <listitem><para><literal
   1.338 +      <listitem><para id="x_5a8"><literal
   1.339  	    role="template-filter">escape</literal>: Any text.
   1.340  	  Replace the special XML/XHTML characters
   1.341  	  <quote><literal>&amp;</literal></quote>,
   1.342 @@ -320,7 +320,7 @@
   1.343  	  <quote><literal>&gt;</literal></quote> with XML
   1.344  	  entities.</para>
   1.345        </listitem>
   1.346 -      <listitem><para><literal
   1.347 +      <listitem><para id="x_5a9"><literal
   1.348  	    role="template-filter">fill68</literal>: Any text.  Wrap
   1.349  	  the text to fit in 68 columns.  This is useful before you
   1.350  	  pass text through the <literal
   1.351 @@ -328,30 +328,30 @@
   1.352  	  still want it to fit in an 80-column fixed-font
   1.353  	  window.</para>
   1.354        </listitem>
   1.355 -      <listitem><para><literal
   1.356 +      <listitem><para id="x_5aa"><literal
   1.357  	    role="template-filter">fill76</literal>: Any text.  Wrap
   1.358  	  the text to fit in 76 columns.</para>
   1.359        </listitem>
   1.360 -      <listitem><para><literal
   1.361 +      <listitem><para id="x_5ab"><literal
   1.362  	    role="template-filter">firstline</literal>: Any text.
   1.363  	  Yield the first line of text, without any trailing
   1.364  	  newlines.</para>
   1.365        </listitem>
   1.366 -      <listitem><para><literal
   1.367 +      <listitem><para id="x_5ac"><literal
   1.368  	    role="template-kw-filt-date">hgdate</literal>: <literal
   1.369  	    role="template-keyword">date</literal> keyword.  Render
   1.370  	  the date as a pair of readable numbers.  Yields a string
   1.371  	  like <quote><literal>1157407993
   1.372  	      25200</literal></quote>.</para>
   1.373        </listitem>
   1.374 -      <listitem><para><literal
   1.375 +      <listitem><para id="x_5ad"><literal
   1.376  	    role="template-kw-filt-date">isodate</literal>: <literal
   1.377  	    role="template-keyword">date</literal> keyword.  Render
   1.378  	  the date as a text string in ISO 8601 format.  Yields a
   1.379  	  string like <quote><literal>2006-09-04 15:13:13
   1.380  	      -0700</literal></quote>.</para>
   1.381        </listitem>
   1.382 -      <listitem><para><literal
   1.383 +      <listitem><para id="x_5ae"><literal
   1.384  	    role="template-filter">obfuscate</literal>: Any text, but
   1.385  	  most useful for the <literal
   1.386  	    role="template-keyword">author</literal> keyword.  Yield
   1.387 @@ -359,7 +359,7 @@
   1.388  	  helps to defeat some particularly stupid screen-scraping
   1.389  	  email harvesting spambots.</para>
   1.390        </listitem>
   1.391 -      <listitem><para><literal
   1.392 +      <listitem><para id="x_5af"><literal
   1.393  	    role="template-kw-filt-author">person</literal>: Any text,
   1.394  	  but most useful for the <literal
   1.395  	    role="template-keyword">author</literal> keyword.  Yield
   1.396 @@ -368,41 +368,41 @@
   1.397  	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.398  	  <quote><literal>Bryan O'Sullivan</literal></quote>.</para>
   1.399        </listitem>
   1.400 -      <listitem><para><literal
   1.401 +      <listitem><para id="x_5b0"><literal
   1.402  	    role="template-kw-filt-date">rfc822date</literal>:
   1.403  	  <literal role="template-keyword">date</literal> keyword.
   1.404  	  Render a date using the same format used in email headers.
   1.405  	  Yields a string like <quote><literal>Mon, 04 Sep 2006
   1.406  	      15:13:13 -0700</literal></quote>.</para>
   1.407        </listitem>
   1.408 -      <listitem><para><literal
   1.409 +      <listitem><para id="x_5b1"><literal
   1.410  	    role="template-kw-filt-node">short</literal>: Changeset
   1.411  	  hash.  Yield the short form of a changeset hash, i.e. a
   1.412  	  12-character hexadecimal string.</para>
   1.413        </listitem>
   1.414 -      <listitem><para><literal
   1.415 +      <listitem><para id="x_5b2"><literal
   1.416  	    role="template-kw-filt-date">shortdate</literal>: <literal
   1.417  	    role="template-keyword">date</literal> keyword.  Render
   1.418  	  the year, month, and day of the date.  Yields a string like
   1.419  	  <quote><literal>2006-09-04</literal></quote>.</para>
   1.420        </listitem>
   1.421 -      <listitem><para><literal role="template-filter">strip</literal>:
   1.422 +      <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>:
   1.423  	  Any text.  Strip all leading and trailing whitespace from
   1.424  	  the string.</para>
   1.425        </listitem>
   1.426 -      <listitem><para><literal
   1.427 +      <listitem><para id="x_5b4"><literal
   1.428  	    role="template-filter">tabindent</literal>: Any text.
   1.429  	  Yield the text, with every line except the first starting
   1.430  	  with a tab character.</para>
   1.431        </listitem>
   1.432 -      <listitem><para><literal
   1.433 +      <listitem><para id="x_5b5"><literal
   1.434  	    role="template-filter">urlescape</literal>: Any text.
   1.435  	  Escape all characters that are considered
   1.436  	  <quote>special</quote> by URL parsers.  For example,
   1.437  	  <literal>foo bar</literal> becomes
   1.438  	  <literal>foo%20bar</literal>.</para>
   1.439        </listitem>
   1.440 -      <listitem><para><literal
   1.441 +      <listitem><para id="x_5b6"><literal
   1.442  	    role="template-kw-filt-author">user</literal>: Any text,
   1.443  	  but most useful for the <literal
   1.444  	    role="template-keyword">author</literal> keyword.  Return
   1.445 @@ -415,7 +415,7 @@
   1.446  &interaction.template.simple.manyfilters;
   1.447  
   1.448      <note>
   1.449 -      <para>  If you try to apply a filter to a piece of data that it
   1.450 +      <para id="x_5b7">  If you try to apply a filter to a piece of data that it
   1.451  	cannot process, Mercurial will fail and print a Python
   1.452  	exception.  For example, trying to run the output of the
   1.453  	<literal role="template-keyword">desc</literal> keyword into
   1.454 @@ -426,7 +426,7 @@
   1.455      <sect2>
   1.456        <title>Combining filters</title>
   1.457  
   1.458 -      <para>It is easy to combine filters to yield output in the form
   1.459 +      <para id="x_5b8">It is easy to combine filters to yield output in the form
   1.460  	you would like.  The following chain of filters tidies up a
   1.461  	description, then makes sure that it fits cleanly into 68
   1.462  	columns, then indents it by a further 8 characters (at least
   1.463 @@ -435,13 +435,13 @@
   1.464  
   1.465        &interaction.template.simple.combine;
   1.466  
   1.467 -      <para>Note the use of <quote><literal>\t</literal></quote> (a
   1.468 +      <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a
   1.469  	tab character) in the template to force the first line to be
   1.470  	indented; this is necessary since <literal
   1.471  	  role="template-keyword">tabindent</literal> indents all
   1.472  	lines <emphasis>except</emphasis> the first.</para>
   1.473  
   1.474 -      <para>Keep in mind that the order of filters in a chain is
   1.475 +      <para id="x_5ba">Keep in mind that the order of filters in a chain is
   1.476  	significant.  The first filter is applied to the result of the
   1.477  	keyword; the second to the result of the first filter; and so
   1.478  	on.  For example, using <literal>fill68|tabindent</literal>
   1.479 @@ -454,12 +454,12 @@
   1.480    <sect1>
   1.481      <title>From templates to styles</title>
   1.482  
   1.483 -    <para>A command line template provides a quick and simple way to
   1.484 +    <para id="x_5bb">A command line template provides a quick and simple way to
   1.485        format some output.  Templates can become verbose, though, and
   1.486        it's useful to be able to give a template a name.  A style file
   1.487        is a template with a name, stored in a file.</para>
   1.488  
   1.489 -    <para>More than that, using a style file unlocks the power of
   1.490 +    <para id="x_5bc">More than that, using a style file unlocks the power of
   1.491        Mercurial's templating engine in ways that are not possible
   1.492        using the command line <option
   1.493  	role="hg-opt-log">--template</option> option.</para>
   1.494 @@ -467,11 +467,11 @@
   1.495      <sect2>
   1.496        <title>The simplest of style files</title>
   1.497  
   1.498 -      <para>Our simple style file contains just one line:</para>
   1.499 +      <para id="x_5bd">Our simple style file contains just one line:</para>
   1.500  
   1.501        &interaction.template.simple.rev;
   1.502  
   1.503 -      <para>This tells Mercurial, <quote>if you're printing a
   1.504 +      <para id="x_5be">This tells Mercurial, <quote>if you're printing a
   1.505  	  changeset, use the text on the right as the
   1.506  	  template</quote>.</para>
   1.507  
   1.508 @@ -479,38 +479,38 @@
   1.509      <sect2>
   1.510        <title>Style file syntax</title>
   1.511  
   1.512 -      <para>The syntax rules for a style file are simple.</para>
   1.513 +      <para id="x_5bf">The syntax rules for a style file are simple.</para>
   1.514  
   1.515        <itemizedlist>
   1.516 -	<listitem><para>The file is processed one line at a
   1.517 +	<listitem><para id="x_5c0">The file is processed one line at a
   1.518  	    time.</para>
   1.519  	</listitem>
   1.520 -	<listitem><para>Leading and trailing white space are
   1.521 +	<listitem><para id="x_5c1">Leading and trailing white space are
   1.522  	    ignored.</para>
   1.523  	</listitem>
   1.524 -	<listitem><para>Empty lines are skipped.</para>
   1.525 -	</listitem>
   1.526 -	<listitem><para>If a line starts with either of the characters
   1.527 +	<listitem><para id="x_5c2">Empty lines are skipped.</para>
   1.528 +	</listitem>
   1.529 +	<listitem><para id="x_5c3">If a line starts with either of the characters
   1.530  	    <quote><literal>#</literal></quote> or
   1.531  	    <quote><literal>;</literal></quote>, the entire line is
   1.532  	    treated as a comment, and skipped as if empty.</para>
   1.533  	</listitem>
   1.534 -	<listitem><para>A line starts with a keyword.  This must start
   1.535 +	<listitem><para id="x_5c4">A line starts with a keyword.  This must start
   1.536  	    with an alphabetic character or underscore, and can
   1.537  	    subsequently contain any alphanumeric character or
   1.538  	    underscore.  (In regexp notation, a keyword must match
   1.539  	    <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
   1.540  	</listitem>
   1.541 -	<listitem><para>The next element must be an
   1.542 +	<listitem><para id="x_5c5">The next element must be an
   1.543  	    <quote><literal>=</literal></quote> character, which can
   1.544  	    be preceded or followed by an arbitrary amount of white
   1.545  	    space.</para>
   1.546  	</listitem>
   1.547 -	<listitem><para>If the rest of the line starts and ends with
   1.548 +	<listitem><para id="x_5c6">If the rest of the line starts and ends with
   1.549  	    matching quote characters (either single or double quote),
   1.550  	    it is treated as a template body.</para>
   1.551  	</listitem>
   1.552 -	<listitem><para>If the rest of the line <emphasis>does
   1.553 +	<listitem><para id="x_5c7">If the rest of the line <emphasis>does
   1.554  	      not</emphasis> start with a quote character, it is
   1.555  	    treated as the name of a file; the contents of this file
   1.556  	    will be read and used as a template body.</para>
   1.557 @@ -521,7 +521,7 @@
   1.558    <sect1>
   1.559      <title>Style files by example</title>
   1.560  
   1.561 -    <para>To illustrate how to write a style file, we will construct a
   1.562 +    <para id="x_5c8">To illustrate how to write a style file, we will construct a
   1.563        few by example.  Rather than provide a complete style file and
   1.564        walk through it, we'll mirror the usual process of developing a
   1.565        style file by starting with something very simple, and walking
   1.566 @@ -530,40 +530,40 @@
   1.567      <sect2>
   1.568        <title>Identifying mistakes in style files</title>
   1.569  
   1.570 -      <para>If Mercurial encounters a problem in a style file you are
   1.571 +      <para id="x_5c9">If Mercurial encounters a problem in a style file you are
   1.572  	working on, it prints a terse error message that, once you
   1.573  	figure out what it means, is actually quite useful.</para>
   1.574  
   1.575  &interaction.template.svnstyle.syntax.input;
   1.576  
   1.577 -      <para>Notice that <filename>broken.style</filename> attempts to
   1.578 +      <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to
   1.579  	define a <literal>changeset</literal> keyword, but forgets to
   1.580  	give any content for it. When instructed to use this style
   1.581  	file, Mercurial promptly complains.</para>
   1.582  
   1.583        &interaction.template.svnstyle.syntax.error;
   1.584  
   1.585 -      <para>This error message looks intimidating, but it is not too
   1.586 +      <para id="x_5cb">This error message looks intimidating, but it is not too
   1.587  	hard to follow.</para>
   1.588  
   1.589        <itemizedlist>
   1.590 -	<listitem><para>The first component is simply Mercurial's way
   1.591 +	<listitem><para id="x_5cc">The first component is simply Mercurial's way
   1.592  	    of saying <quote>I am giving up</quote>.</para>
   1.593  	  <programlisting>___abort___: broken.style:1: parse error</programlisting>
   1.594  	</listitem>
   1.595 -	<listitem><para>Next comes the name of the style file that
   1.596 +	<listitem><para id="x_5cd">Next comes the name of the style file that
   1.597  	    contains the error.</para>
   1.598  	  <programlisting>abort: ___broken.style___:1: parse error</programlisting>
   1.599  	</listitem>
   1.600 -	<listitem><para>Following the file name is the line number
   1.601 +	<listitem><para id="x_5ce">Following the file name is the line number
   1.602  	    where the error was encountered.</para>
   1.603  	  <programlisting>abort: broken.style:___1___: parse error</programlisting>
   1.604  	</listitem>
   1.605 -	<listitem><para>Finally, a description of what went
   1.606 +	<listitem><para id="x_5cf">Finally, a description of what went
   1.607  	    wrong.</para>
   1.608  	  <programlisting>abort: broken.style:1: ___parse error___</programlisting>
   1.609  	</listitem>
   1.610 -	<listitem><para>The description of the problem is not always
   1.611 +	<listitem><para id="x_5d0">The description of the problem is not always
   1.612  	    clear (as in this case), but even when it is cryptic, it
   1.613  	    is almost always trivial to visually inspect the offending
   1.614  	    line in the style file and see what is wrong.</para>
   1.615 @@ -573,32 +573,32 @@
   1.616      <sect2>
   1.617        <title>Uniquely identifying a repository</title>
   1.618  
   1.619 -      <para>If you would like to be able to identify a Mercurial
   1.620 +      <para id="x_5d1">If you would like to be able to identify a Mercurial
   1.621  	repository <quote>fairly uniquely</quote> using a short string
   1.622  	as an identifier, you can use the first revision in the
   1.623  	repository.</para>
   1.624  
   1.625        &interaction.template.svnstyle.id;
   1.626  
   1.627 -      <para>This is not guaranteed to be unique, but it is
   1.628 +      <para id="x_5d2">This is not guaranteed to be unique, but it is
   1.629  	nevertheless useful in many cases.</para>
   1.630        <itemizedlist>
   1.631 -	<listitem><para>It will not work in a completely empty
   1.632 +	<listitem><para id="x_5d3">It will not work in a completely empty
   1.633  	    repository, because such a repository does not have a
   1.634  	    revision zero.</para>
   1.635  	</listitem>
   1.636 -	<listitem><para>Neither will it work in the (extremely rare)
   1.637 +	<listitem><para id="x_5d4">Neither will it work in the (extremely rare)
   1.638  	    case where a repository is a merge of two or more formerly
   1.639  	    independent repositories, and you still have those
   1.640  	    repositories around.</para>
   1.641  	</listitem></itemizedlist>
   1.642 -      <para>Here are some uses to which you could put this
   1.643 +      <para id="x_5d5">Here are some uses to which you could put this
   1.644  	identifier:</para>
   1.645        <itemizedlist>
   1.646 -	<listitem><para>As a key into a table for a database that
   1.647 +	<listitem><para id="x_5d6">As a key into a table for a database that
   1.648  	    manages repositories on a server.</para>
   1.649  	</listitem>
   1.650 -	<listitem><para>As half of a {<emphasis>repository
   1.651 +	<listitem><para id="x_5d7">As half of a {<emphasis>repository
   1.652  	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
   1.653  	    Save this information away when you run an automated build
   1.654  	    or other activity, so that you can <quote>replay</quote>
   1.655 @@ -609,29 +609,29 @@
   1.656      <sect2>
   1.657        <title>Mimicking Subversion's output</title>
   1.658  
   1.659 -      <para>Let's try to emulate the default output format used by
   1.660 +      <para id="x_5d8">Let's try to emulate the default output format used by
   1.661  	another revision control tool, Subversion.</para>
   1.662  
   1.663        &interaction.template.svnstyle.short;
   1.664  
   1.665 -      <para>Since Subversion's output style is fairly simple, it is
   1.666 +      <para id="x_5d9">Since Subversion's output style is fairly simple, it is
   1.667  	easy to copy-and-paste a hunk of its output into a file, and
   1.668  	replace the text produced above by Subversion with the
   1.669  	template values we'd like to see expanded.</para>
   1.670  
   1.671        &interaction.template.svnstyle.template;
   1.672  
   1.673 -      <para>There are a few small ways in which this template deviates
   1.674 +      <para id="x_5da">There are a few small ways in which this template deviates
   1.675  	from the output produced by Subversion.</para>
   1.676        <itemizedlist>
   1.677 -	<listitem><para>Subversion prints a <quote>readable</quote>
   1.678 +	<listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
   1.679  	    date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the
   1.680  	    example output above) in parentheses.  Mercurial's
   1.681  	    templating engine does not provide a way to display a date
   1.682  	    in this format without also printing the time and time
   1.683  	    zone.</para>
   1.684  	</listitem>
   1.685 -	<listitem><para>We emulate Subversion's printing of
   1.686 +	<listitem><para id="x_5dc">We emulate Subversion's printing of
   1.687  	    <quote>separator</quote> lines full of
   1.688  	    <quote><literal>-</literal></quote> characters by ending
   1.689  	    the template with such a line. We use the templating
   1.690 @@ -640,20 +640,20 @@
   1.691  	    output (see below), thus achieving similar output to
   1.692  	    Subversion.</para>
   1.693  	</listitem>
   1.694 -	<listitem><para>Subversion's output includes a count in the
   1.695 +	<listitem><para id="x_5dd">Subversion's output includes a count in the
   1.696  	    header of the number of lines in the commit message.  We
   1.697  	    cannot replicate this in Mercurial; the templating engine
   1.698  	    does not currently provide a filter that counts the number
   1.699  	    of lines the template generates.</para>
   1.700  	</listitem></itemizedlist>
   1.701 -      <para>It took me no more than a minute or two of work to replace
   1.702 +      <para id="x_5de">It took me no more than a minute or two of work to replace
   1.703  	literal text from an example of Subversion's output with some
   1.704  	keywords and filters to give the template above.  The style
   1.705  	file simply refers to the template.</para>
   1.706  
   1.707        &interaction.template.svnstyle.style;
   1.708  
   1.709 -      <para>We could have included the text of the template file
   1.710 +      <para id="x_5df">We could have included the text of the template file
   1.711  	directly in the style file by enclosing it in quotes and
   1.712  	replacing the newlines with
   1.713  	<quote><literal>\n</literal></quote> sequences, but it would