1.1 --- a/fr/ch11-template.xml	Sun Aug 16 04:58:01 2009 +0200
     1.2 +++ b/fr/ch11-template.xml	Wed Apr 21 18:28:16 2010 +0200
     1.3 @@ -1,689 +1,685 @@
     1.4  <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5  
     1.6 -<chapter>
     1.7 -<title>Customising the output of Mercurial</title>
     1.8 -<para>\label{chap:template}</para>
     1.9 -
    1.10 -<para>Mercurial provides a powerful mechanism to let you control how it
    1.11 -displays information.  The mechanism is based on templates.  You can
    1.12 -use templates to generate specific output for a single command, or to
    1.13 -customise the entire appearance of the built-in web interface.</para>
    1.14 -
    1.15 -<sect1>
    1.16 -<title>Using precanned output styles</title>
    1.17 -<para>\label{sec:style}</para>
    1.18 -
    1.19 -<para>Packaged with Mercurial are some output styles that you can use
    1.20 -immediately.  A style is simply a precanned template that someone
    1.21 -wrote and installed somewhere that Mercurial can find.</para>
    1.22 -
    1.23 -<para>Before we take a look at Mercurial's bundled styles, let's review its
    1.24 -normal output.</para>
    1.25 -
    1.26 -<para><!-- &interaction.template.simple.normal; --></para>
    1.27 -
    1.28 -<para>This is somewhat informative, but it takes up a lot of space&emdash;five
    1.29 -lines of output per changeset.  The <literal>compact</literal> style reduces
    1.30 -this to three lines, presented in a sparse manner.</para>
    1.31 -
    1.32 -<para><!-- &interaction.template.simple.compact; --></para>
    1.33 -
    1.34 -<para>The <literal>changelog</literal> style hints at the expressive power of
    1.35 -Mercurial's templating engine.  This style attempts to follow the GNU
    1.36 -Project's changelog guidelines<citation>web:changelog</citation>.
    1.37 -</para>
    1.38 -
    1.39 -<para><!-- &interaction.template.simple.changelog; -->
    1.40 -</para>
    1.41 -
    1.42 -<para>You will not be shocked to learn that Mercurial's default output style
    1.43 -is named <literal>default</literal>.
    1.44 -</para>
    1.45 -
    1.46 -<sect2>
    1.47 -<title>Setting a default style</title>
    1.48 -
    1.49 -<para>You can modify the output style that Mercurial will use for every
    1.50 -command by editing your <filename role="special"> /.hgrc</filename>\ file, naming the style you would
    1.51 -prefer to use.
    1.52 -</para>
    1.53 -
    1.54 -<programlisting>
    1.55 -<para>  [ui]
    1.56 -  style = compact
    1.57 -</para>
    1.58 -</programlisting>
    1.59 -
    1.60 -<para>If you write a style of your own, you can use it by either providing
    1.61 -the path to your style file, or copying your style file into a
    1.62 -location where Mercurial can find it (typically the <literal>templates</literal>
    1.63 -subdirectory of your Mercurial install directory).
    1.64 -</para>
    1.65 -
    1.66 -</sect2>
    1.67 -</sect1>
    1.68 -<sect1>
    1.69 -<title>Commands that support styles and templates</title>
    1.70 -
    1.71 -<para>All of Mercurial's <quote><literal>log</literal>-like</quote> commands let you use styles
    1.72 -and templates: <command role="hg-cmd">hg incoming</command>, <command role="hg-cmd">hg log</command>, <command role="hg-cmd">hg outgoing</command>, and
    1.73 -<command role="hg-cmd">hg tip</command>.
    1.74 -</para>
    1.75 -
    1.76 -<para>As I write this manual, these are so far the only commands that
    1.77 -support styles and templates.  Since these are the most important
    1.78 -commands that need customisable output, there has been little pressure
    1.79 -from the Mercurial user community to add style and template support to
    1.80 -other commands.
    1.81 -</para>
    1.82 -
    1.83 -</sect1>
    1.84 -<sect1>
    1.85 -<title>The basics of templating</title>
    1.86 -
    1.87 -<para>At its simplest, a Mercurial template is a piece of text.  Some of the
    1.88 -text never changes, while other parts are <emphasis>expanded</emphasis>, or replaced
    1.89 -with new text, when necessary.
    1.90 -</para>
    1.91 -
    1.92 -<para>Before we continue, let's look again at a simple example of
    1.93 -Mercurial's normal output.
    1.94 -</para>
    1.95 -
    1.96 -<para><!-- &interaction.template.simple.normal; -->
    1.97 -</para>
    1.98 -
    1.99 -<para>Now, let's run the same command, but using a template to change its
   1.100 -output.
   1.101 -</para>
   1.102 -
   1.103 -<para><!-- &interaction.template.simple.simplest; -->
   1.104 -</para>
   1.105 -
   1.106 -<para>The example above illustrates the simplest possible template; it's
   1.107 -just a piece of static text, printed once for each changeset.  The
   1.108 -<option role="hg-opt-log">--template</option> option to the <command role="hg-cmd">hg log</command> command tells
   1.109 -Mercurial to use the given text as the template when printing each
   1.110 -changeset.
   1.111 -</para>
   1.112 -
   1.113 -<para>Notice that the template string above ends with the text
   1.114 -<quote><literal>\n</literal></quote>.  This is an <emphasis>escape sequence</emphasis>, telling Mercurial
   1.115 -to print a newline at the end of each template item.  If you omit this
   1.116 -newline, Mercurial will run each piece of output together.  See
   1.117 -section <xref linkend="sec:template:escape"/> for more details of escape sequences.
   1.118 -</para>
   1.119 -
   1.120 -<para>A template that prints a fixed string of text all the time isn't very
   1.121 -useful; let's try something a bit more complex.
   1.122 -</para>
   1.123 -
   1.124 -<para><!-- &interaction.template.simple.simplesub; -->
   1.125 -</para>
   1.126 -
   1.127 -<para>As you can see, the string <quote><literal>{desc}</literal></quote> in the template has been
   1.128 -replaced in the output with the description of each changeset.  Every
   1.129 -time Mercurial finds text enclosed in curly braces (<quote><literal>{</literal></quote>
   1.130 -and <quote>\texttt{}}</quote>), it will try to replace the braces and text with
   1.131 -the expansion of whatever is inside.  To print a literal curly brace,
   1.132 -you must escape it, as described in section <xref linkend="sec:template:escape"/>.
   1.133 -</para>
   1.134 -
   1.135 -</sect1>
   1.136 -<sect1>
   1.137 -<title>Common template keywords</title>
   1.138 -<para>\label{sec:template:keyword}
   1.139 -</para>
   1.140 -
   1.141 -<para>You can start writing simple templates immediately using the keywords
   1.142 -below.
   1.143 -</para>
   1.144 -
   1.145 -<itemizedlist>
   1.146 -<listitem><para><literal role="template-keyword">author</literal>: String.  The unmodified author of the changeset.
   1.147 -</para>
   1.148 -</listitem>
   1.149 -<listitem><para><literal role="template-keyword">branches</literal>: String.  The name of the branch on which
   1.150 -  the changeset was committed.  Will be empty if the branch name was
   1.151 -  <literal>default</literal>.
   1.152 -</para>
   1.153 -</listitem>
   1.154 -<listitem><para><literal role="template-keyword">date</literal>: Date information.  The date when the changeset
   1.155 -  was committed.  This is <emphasis>not</emphasis> human-readable; you must pass it
   1.156 -  through a filter that will render it appropriately.  See
   1.157 -  section <xref linkend="sec:template:filter"/> for more information on filters.
   1.158 -  The date is expressed as a pair of numbers.  The first number is a
   1.159 -  Unix UTC timestamp (seconds since January 1, 1970); the second is
   1.160 -  the offset of the committer's timezone from UTC, in seconds.
   1.161 -</para>
   1.162 -</listitem>
   1.163 -<listitem><para><literal role="template-keyword">desc</literal>: String.  The text of the changeset description.
   1.164 -</para>
   1.165 -</listitem>
   1.166 -<listitem><para><literal role="template-keyword">files</literal>: List of strings.  All files modified, added, or
   1.167 -  removed by this changeset.
   1.168 -</para>
   1.169 -</listitem>
   1.170 -<listitem><para><literal role="template-keyword">file_adds</literal>: List of strings.  Files added by this
   1.171 -  changeset.
   1.172 -</para>
   1.173 -</listitem>
   1.174 -<listitem><para><literal role="template-keyword">file_dels</literal>: List of strings.  Files removed by this
   1.175 -  changeset.
   1.176 -</para>
   1.177 -</listitem>
   1.178 -<listitem><para><literal role="template-keyword">node</literal>: String.  The changeset identification hash, as a
   1.179 -  40-character hexadecimal string.
   1.180 -</para>
   1.181 -</listitem>
   1.182 -<listitem><para><literal role="template-keyword">parents</literal>: List of strings.  The parents of the
   1.183 -  changeset.
   1.184 -</para>
   1.185 -</listitem>
   1.186 -<listitem><para><literal role="template-keyword">rev</literal>: Integer.  The repository-local changeset revision
   1.187 -  number.
   1.188 -</para>
   1.189 -</listitem>
   1.190 -<listitem><para><literal role="template-keyword">tags</literal>: List of strings.  Any tags associated with the
   1.191 -  changeset.
   1.192 -</para>
   1.193 -</listitem></itemizedlist>
   1.194 -
   1.195 -<para>A few simple experiments will show us what to expect when we use these
   1.196 -keywords; you can see the results in
   1.197 -figure <xref linkend="fig:template:keywords"/>.
   1.198 -</para>
   1.199 -
   1.200 -<informalfigure>
   1.201 -<para>  <!-- &interaction.template.simple.keywords; -->
   1.202 -  <caption><para>Template keywords in use</para></caption>
   1.203 -  \label{fig:template:keywords}
   1.204 -</para>
   1.205 -</informalfigure>
   1.206 -
   1.207 -<para>As we noted above, the date keyword does not produce human-readable
   1.208 -output, so we must treat it specially.  This involves using a
   1.209 -<emphasis>filter</emphasis>, about which more in section <xref linkend="sec:template:filter"/>.
   1.210 -</para>
   1.211 -
   1.212 -<para><!-- &interaction.template.simple.datekeyword; -->
   1.213 -</para>
   1.214 -
   1.215 -</sect1>
   1.216 -<sect1>
   1.217 -<title>Escape sequences</title>
   1.218 -<para>\label{sec:template:escape}
   1.219 -</para>
   1.220 -
   1.221 -<para>Mercurial's templating engine recognises the most commonly used escape
   1.222 -sequences in strings.  When it sees a backslash (<quote><literal>\</literal></quote>)
   1.223 -character, it looks at the following character and substitutes the two
   1.224 -characters with a single replacement, as described below.
   1.225 -</para>
   1.226 -
   1.227 -<itemizedlist>
   1.228 -<listitem><para><literal>\textbackslash\textbackslash</literal>: Backslash, <quote><literal>\</literal></quote>,
   1.229 -  ASCII 134.
   1.230 -</para>
   1.231 -</listitem>
   1.232 -<listitem><para><literal>\textbackslash n</literal>: Newline, ASCII 12.
   1.233 -</para>
   1.234 -</listitem>
   1.235 -<listitem><para><literal>\textbackslash r</literal>: Carriage return, ASCII 15.
   1.236 -</para>
   1.237 -</listitem>
   1.238 -<listitem><para><literal>\textbackslash t</literal>: Tab, ASCII 11.
   1.239 -</para>
   1.240 -</listitem>
   1.241 -<listitem><para><literal>\textbackslash v</literal>: Vertical tab, ASCII 13.
   1.242 -</para>
   1.243 -</listitem>
   1.244 -<listitem><para><literal>\textbackslash {</literal>: Open curly brace, <quote><literal>{</literal></quote>, ASCII 173.
   1.245 -</para>
   1.246 -</listitem>
   1.247 -<listitem><para><literal>\textbackslash }</literal>: Close curly brace, <quote><literal>}</literal></quote>, ASCII 175.
   1.248 -</para>
   1.249 -</listitem></itemizedlist>
   1.250 -
   1.251 -<para>As indicated above, if you want the expansion of a template to contain
   1.252 -a literal <quote><literal>\</literal></quote>, <quote><literal>{</literal></quote>, or <quote><literal>{</literal></quote> character, you
   1.253 -must escape it.
   1.254 -</para>
   1.255 -
   1.256 -</sect1>
   1.257 -<sect1>
   1.258 -<title>Filtering keywords to change their results</title>
   1.259 -<para>\label{sec:template:filter}
   1.260 -</para>
   1.261 -
   1.262 -<para>Some of the results of template expansion are not immediately easy to
   1.263 -use.  Mercurial lets you specify an optional chain of <emphasis>filters</emphasis>
   1.264 -to modify the result of expanding a keyword.  You have already seen a
   1.265 -common filter, <literal role="template-kw-filt-date">isodate</literal>, in action above, to make a
   1.266 -date readable.
   1.267 -</para>
   1.268 -
   1.269 -<para>Below is a list of the most commonly used filters that Mercurial
   1.270 -supports.  While some filters can be applied to any text, others can
   1.271 -only be used in specific circumstances.  The name of each filter is
   1.272 -followed first by an indication of where it can be used, then a
   1.273 -description of its effect.
   1.274 -</para>
   1.275 -
   1.276 -<itemizedlist>
   1.277 -<listitem><para><literal role="template-filter">addbreaks</literal>: Any text. Add an XHTML <quote><literal>&lt;br/&gt;</literal></quote>
   1.278 -  tag before the end of every line except the last.  For example,
   1.279 -  <quote><literal>foo\nbar</literal></quote> becomes <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.
   1.280 -</para>
   1.281 -</listitem>
   1.282 -<listitem><para><literal role="template-kw-filt-date">age</literal>: <literal role="template-keyword">date</literal> keyword.  Render the
   1.283 -  age of the date, relative to the current time.  Yields a string like
   1.284 -  <quote><literal>10 minutes</literal></quote>.
   1.285 -</para>
   1.286 -</listitem>
   1.287 -<listitem><para><literal role="template-filter">basename</literal>: Any text, but most useful for the
   1.288 -  <literal role="template-keyword">files</literal> keyword and its relatives.  Treat the text as a
   1.289 -  path, and return the basename. For example, <quote><literal>foo/bar/baz</literal></quote>
   1.290 -  becomes <quote><literal>baz</literal></quote>.
   1.291 -</para>
   1.292 -</listitem>
   1.293 -<listitem><para><literal role="template-kw-filt-date">date</literal>: <literal role="template-keyword">date</literal> keyword.  Render a date
   1.294 -  in a similar format to the Unix <literal role="template-keyword">date</literal> command, but with
   1.295 -  timezone included.  Yields a string like
   1.296 -  <quote><literal>Mon Sep 04 15:13:13 2006 -0700</literal></quote>.
   1.297 -</para>
   1.298 -</listitem>
   1.299 -<listitem><para><literal role="template-kw-filt-author">domain</literal>: Any text, but most useful for the
   1.300 -  <literal role="template-keyword">author</literal> keyword.  Finds the first string that looks like
   1.301 -  an email address, and extract just the domain component.  For
   1.302 -  example, <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.303 -  <quote><literal>serpentine.com</literal></quote>.
   1.304 -</para>
   1.305 -</listitem>
   1.306 -<listitem><para><literal role="template-kw-filt-author">email</literal>: Any text, but most useful for the
   1.307 -  <literal role="template-keyword">author</literal> keyword.  Extract the first string that looks like
   1.308 -  an email address.  For example,
   1.309 -  <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.310 -  <quote><literal>bos@serpentine.com</literal></quote>.
   1.311 -</para>
   1.312 -</listitem>
   1.313 -<listitem><para><literal role="template-filter">escape</literal>: Any text.  Replace the special XML/XHTML
   1.314 -  characters <quote><literal>&amp;</literal></quote>, <quote><literal>&lt;</literal></quote> and <quote><literal>&gt;</literal></quote> with
   1.315 -  XML entities.
   1.316 -</para>
   1.317 -</listitem>
   1.318 -<listitem><para><literal role="template-filter">fill68</literal>: Any text.  Wrap the text to fit in 68
   1.319 -  columns.  This is useful before you pass text through the
   1.320 -  <literal role="template-filter">tabindent</literal> filter, and still want it to fit in an
   1.321 -  80-column fixed-font window.
   1.322 -</para>
   1.323 -</listitem>
   1.324 -<listitem><para><literal role="template-filter">fill76</literal>: Any text.  Wrap the text to fit in 76
   1.325 -  columns.
   1.326 -</para>
   1.327 -</listitem>
   1.328 -<listitem><para><literal role="template-filter">firstline</literal>: Any text.  Yield the first line of text,
   1.329 -  without any trailing newlines.
   1.330 -</para>
   1.331 -</listitem>
   1.332 -<listitem><para><literal role="template-kw-filt-date">hgdate</literal>: <literal role="template-keyword">date</literal> keyword.  Render the
   1.333 -  date as a pair of readable numbers.  Yields a string like
   1.334 -  <quote><literal>1157407993 25200</literal></quote>.
   1.335 -</para>
   1.336 -</listitem>
   1.337 -<listitem><para><literal role="template-kw-filt-date">isodate</literal>: <literal role="template-keyword">date</literal> keyword.  Render the
   1.338 -  date as a text string in ISO 8601 format.  Yields a string like
   1.339 -  <quote><literal>2006-09-04 15:13:13 -0700</literal></quote>.
   1.340 -</para>
   1.341 -</listitem>
   1.342 -<listitem><para><literal role="template-filter">obfuscate</literal>: Any text, but most useful for the
   1.343 -  <literal role="template-keyword">author</literal> keyword.  Yield the input text rendered as a
   1.344 -  sequence of XML entities.  This helps to defeat some particularly
   1.345 -  stupid screen-scraping email harvesting spambots.
   1.346 -</para>
   1.347 -</listitem>
   1.348 -<listitem><para><literal role="template-kw-filt-author">person</literal>: Any text, but most useful for the
   1.349 -  <literal role="template-keyword">author</literal> keyword.  Yield the text before an email address.
   1.350 -  For example, <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote>
   1.351 -  becomes <quote><literal>Bryan O'Sullivan</literal></quote>.
   1.352 -</para>
   1.353 -</listitem>
   1.354 -<listitem><para><literal role="template-kw-filt-date">rfc822date</literal>: <literal role="template-keyword">date</literal> keyword.  Render a
   1.355 -  date using the same format used in email headers.  Yields a string
   1.356 -  like <quote><literal>Mon, 04 Sep 2006 15:13:13 -0700</literal></quote>.
   1.357 -</para>
   1.358 -</listitem>
   1.359 -<listitem><para><literal role="template-kw-filt-node">short</literal>: Changeset hash.  Yield the short form
   1.360 -  of a changeset hash, i.e. a 12-character hexadecimal string.
   1.361 -</para>
   1.362 -</listitem>
   1.363 -<listitem><para><literal role="template-kw-filt-date">shortdate</literal>: <literal role="template-keyword">date</literal> keyword.  Render
   1.364 -  the year, month, and day of the date.  Yields a string like
   1.365 -  <quote><literal>2006-09-04</literal></quote>.
   1.366 -</para>
   1.367 -</listitem>
   1.368 -<listitem><para><literal role="template-filter">strip</literal>: Any text.  Strip all leading and trailing
   1.369 -  whitespace from the string.
   1.370 -</para>
   1.371 -</listitem>
   1.372 -<listitem><para><literal role="template-filter">tabindent</literal>: Any text.  Yield the text, with every line
   1.373 -  except the first starting with a tab character.
   1.374 -</para>
   1.375 -</listitem>
   1.376 -<listitem><para><literal role="template-filter">urlescape</literal>: Any text.  Escape all characters that are
   1.377 -  considered <quote>special</quote> by URL parsers.  For example, <literal>foo bar</literal>
   1.378 -  becomes <literal>foo%20bar</literal>.
   1.379 -</para>
   1.380 -</listitem>
   1.381 -<listitem><para><literal role="template-kw-filt-author">user</literal>: Any text, but most useful for the
   1.382 -  <literal role="template-keyword">author</literal> keyword.  Return the <quote>user</quote> portion of an email
   1.383 -  address.  For example,
   1.384 -  <quote><literal>Bryan O'Sullivan &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.385 -  <quote><literal>bos</literal></quote>.
   1.386 -</para>
   1.387 -</listitem></itemizedlist>
   1.388 -
   1.389 -<informalfigure>
   1.390 -<para>  <!-- &interaction.template.simple.manyfilters; -->
   1.391 -  <caption><para>Template filters in action</para></caption>
   1.392 -  \label{fig:template:filters}
   1.393 -</para>
   1.394 -</informalfigure>
   1.395 -
   1.396 -<note>
   1.397 -<para>  If you try to apply a filter to a piece of data that it cannot
   1.398 -  process, Mercurial will fail and print a Python exception.  For
   1.399 -  example, trying to run the output of the <literal role="template-keyword">desc</literal> keyword
   1.400 -  into the <literal role="template-kw-filt-date">isodate</literal> filter is not a good idea.
   1.401 -</para>
   1.402 -</note>
   1.403 -
   1.404 -<sect2>
   1.405 -<title>Combining filters</title>
   1.406 -
   1.407 -<para>It is easy to combine filters to yield output in the form you would
   1.408 -like.  The following chain of filters tidies up a description, then
   1.409 -makes sure that it fits cleanly into 68 columns, then indents it by a
   1.410 -further 8 characters (at least on Unix-like systems, where a tab is
   1.411 -conventionally 8 characters wide).
   1.412 -</para>
   1.413 -
   1.414 -<para><!-- &interaction.template.simple.combine; -->
   1.415 -</para>
   1.416 -
   1.417 -<para>Note the use of <quote><literal>\t</literal></quote> (a tab character) in the template to
   1.418 -force the first line to be indented; this is necessary since
   1.419 -<literal role="template-keyword">tabindent</literal> indents all lines <emphasis>except</emphasis> the first.
   1.420 -</para>
   1.421 -
   1.422 -<para>Keep in mind that the order of filters in a chain is significant.  The
   1.423 -first filter is applied to the result of the keyword; the second to
   1.424 -the result of the first filter; and so on.  For example, using
   1.425 -<literal>fill68|tabindent</literal> gives very different results from
   1.426 -<literal>tabindent|fill68</literal>.
   1.427 -</para>
   1.428 -
   1.429 -
   1.430 -</sect2>
   1.431 -</sect1>
   1.432 -<sect1>
   1.433 -<title>From templates to styles</title>
   1.434 -
   1.435 -<para>A command line template provides a quick and simple way to format some
   1.436 -output.  Templates can become verbose, though, and it's useful to be
   1.437 -able to give a template a name.  A style file is a template with a
   1.438 -name, stored in a file.
   1.439 -</para>
   1.440 -
   1.441 -<para>More than that, using a style file unlocks the power of Mercurial's
   1.442 -templating engine in ways that are not possible using the command line
   1.443 -<option role="hg-opt-log">--template</option> option.
   1.444 -</para>
   1.445 -
   1.446 -<sect2>
   1.447 -<title>The simplest of style files</title>
   1.448 -
   1.449 -<para>Our simple style file contains just one line:
   1.450 -</para>
   1.451 -
   1.452 -<para><!-- &interaction.template.simple.rev; -->
   1.453 -</para>
   1.454 -
   1.455 -<para>This tells Mercurial, <quote>if you're printing a changeset, use the text
   1.456 -on the right as the template</quote>.
   1.457 -</para>
   1.458 -
   1.459 -</sect2>
   1.460 -<sect2>
   1.461 -<title>Style file syntax</title>
   1.462 -
   1.463 -<para>The syntax rules for a style file are simple.
   1.464 -</para>
   1.465 -
   1.466 -<itemizedlist>
   1.467 -<listitem><para>The file is processed one line at a time.
   1.468 -</para>
   1.469 -</listitem>
   1.470 -</para>
   1.471 -</listitem>
   1.472 -<listitem><para>Leading and trailing white space are ignored.
   1.473 -</para>
   1.474 -</listitem>
   1.475 -</para>
   1.476 -</listitem>
   1.477 -<listitem><para>Empty lines are skipped.
   1.478 -</para>
   1.479 -</listitem>
   1.480 -</para>
   1.481 -</listitem>
   1.482 -<listitem><para>If a line starts with either of the characters <quote><literal>#</literal></quote> or
   1.483 -  <quote><literal>;</literal></quote>, the entire line is treated as a comment, and skipped
   1.484 -  as if empty.
   1.485 -</para>
   1.486 -</listitem>
   1.487 -</para>
   1.488 -</listitem>
   1.489 -<listitem><para>A line starts with a keyword.  This must start with an
   1.490 -  alphabetic character or underscore, and can subsequently contain any
   1.491 -  alphanumeric character or underscore.  (In regexp notation, a
   1.492 -  keyword must match <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)
   1.493 -</para>
   1.494 -</listitem>
   1.495 -</para>
   1.496 -</listitem>
   1.497 -<listitem><para>The next element must be an <quote><literal>=</literal></quote> character, which can
   1.498 -  be preceded or followed by an arbitrary amount of white space.
   1.499 -</para>
   1.500 -</listitem>
   1.501 -</para>
   1.502 -</listitem>
   1.503 -<listitem><para>If the rest of the line starts and ends with matching quote
   1.504 -  characters (either single or double quote), it is treated as a
   1.505 -  template body.
   1.506 -</para>
   1.507 -</listitem>
   1.508 -</para>
   1.509 -</listitem>
   1.510 -<listitem><para>If the rest of the line <emphasis>does not</emphasis> start with a quote
   1.511 -  character, it is treated as the name of a file; the contents of this
   1.512 -  file will be read and used as a template body.
   1.513 -</para>
   1.514 -</listitem></itemizedlist>
   1.515 -
   1.516 -</sect2>
   1.517 -</sect1>
   1.518 -<sect1>
   1.519 -<title>Style files by example</title>
   1.520 -
   1.521 -<para>To illustrate how to write a style file, we will construct a few by
   1.522 -example.  Rather than provide a complete style file and walk through
   1.523 -it, we'll mirror the usual process of developing a style file by
   1.524 -starting with something very simple, and walking through a series of
   1.525 -successively more complete examples.
   1.526 -</para>
   1.527 -
   1.528 -<sect2>
   1.529 -<title>Identifying mistakes in style files</title>
   1.530 -
   1.531 -<para>If Mercurial encounters a problem in a style file you are working on,
   1.532 -it prints a terse error message that, once you figure out what it
   1.533 -means, is actually quite useful.
   1.534 -</para>
   1.535 -
   1.536 -<para><!-- &interaction.template.svnstyle.syntax.input; -->
   1.537 -</para>
   1.538 -
   1.539 -<para>Notice that <filename>broken.style</filename> attempts to define a
   1.540 -<literal>changeset</literal> keyword, but forgets to give any content for it.
   1.541 -When instructed to use this style file, Mercurial promptly complains.
   1.542 -</para>
   1.543 -
   1.544 -<para><!-- &interaction.template.svnstyle.syntax.error; -->
   1.545 -</para>
   1.546 -
   1.547 -<para>This error message looks intimidating, but it is not too hard to
   1.548 -follow.
   1.549 -</para>
   1.550 -
   1.551 -<itemizedlist>
   1.552 -<listitem><para>The first component is simply Mercurial's way of saying <quote>I am
   1.553 -  giving up</quote>.
   1.554 -</para>
   1.555 -</listitem><programlisting>
   1.556 -<listitem><para>    <emphasis role="bold">abort:</emphasis> broken.style:1: parse error
   1.557 -</para>
   1.558 -</listitem></programlisting>
   1.559 -
   1.560 -</para>
   1.561 -</listitem>
   1.562 -<listitem><para>Next comes the name of the style file that contains the error.
   1.563 -</para>
   1.564 -</listitem><programlisting>
   1.565 -<listitem><para>    abort: <emphasis role="bold">broken.style</emphasis>:1: parse error
   1.566 -</para>
   1.567 -</listitem></programlisting>
   1.568 -
   1.569 -</para>
   1.570 -</listitem>
   1.571 -<listitem><para>Following the file name is the line number where the error was
   1.572 -  encountered.
   1.573 -</para>
   1.574 -</listitem><programlisting>
   1.575 -<listitem><para>    abort: broken.style:<emphasis role="bold">1</emphasis>: parse error
   1.576 -</para>
   1.577 -</listitem></programlisting>
   1.578 -
   1.579 -</para>
   1.580 -</listitem>
   1.581 -<listitem><para>Finally, a description of what went wrong.
   1.582 -</para>
   1.583 -</listitem><programlisting>
   1.584 -<listitem><para>    abort: broken.style:1: <emphasis role="bold">parse error</emphasis>
   1.585 -</para>
   1.586 -</listitem></programlisting>
   1.587 -<listitem><para>  The description of the problem is not always clear (as in this
   1.588 -  case), but even when it is cryptic, it is almost always trivial to
   1.589 -  visually inspect the offending line in the style file and see what
   1.590 -  is wrong.
   1.591 -</para>
   1.592 -</listitem></itemizedlist>
   1.593 -
   1.594 -</sect2>
   1.595 -<sect2>
   1.596 -<title>Uniquely identifying a repository</title>
   1.597 -
   1.598 -<para>If you would like to be able to identify a Mercurial repository
   1.599 -<quote>fairly uniquely</quote> using a short string as an identifier, you can
   1.600 -use the first revision in the repository.
   1.601 -<!-- &interaction.template.svnstyle.id; -->
   1.602 -This is not guaranteed to be unique, but it is nevertheless useful in
   1.603 -many cases.
   1.604 -</para>
   1.605 -<itemizedlist>
   1.606 -<listitem><para>It will not work in a completely empty repository, because such
   1.607 -  a repository does not have a revision zero.
   1.608 -</para>
   1.609 -</listitem>
   1.610 -<listitem><para>Neither will it work in the (extremely rare) case where a
   1.611 -  repository is a merge of two or more formerly independent
   1.612 -  repositories, and you still have those repositories around.
   1.613 -</para>
   1.614 -</listitem></itemizedlist>
   1.615 -<para>Here are some uses to which you could put this identifier:
   1.616 -</para>
   1.617 -<itemizedlist>
   1.618 -<listitem><para>As a key into a table for a database that manages repositories
   1.619 -  on a server.
   1.620 -</para>
   1.621 -</listitem>
   1.622 -<listitem><para>As half of a {<emphasis>repository ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
   1.623 -  Save this information away when you run an automated build or other
   1.624 -  activity, so that you can <quote>replay</quote> the build later if necessary.
   1.625 -</para>
   1.626 -</listitem></itemizedlist>
   1.627 -
   1.628 -</sect2>
   1.629 -<sect2>
   1.630 -<title>Mimicking Subversion's output</title>
   1.631 -
   1.632 -<para>Let's try to emulate the default output format used by another
   1.633 -revision control tool, Subversion.
   1.634 -<!-- &interaction.template.svnstyle.short; -->
   1.635 -</para>
   1.636 -
   1.637 -<para>Since Subversion's output style is fairly simple, it is easy to
   1.638 -copy-and-paste a hunk of its output into a file, and replace the text
   1.639 -produced above by Subversion with the template values we'd like to see
   1.640 -expanded.
   1.641 -<!-- &interaction.template.svnstyle.template; -->
   1.642 -</para>
   1.643 -
   1.644 -<para>There are a few small ways in which this template deviates from the
   1.645 -output produced by Subversion.
   1.646 -</para>
   1.647 -<itemizedlist>
   1.648 -<listitem><para>Subversion prints a <quote>readable</quote> date (the <quote>\texttt{Wed, 27 Sep
   1.649 -    2006}</quote> in the example output above) in parentheses.  Mercurial's
   1.650 -  templating engine does not provide a way to display a date in this
   1.651 -  format without also printing the time and time zone.
   1.652 -</para>
   1.653 -</listitem>
   1.654 -<listitem><para>We emulate Subversion's printing of <quote>separator</quote> lines full of
   1.655 -  <quote><literal>-</literal></quote> characters by ending the template with such a line.
   1.656 -  We use the templating engine's <literal role="template-keyword">header</literal> keyword to print a
   1.657 -  separator line as the first line of output (see below), thus
   1.658 -  achieving similar output to Subversion.
   1.659 -</para>
   1.660 -</listitem>
   1.661 -<listitem><para>Subversion's output includes a count in the header of the number
   1.662 -  of lines in the commit message.  We cannot replicate this in
   1.663 -  Mercurial; the templating engine does not currently provide a filter
   1.664 -  that counts the number of lines the template generates.
   1.665 -</para>
   1.666 -</listitem></itemizedlist>
   1.667 -<para>It took me no more than a minute or two of work to replace literal
   1.668 -text from an example of Subversion's output with some keywords and
   1.669 -filters to give the template above.  The style file simply refers to
   1.670 -the template.
   1.671 -<!-- &interaction.template.svnstyle.style; -->
   1.672 -</para>
   1.673 -
   1.674 -<para>We could have included the text of the template file directly in the
   1.675 -style file by enclosing it in quotes and replacing the newlines with
   1.676 -<quote><literal>\n</literal></quote> sequences, but it would have made the style file too
   1.677 -difficult to read.  Readability is a good guide when you're trying to
   1.678 -decide whether some text belongs in a style file, or in a template
   1.679 -file that the style file points to.  If the style file will look too
   1.680 -big or cluttered if you insert a literal piece of text, drop it into a
   1.681 -template instead.
   1.682 -</para>
   1.683 -
   1.684 -</sect2>
   1.685 -</sect1>
   1.686 +<chapter id="chap:template">
   1.687 +  <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
   1.688 +  <title>Customizing the output of Mercurial</title>
   1.689 +
   1.690 +  <para id="x_578">Mercurial provides a powerful mechanism to let you control how
   1.691 +    it displays information.  The mechanism is based on templates.
   1.692 +    You can use templates to generate specific output for a single
   1.693 +    command, or to customize the entire appearance of the built-in web
   1.694 +    interface.</para>
   1.695 +
   1.696 +  <sect1 id="sec:style">
   1.697 +    <title>Using precanned output styles</title>
   1.698 +
   1.699 +    <para id="x_579">Packaged with Mercurial are some output styles that you can
   1.700 +      use immediately.  A style is simply a precanned template that
   1.701 +      someone wrote and installed somewhere that Mercurial can
   1.702 +      find.</para>
   1.703 +
   1.704 +    <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
   1.705 +      review its normal output.</para>
   1.706 +
   1.707 +    &interaction.template.simple.normal;
   1.708 +
   1.709 +    <para id="x_57b">This is somewhat informative, but it takes up a lot of
   1.710 +      space&emdash;five lines of output per changeset.  The
   1.711 +      <literal>compact</literal> style reduces this to three lines,
   1.712 +      presented in a sparse manner.</para>
   1.713 +
   1.714 +    &interaction.template.simple.compact;
   1.715 +
   1.716 +    <para id="x_57c">The <literal>changelog</literal> style hints at the
   1.717 +      expressive power of Mercurial's templating engine.  This style
   1.718 +      attempts to follow the GNU Project's changelog
   1.719 +      guidelines<citation>web:changelog</citation>.</para>
   1.720 +
   1.721 +    &interaction.template.simple.changelog;
   1.722 +
   1.723 +    <para id="x_57d">You will not be shocked to learn that Mercurial's default
   1.724 +      output style is named <literal>default</literal>.</para>
   1.725 +
   1.726 +    <sect2>
   1.727 +      <title>Setting a default style</title>
   1.728 +
   1.729 +      <para id="x_57e">You can modify the output style that Mercurial will use
   1.730 +	for every command by editing your <filename
   1.731 +	  role="special">~/.hgrc</filename> file, naming the style
   1.732 +	you would prefer to use.</para>
   1.733 +
   1.734 +      <programlisting>[ui]
   1.735 +style = compact</programlisting>
   1.736 +
   1.737 +      <para id="x_57f">If you write a style of your own, you can use it by either
   1.738 +	providing the path to your style file, or copying your style
   1.739 +	file into a location where Mercurial can find it (typically
   1.740 +	the <literal>templates</literal> subdirectory of your
   1.741 +	Mercurial install directory).</para>
   1.742 +    </sect2>
   1.743 +  </sect1>
   1.744 +
   1.745 +  <sect1>
   1.746 +    <title>Commands that support styles and templates</title>
   1.747 +
   1.748 +    <para id="x_580">All of Mercurial's
   1.749 +      <quote><literal>log</literal>-like</quote> commands let you use
   1.750 +      styles and templates: <command role="hg-cmd">hg
   1.751 +	incoming</command>, <command role="hg-cmd">hg log</command>,
   1.752 +      <command role="hg-cmd">hg outgoing</command>, and <command
   1.753 +	role="hg-cmd">hg tip</command>.</para>
   1.754 +
   1.755 +    <para id="x_581">As I write this manual, these are so far the only commands
   1.756 +      that support styles and templates.  Since these are the most
   1.757 +      important commands that need customizable output, there has been
   1.758 +      little pressure from the Mercurial user community to add style
   1.759 +      and template support to other commands.</para>
   1.760 +  </sect1>
   1.761 +
   1.762 +  <sect1>
   1.763 +    <title>The basics of templating</title>
   1.764 +
   1.765 +    <para id="x_582">At its simplest, a Mercurial template is a piece of text.
   1.766 +      Some of the text never changes, while other parts are
   1.767 +      <emphasis>expanded</emphasis>, or replaced with new text, when
   1.768 +      necessary.</para>
   1.769 +
   1.770 +    <para id="x_583">Before we continue, let's look again at a simple example of
   1.771 +      Mercurial's normal output.</para>
   1.772 +
   1.773 +    &interaction.template.simple.normal;
   1.774 +
   1.775 +    <para id="x_584">Now, let's run the same command, but using a template to
   1.776 +      change its output.</para>
   1.777 +
   1.778 +    &interaction.template.simple.simplest;
   1.779 +
   1.780 +    <para id="x_585">The example above illustrates the simplest possible
   1.781 +      template; it's just a piece of static text, printed once for
   1.782 +      each changeset.  The <option
   1.783 +	role="hg-opt-log">--template</option> option to the <command
   1.784 +	role="hg-cmd">hg log</command> command tells Mercurial to use
   1.785 +      the given text as the template when printing each
   1.786 +      changeset.</para>
   1.787 +
   1.788 +    <para id="x_586">Notice that the template string above ends with the text
   1.789 +      <quote><literal>\n</literal></quote>.  This is an
   1.790 +      <emphasis>escape sequence</emphasis>, telling Mercurial to print
   1.791 +      a newline at the end of each template item.  If you omit this
   1.792 +      newline, Mercurial will run each piece of output together.  See
   1.793 +      <xref linkend="sec:template:escape"/> for more details
   1.794 +      of escape sequences.</para>
   1.795 +
   1.796 +    <para id="x_587">A template that prints a fixed string of text all the time
   1.797 +      isn't very useful; let's try something a bit more
   1.798 +      complex.</para>
   1.799 +
   1.800 +    &interaction.template.simple.simplesub;
   1.801 +
   1.802 +    <para id="x_588">As you can see, the string
   1.803 +      <quote><literal>{desc}</literal></quote> in the template has
   1.804 +      been replaced in the output with the description of each
   1.805 +      changeset.  Every time Mercurial finds text enclosed in curly
   1.806 +      braces (<quote><literal>{</literal></quote> and
   1.807 +      <quote><literal>}</literal></quote>), it will try to replace the
   1.808 +      braces and text with the expansion of whatever is inside.  To
   1.809 +      print a literal curly brace, you must escape it, as described in
   1.810 +      <xref linkend="sec:template:escape"/>.</para>
   1.811 +  </sect1>
   1.812 +
   1.813 +  <sect1 id="sec:template:keyword">
   1.814 +    <title>Common template keywords</title>
   1.815 +
   1.816 +    <para id="x_589">You can start writing simple templates immediately using the
   1.817 +      keywords below.</para>
   1.818 +
   1.819 +    <itemizedlist>
   1.820 +      <listitem><para id="x_58a"><literal
   1.821 +	    role="template-keyword">author</literal>: String.  The
   1.822 +	  unmodified author of the changeset.</para>
   1.823 +      </listitem>
   1.824 +      <listitem><para id="x_58b"><literal
   1.825 +	    role="template-keyword">branches</literal>: String.  The
   1.826 +	  name of the branch on which the changeset was committed.
   1.827 +	  Will be empty if the branch name was
   1.828 +	  <literal>default</literal>.</para>
   1.829 +      </listitem>
   1.830 +      <listitem><para id="x_58c"><literal role="template-keyword">date</literal>:
   1.831 +	  Date information.  The date when the changeset was
   1.832 +	  committed.  This is <emphasis>not</emphasis> human-readable;
   1.833 +	  you must pass it through a filter that will render it
   1.834 +	  appropriately.  See <xref
   1.835 +	    linkend="sec:template:filter"/> for more information
   1.836 +	  on filters. The date is expressed as a pair of numbers.  The
   1.837 +	  first number is a Unix UTC timestamp (seconds since January
   1.838 +	  1, 1970); the second is the offset of the committer's
   1.839 +	  timezone from UTC, in seconds.</para>
   1.840 +      </listitem>
   1.841 +      <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>:
   1.842 +	  String.  The text of the changeset description.</para>
   1.843 +      </listitem>
   1.844 +      <listitem><para id="x_58e"><literal
   1.845 +	    role="template-keyword">files</literal>: List of strings.
   1.846 +	  All files modified, added, or removed by this
   1.847 +	  changeset.</para>
   1.848 +      </listitem>
   1.849 +      <listitem><para id="x_58f"><literal
   1.850 +	    role="template-keyword">file_adds</literal>: List of
   1.851 +	  strings.  Files added by this changeset.</para>
   1.852 +      </listitem>
   1.853 +      <listitem><para id="x_590"><literal
   1.854 +	    role="template-keyword">file_dels</literal>: List of
   1.855 +	  strings.  Files removed by this changeset.</para>
   1.856 +      </listitem>
   1.857 +      <listitem><para id="x_591"><literal role="template-keyword">node</literal>:
   1.858 +	  String.  The changeset identification hash, as a
   1.859 +	  40-character hexadecimal string.</para>
   1.860 +      </listitem>
   1.861 +      <listitem><para id="x_592"><literal
   1.862 +	    role="template-keyword">parents</literal>: List of
   1.863 +	  strings.  The parents of the changeset.</para>
   1.864 +      </listitem>
   1.865 +      <listitem><para id="x_593"><literal role="template-keyword">rev</literal>:
   1.866 +	  Integer.  The repository-local changeset revision
   1.867 +	  number.</para>
   1.868 +      </listitem>
   1.869 +      <listitem><para id="x_594"><literal role="template-keyword">tags</literal>:
   1.870 +	  List of strings.  Any tags associated with the
   1.871 +	  changeset.</para>
   1.872 +      </listitem>
   1.873 +    </itemizedlist>
   1.874 +
   1.875 +    <para id="x_595">A few simple experiments will show us what to expect when we
   1.876 +      use these keywords; you can see the results below.</para>
   1.877 +
   1.878 +    &interaction.template.simple.keywords;
   1.879 +
   1.880 +    <para id="x_596">As we noted above, the date keyword does not produce
   1.881 +      human-readable output, so we must treat it specially.  This
   1.882 +      involves using a <emphasis>filter</emphasis>, about which more
   1.883 +      in <xref linkend="sec:template:filter"/>.</para>
   1.884 +
   1.885 +    &interaction.template.simple.datekeyword;
   1.886 +  </sect1>
   1.887 +
   1.888 +  <sect1 id="sec:template:escape">
   1.889 +    <title>Escape sequences</title>
   1.890 +
   1.891 +    <para id="x_597">Mercurial's templating engine recognises the most commonly
   1.892 +      used escape sequences in strings.  When it sees a backslash
   1.893 +      (<quote><literal>\</literal></quote>) character, it looks at the
   1.894 +      following character and substitutes the two characters with a
   1.895 +      single replacement, as described below.</para>
   1.896 +
   1.897 +    <itemizedlist>
   1.898 +      <listitem><para id="x_598"><literal>\</literal>:
   1.899 +	  Backslash, <quote><literal>\</literal></quote>, ASCII
   1.900 +	  134.</para>
   1.901 +      </listitem>
   1.902 +      <listitem><para id="x_599"><literal>\n</literal>: Newline,
   1.903 +	  ASCII 12.</para>
   1.904 +      </listitem>
   1.905 +      <listitem><para id="x_59a"><literal>\r</literal>: Carriage
   1.906 +	  return, ASCII 15.</para>
   1.907 +      </listitem>
   1.908 +      <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII
   1.909 +	  11.</para>
   1.910 +      </listitem>
   1.911 +      <listitem><para id="x_59c"><literal>\v</literal>: Vertical
   1.912 +	  tab, ASCII 13.</para>
   1.913 +      </listitem>
   1.914 +      <listitem><para id="x_59d"><literal>\{</literal>: Open curly
   1.915 +	  brace, <quote><literal>{</literal></quote>, ASCII
   1.916 +	  173.</para>
   1.917 +      </listitem>
   1.918 +      <listitem><para id="x_59e"><literal>\}</literal>: Close curly
   1.919 +	  brace, <quote><literal>}</literal></quote>, ASCII
   1.920 +	  175.</para>
   1.921 +      </listitem></itemizedlist>
   1.922 +
   1.923 +    <para id="x_59f">As indicated above, if you want the expansion of a template
   1.924 +      to contain a literal <quote><literal>\</literal></quote>,
   1.925 +      <quote><literal>{</literal></quote>, or
   1.926 +      <quote><literal>{</literal></quote> character, you must escape
   1.927 +      it.</para>
   1.928 +  </sect1>
   1.929 +
   1.930 +  <sect1 id="sec:template:filter">
   1.931 +    <title>Filtering keywords to change their results</title>
   1.932 +
   1.933 +    <para id="x_5a0">Some of the results of template expansion are not
   1.934 +      immediately easy to use.  Mercurial lets you specify an optional
   1.935 +      chain of <emphasis>filters</emphasis> to modify the result of
   1.936 +      expanding a keyword.  You have already seen a common filter,
   1.937 +      <literal role="template-kw-filt-date">isodate</literal>, in
   1.938 +      action above, to make a date readable.</para>
   1.939 +
   1.940 +    <para id="x_5a1">Below is a list of the most commonly used filters that
   1.941 +      Mercurial supports.  While some filters can be applied to any
   1.942 +      text, others can only be used in specific circumstances.  The
   1.943 +      name of each filter is followed first by an indication of where
   1.944 +      it can be used, then a description of its effect.</para>
   1.945 +
   1.946 +    <itemizedlist>
   1.947 +      <listitem><para id="x_5a2"><literal
   1.948 +	    role="template-filter">addbreaks</literal>: Any text. Add
   1.949 +	  an XHTML <quote><literal>&lt;br/&gt;</literal></quote> tag
   1.950 +	  before the end of every line except the last.  For example,
   1.951 +	  <quote><literal>foo\nbar</literal></quote> becomes
   1.952 +	  <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.</para>
   1.953 +      </listitem>
   1.954 +      <listitem><para id="x_5a3"><literal
   1.955 +	    role="template-kw-filt-date">age</literal>: <literal
   1.956 +	    role="template-keyword">date</literal> keyword.  Render
   1.957 +	  the age of the date, relative to the current time.  Yields a
   1.958 +	  string like <quote><literal>10
   1.959 +	      minutes</literal></quote>.</para>
   1.960 +      </listitem>
   1.961 +      <listitem><para id="x_5a4"><literal
   1.962 +	    role="template-filter">basename</literal>: Any text, but
   1.963 +	  most useful for the <literal
   1.964 +	    role="template-keyword">files</literal> keyword and its
   1.965 +	  relatives.  Treat the text as a path, and return the
   1.966 +	  basename. For example,
   1.967 +	  <quote><literal>foo/bar/baz</literal></quote> becomes
   1.968 +	  <quote><literal>baz</literal></quote>.</para>
   1.969 +      </listitem>
   1.970 +      <listitem><para id="x_5a5"><literal
   1.971 +	    role="template-kw-filt-date">date</literal>: <literal
   1.972 +	    role="template-keyword">date</literal> keyword.  Render a
   1.973 +	  date in a similar format to the Unix <literal
   1.974 +	    role="template-keyword">date</literal> command, but with
   1.975 +	  timezone included.  Yields a string like <quote><literal>Mon
   1.976 +	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
   1.977 +      </listitem>
   1.978 +      <listitem><para id="x_5a6"><literal
   1.979 +	    role="template-kw-filt-author">domain</literal>: Any text,
   1.980 +	  but most useful for the <literal
   1.981 +	    role="template-keyword">author</literal> keyword.  Finds
   1.982 +	  the first string that looks like an email address, and
   1.983 +	  extract just the domain component.  For example,
   1.984 +	  <quote><literal>Bryan O'Sullivan
   1.985 +	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.986 +	  <quote><literal>serpentine.com</literal></quote>.</para>
   1.987 +      </listitem>
   1.988 +      <listitem><para id="x_5a7"><literal
   1.989 +	    role="template-kw-filt-author">email</literal>: Any text,
   1.990 +	  but most useful for the <literal
   1.991 +	    role="template-keyword">author</literal> keyword.  Extract
   1.992 +	  the first string that looks like an email address.  For
   1.993 +	  example, <quote><literal>Bryan O'Sullivan
   1.994 +	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
   1.995 +	  <quote><literal>bos@serpentine.com</literal></quote>.</para>
   1.996 +      </listitem>
   1.997 +      <listitem><para id="x_5a8"><literal
   1.998 +	    role="template-filter">escape</literal>: Any text.
   1.999 +	  Replace the special XML/XHTML characters
  1.1000 +	  <quote><literal>&amp;</literal></quote>,
  1.1001 +	  <quote><literal>&lt;</literal></quote> and
  1.1002 +	  <quote><literal>&gt;</literal></quote> with XML
  1.1003 +	  entities.</para>
  1.1004 +      </listitem>
  1.1005 +      <listitem><para id="x_5a9"><literal
  1.1006 +	    role="template-filter">fill68</literal>: Any text.  Wrap
  1.1007 +	  the text to fit in 68 columns.  This is useful before you
  1.1008 +	  pass text through the <literal
  1.1009 +	    role="template-filter">tabindent</literal> filter, and
  1.1010 +	  still want it to fit in an 80-column fixed-font
  1.1011 +	  window.</para>
  1.1012 +      </listitem>
  1.1013 +      <listitem><para id="x_5aa"><literal
  1.1014 +	    role="template-filter">fill76</literal>: Any text.  Wrap
  1.1015 +	  the text to fit in 76 columns.</para>
  1.1016 +      </listitem>
  1.1017 +      <listitem><para id="x_5ab"><literal
  1.1018 +	    role="template-filter">firstline</literal>: Any text.
  1.1019 +	  Yield the first line of text, without any trailing
  1.1020 +	  newlines.</para>
  1.1021 +      </listitem>
  1.1022 +      <listitem><para id="x_5ac"><literal
  1.1023 +	    role="template-kw-filt-date">hgdate</literal>: <literal
  1.1024 +	    role="template-keyword">date</literal> keyword.  Render
  1.1025 +	  the date as a pair of readable numbers.  Yields a string
  1.1026 +	  like <quote><literal>1157407993
  1.1027 +	      25200</literal></quote>.</para>
  1.1028 +      </listitem>
  1.1029 +      <listitem><para id="x_5ad"><literal
  1.1030 +	    role="template-kw-filt-date">isodate</literal>: <literal
  1.1031 +	    role="template-keyword">date</literal> keyword.  Render
  1.1032 +	  the date as a text string in ISO 8601 format.  Yields a
  1.1033 +	  string like <quote><literal>2006-09-04 15:13:13
  1.1034 +	      -0700</literal></quote>.</para>
  1.1035 +      </listitem>
  1.1036 +      <listitem><para id="x_5ae"><literal
  1.1037 +	    role="template-filter">obfuscate</literal>: Any text, but
  1.1038 +	  most useful for the <literal
  1.1039 +	    role="template-keyword">author</literal> keyword.  Yield
  1.1040 +	  the input text rendered as a sequence of XML entities.  This
  1.1041 +	  helps to defeat some particularly stupid screen-scraping
  1.1042 +	  email harvesting spambots.</para>
  1.1043 +      </listitem>
  1.1044 +      <listitem><para id="x_5af"><literal
  1.1045 +	    role="template-kw-filt-author">person</literal>: Any text,
  1.1046 +	  but most useful for the <literal
  1.1047 +	    role="template-keyword">author</literal> keyword.  Yield
  1.1048 +	  the text before an email address. For example,
  1.1049 +	  <quote><literal>Bryan O'Sullivan
  1.1050 +	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
  1.1051 +	  <quote><literal>Bryan O'Sullivan</literal></quote>.</para>
  1.1052 +      </listitem>
  1.1053 +      <listitem><para id="x_5b0"><literal
  1.1054 +	    role="template-kw-filt-date">rfc822date</literal>:
  1.1055 +	  <literal role="template-keyword">date</literal> keyword.
  1.1056 +	  Render a date using the same format used in email headers.
  1.1057 +	  Yields a string like <quote><literal>Mon, 04 Sep 2006
  1.1058 +	      15:13:13 -0700</literal></quote>.</para>
  1.1059 +      </listitem>
  1.1060 +      <listitem><para id="x_5b1"><literal
  1.1061 +	    role="template-kw-filt-node">short</literal>: Changeset
  1.1062 +	  hash.  Yield the short form of a changeset hash, i.e. a
  1.1063 +	  12-character hexadecimal string.</para>
  1.1064 +      </listitem>
  1.1065 +      <listitem><para id="x_5b2"><literal
  1.1066 +	    role="template-kw-filt-date">shortdate</literal>: <literal
  1.1067 +	    role="template-keyword">date</literal> keyword.  Render
  1.1068 +	  the year, month, and day of the date.  Yields a string like
  1.1069 +	  <quote><literal>2006-09-04</literal></quote>.</para>
  1.1070 +      </listitem>
  1.1071 +      <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>:
  1.1072 +	  Any text.  Strip all leading and trailing whitespace from
  1.1073 +	  the string.</para>
  1.1074 +      </listitem>
  1.1075 +      <listitem><para id="x_5b4"><literal
  1.1076 +	    role="template-filter">tabindent</literal>: Any text.
  1.1077 +	  Yield the text, with every line except the first starting
  1.1078 +	  with a tab character.</para>
  1.1079 +      </listitem>
  1.1080 +      <listitem><para id="x_5b5"><literal
  1.1081 +	    role="template-filter">urlescape</literal>: Any text.
  1.1082 +	  Escape all characters that are considered
  1.1083 +	  <quote>special</quote> by URL parsers.  For example,
  1.1084 +	  <literal>foo bar</literal> becomes
  1.1085 +	  <literal>foo%20bar</literal>.</para>
  1.1086 +      </listitem>
  1.1087 +      <listitem><para id="x_5b6"><literal
  1.1088 +	    role="template-kw-filt-author">user</literal>: Any text,
  1.1089 +	  but most useful for the <literal
  1.1090 +	    role="template-keyword">author</literal> keyword.  Return
  1.1091 +	  the <quote>user</quote> portion of an email address.  For
  1.1092 +	  example, <quote><literal>Bryan O'Sullivan
  1.1093 +	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
  1.1094 +	  <quote><literal>bos</literal></quote>.</para>
  1.1095 +      </listitem>
  1.1096 +    </itemizedlist>
  1.1097 +
  1.1098 +    &interaction.template.simple.manyfilters;
  1.1099 +
  1.1100 +    <note>
  1.1101 +      <para id="x_5b7">  If you try to apply a filter to a piece of data that it
  1.1102 +	cannot process, Mercurial will fail and print a Python
  1.1103 +	exception.  For example, trying to run the output of the
  1.1104 +	<literal role="template-keyword">desc</literal> keyword into
  1.1105 +	the <literal role="template-kw-filt-date">isodate</literal>
  1.1106 +	filter is not a good idea.</para>
  1.1107 +    </note>
  1.1108 +
  1.1109 +    <sect2>
  1.1110 +      <title>Combining filters</title>
  1.1111 +
  1.1112 +      <para id="x_5b8">It is easy to combine filters to yield output in the form
  1.1113 +	you would like.  The following chain of filters tidies up a
  1.1114 +	description, then makes sure that it fits cleanly into 68
  1.1115 +	columns, then indents it by a further 8 characters (at least
  1.1116 +	on Unix-like systems, where a tab is conventionally 8
  1.1117 +	characters wide).</para>
  1.1118 +
  1.1119 +      &interaction.template.simple.combine;
  1.1120 +
  1.1121 +      <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a
  1.1122 +	tab character) in the template to force the first line to be
  1.1123 +	indented; this is necessary since <literal
  1.1124 +	  role="template-keyword">tabindent</literal> indents all
  1.1125 +	lines <emphasis>except</emphasis> the first.</para>
  1.1126 +
  1.1127 +      <para id="x_5ba">Keep in mind that the order of filters in a chain is
  1.1128 +	significant.  The first filter is applied to the result of the
  1.1129 +	keyword; the second to the result of the first filter; and so
  1.1130 +	on.  For example, using <literal>fill68|tabindent</literal>
  1.1131 +	gives very different results from
  1.1132 +	<literal>tabindent|fill68</literal>.</para>
  1.1133 +    </sect2>
  1.1134 +  </sect1>
  1.1135 +
  1.1136 +  <sect1>
  1.1137 +    <title>From templates to styles</title>
  1.1138 +
  1.1139 +    <para id="x_5bb">A command line template provides a quick and simple way to
  1.1140 +      format some output.  Templates can become verbose, though, and
  1.1141 +      it's useful to be able to give a template a name.  A style file
  1.1142 +      is a template with a name, stored in a file.</para>
  1.1143 +
  1.1144 +    <para id="x_5bc">More than that, using a style file unlocks the power of
  1.1145 +      Mercurial's templating engine in ways that are not possible
  1.1146 +      using the command line <option
  1.1147 +	role="hg-opt-log">--template</option> option.</para>
  1.1148 +
  1.1149 +    <sect2>
  1.1150 +      <title>The simplest of style files</title>
  1.1151 +
  1.1152 +      <para id="x_5bd">Our simple style file contains just one line:</para>
  1.1153 +
  1.1154 +      &interaction.template.simple.rev;
  1.1155 +
  1.1156 +      <para id="x_5be">This tells Mercurial, <quote>if you're printing a
  1.1157 +	  changeset, use the text on the right as the
  1.1158 +	  template</quote>.</para>
  1.1159 +    </sect2>
  1.1160 +
  1.1161 +    <sect2>
  1.1162 +      <title>Style file syntax</title>
  1.1163 +
  1.1164 +      <para id="x_5bf">The syntax rules for a style file are simple.</para>
  1.1165 +
  1.1166 +      <itemizedlist>
  1.1167 +	<listitem><para id="x_5c0">The file is processed one line at a
  1.1168 +	    time.</para>
  1.1169 +	</listitem>
  1.1170 +	<listitem><para id="x_5c1">Leading and trailing white space are
  1.1171 +	    ignored.</para>
  1.1172 +	</listitem>
  1.1173 +	<listitem><para id="x_5c2">Empty lines are skipped.</para>
  1.1174 +	</listitem>
  1.1175 +	<listitem><para id="x_5c3">If a line starts with either of the characters
  1.1176 +	    <quote><literal>#</literal></quote> or
  1.1177 +	    <quote><literal>;</literal></quote>, the entire line is
  1.1178 +	    treated as a comment, and skipped as if empty.</para>
  1.1179 +	</listitem>
  1.1180 +	<listitem><para id="x_5c4">A line starts with a keyword.  This must start
  1.1181 +	    with an alphabetic character or underscore, and can
  1.1182 +	    subsequently contain any alphanumeric character or
  1.1183 +	    underscore.  (In regexp notation, a keyword must match
  1.1184 +	    <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
  1.1185 +	</listitem>
  1.1186 +	<listitem><para id="x_5c5">The next element must be an
  1.1187 +	    <quote><literal>=</literal></quote> character, which can
  1.1188 +	    be preceded or followed by an arbitrary amount of white
  1.1189 +	    space.</para>
  1.1190 +	</listitem>
  1.1191 +	<listitem><para id="x_5c6">If the rest of the line starts and ends with
  1.1192 +	    matching quote characters (either single or double quote),
  1.1193 +	    it is treated as a template body.</para>
  1.1194 +	</listitem>
  1.1195 +	<listitem><para id="x_5c7">If the rest of the line <emphasis>does
  1.1196 +	      not</emphasis> start with a quote character, it is
  1.1197 +	    treated as the name of a file; the contents of this file
  1.1198 +	    will be read and used as a template body.</para>
  1.1199 +	</listitem></itemizedlist>
  1.1200 +    </sect2>
  1.1201 +  </sect1>
  1.1202 +
  1.1203 +  <sect1>
  1.1204 +    <title>Style files by example</title>
  1.1205 +
  1.1206 +    <para id="x_5c8">To illustrate how to write a style file, we will construct a
  1.1207 +      few by example.  Rather than provide a complete style file and
  1.1208 +      walk through it, we'll mirror the usual process of developing a
  1.1209 +      style file by starting with something very simple, and walking
  1.1210 +      through a series of successively more complete examples.</para>
  1.1211 +
  1.1212 +    <sect2>
  1.1213 +      <title>Identifying mistakes in style files</title>
  1.1214 +
  1.1215 +      <para id="x_5c9">If Mercurial encounters a problem in a style file you are
  1.1216 +	working on, it prints a terse error message that, once you
  1.1217 +	figure out what it means, is actually quite useful.</para>
  1.1218 +
  1.1219 +&interaction.template.svnstyle.syntax.input;
  1.1220 +
  1.1221 +      <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to
  1.1222 +	define a <literal>changeset</literal> keyword, but forgets to
  1.1223 +	give any content for it. When instructed to use this style
  1.1224 +	file, Mercurial promptly complains.</para>
  1.1225 +
  1.1226 +      &interaction.template.svnstyle.syntax.error;
  1.1227 +
  1.1228 +      <para id="x_5cb">This error message looks intimidating, but it is not too
  1.1229 +	hard to follow.</para>
  1.1230 +
  1.1231 +      <itemizedlist>
  1.1232 +	<listitem><para id="x_5cc">The first component is simply Mercurial's way
  1.1233 +	    of saying <quote>I am giving up</quote>.</para>
  1.1234 +	  <programlisting>___abort___: broken.style:1: parse error</programlisting>
  1.1235 +	</listitem>
  1.1236 +	<listitem><para id="x_5cd">Next comes the name of the style file that
  1.1237 +	    contains the error.</para>
  1.1238 +	  <programlisting>abort: ___broken.style___:1: parse error</programlisting>
  1.1239 +	</listitem>
  1.1240 +	<listitem><para id="x_5ce">Following the file name is the line number
  1.1241 +	    where the error was encountered.</para>
  1.1242 +	  <programlisting>abort: broken.style:___1___: parse error</programlisting>
  1.1243 +	</listitem>
  1.1244 +	<listitem><para id="x_5cf">Finally, a description of what went
  1.1245 +	    wrong.</para>
  1.1246 +	  <programlisting>abort: broken.style:1: ___parse error___</programlisting>
  1.1247 +	</listitem>
  1.1248 +	<listitem><para id="x_5d0">The description of the problem is not always
  1.1249 +	    clear (as in this case), but even when it is cryptic, it
  1.1250 +	    is almost always trivial to visually inspect the offending
  1.1251 +	    line in the style file and see what is wrong.</para>
  1.1252 +	</listitem>
  1.1253 +      </itemizedlist>
  1.1254 +    </sect2>
  1.1255 +
  1.1256 +    <sect2>
  1.1257 +      <title>Uniquely identifying a repository</title>
  1.1258 +
  1.1259 +      <para id="x_5d1">If you would like to be able to identify a Mercurial
  1.1260 +	repository <quote>fairly uniquely</quote> using a short string
  1.1261 +	as an identifier, you can use the first revision in the
  1.1262 +	repository.</para>
  1.1263 +
  1.1264 +      &interaction.template.svnstyle.id;
  1.1265 +
  1.1266 +      <para id="x_5d2">This is likely to be unique, and so it is
  1.1267 +	useful in many cases.  There are a few caveats.</para>
  1.1268 +      <itemizedlist>
  1.1269 +	<listitem><para id="x_5d3">It will not work in a completely empty
  1.1270 +	    repository, because such a repository does not have a
  1.1271 +	    revision zero.</para>
  1.1272 +	</listitem>
  1.1273 +	<listitem><para id="x_5d4">Neither will it work in the (extremely rare)
  1.1274 +	    case where a repository is a merge of two or more formerly
  1.1275 +	    independent repositories, and you still have those
  1.1276 +	    repositories around.</para>
  1.1277 +	</listitem></itemizedlist>
  1.1278 +      <para id="x_5d5">Here are some uses to which you could put this
  1.1279 +	identifier:</para>
  1.1280 +      <itemizedlist>
  1.1281 +	<listitem><para id="x_5d6">As a key into a table for a database that
  1.1282 +	    manages repositories on a server.</para>
  1.1283 +	</listitem>
  1.1284 +	<listitem><para id="x_5d7">As half of a {<emphasis>repository
  1.1285 +	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
  1.1286 +	    Save this information away when you run an automated build
  1.1287 +	    or other activity, so that you can <quote>replay</quote>
  1.1288 +	    the build later if necessary.</para>
  1.1289 +	</listitem>
  1.1290 +      </itemizedlist>
  1.1291 +    </sect2>
  1.1292 +
  1.1293 +    <sect2>
  1.1294 +      <title>Listing files on multiple lines</title>
  1.1295 +
  1.1296 +      <para id="x_714">Suppose we want to list the files changed by a changeset,
  1.1297 +	one per line, with a little indentation before each file
  1.1298 +	name.</para>
  1.1299 +
  1.1300 +      &interaction.ch10-multiline.go;
  1.1301 +    </sect2>
  1.1302 +
  1.1303 +    <sect2>
  1.1304 +      <title>Mimicking Subversion's output</title>
  1.1305 +
  1.1306 +      <para id="x_5d8">Let's try to emulate the default output format used by
  1.1307 +	another revision control tool, Subversion.</para>
  1.1308 +
  1.1309 +      &interaction.template.svnstyle.short;
  1.1310 +
  1.1311 +      <para id="x_5d9">Since Subversion's output style is fairly simple, it is
  1.1312 +	easy to copy-and-paste a hunk of its output into a file, and
  1.1313 +	replace the text produced above by Subversion with the
  1.1314 +	template values we'd like to see expanded.</para>
  1.1315 +
  1.1316 +      &interaction.template.svnstyle.template;
  1.1317 +
  1.1318 +      <para id="x_5da">There are a few small ways in which this template deviates
  1.1319 +	from the output produced by Subversion.</para>
  1.1320 +      <itemizedlist>
  1.1321 +	<listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
  1.1322 +	    date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the
  1.1323 +	    example output above) in parentheses.  Mercurial's
  1.1324 +	    templating engine does not provide a way to display a date
  1.1325 +	    in this format without also printing the time and time
  1.1326 +	    zone.</para>
  1.1327 +	</listitem>
  1.1328 +	<listitem><para id="x_5dc">We emulate Subversion's printing of
  1.1329 +	    <quote>separator</quote> lines full of
  1.1330 +	    <quote><literal>-</literal></quote> characters by ending
  1.1331 +	    the template with such a line. We use the templating
  1.1332 +	    engine's <literal role="template-keyword">header</literal>
  1.1333 +	    keyword to print a separator line as the first line of
  1.1334 +	    output (see below), thus achieving similar output to
  1.1335 +	    Subversion.</para>
  1.1336 +	</listitem>
  1.1337 +	<listitem><para id="x_5dd">Subversion's output includes a count in the
  1.1338 +	    header of the number of lines in the commit message.  We
  1.1339 +	    cannot replicate this in Mercurial; the templating engine
  1.1340 +	    does not currently provide a filter that counts the number
  1.1341 +	    of lines the template generates.</para>
  1.1342 +	</listitem></itemizedlist>
  1.1343 +      <para id="x_5de">It took me no more than a minute or two of work to replace
  1.1344 +	literal text from an example of Subversion's output with some
  1.1345 +	keywords and filters to give the template above.  The style
  1.1346 +	file simply refers to the template.</para>
  1.1347 +
  1.1348 +      &interaction.template.svnstyle.style;
  1.1349 +
  1.1350 +      <para id="x_5df">We could have included the text of the template file
  1.1351 +	directly in the style file by enclosing it in quotes and
  1.1352 +	replacing the newlines with
  1.1353 +	<quote><literal>\n</literal></quote> sequences, but it would
  1.1354 +	have made the style file too difficult to read.  Readability
  1.1355 +	is a good guide when you're trying to decide whether some text
  1.1356 +	belongs in a style file, or in a template file that the style
  1.1357 +	file points to.  If the style file will look too big or
  1.1358 +	cluttered if you insert a literal piece of text, drop it into
  1.1359 +	a template instead.</para>
  1.1360 +    </sect2>
  1.1361 +  </sect1>
  1.1362  </chapter>
  1.1363  
  1.1364  <!--
  1.1365  local variables: 
  1.1366  sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1367  end:
  1.1368 --->
  1.1369 \ No newline at end of file
  1.1370 +-->