hgbook
diff fr/ch11-template.xml @ 1114:527b86d55d4a
inotify: update installation information
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
inotify is shipped in Mercurial since 1.0, which greatly simplifies the installation process
author | Nicolas Dumazet <nicdumz.commits@gmail.com> |
---|---|
date | Sun Dec 13 16:35:56 2009 +0900 (2009-12-13) |
parents | 6b680d569bb4 f0110009e946 |
children |
line diff
1.1 --- a/fr/ch11-template.xml Sun Aug 16 04:58:01 2009 +0200 1.2 +++ b/fr/ch11-template.xml Sun Dec 13 16:35:56 2009 +0900 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><br/></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<br/>\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 <bos@serpentine.com></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 <bos@serpentine.com></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>&</literal></quote>, <quote><literal><</literal></quote> and <quote><literal>></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 <bos@serpentine.com></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 <bos@serpentine.com></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><br/></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<br/>\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 + <bos@serpentine.com></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 + <bos@serpentine.com></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>&</literal></quote>, 1.1001 + <quote><literal><</literal></quote> and 1.1002 + <quote><literal>></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 + <bos@serpentine.com></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 + <bos@serpentine.com></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 +-->