bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
bos@559: <chapter id="chap:template">
bos@572:   <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
bos@559:   <title>Customising the output of Mercurial</title>
bos@559: 
bos@584:   <para id="x_578">Mercurial provides a powerful mechanism to let you control how
bos@559:     it displays information.  The mechanism is based on templates.
bos@559:     You can use templates to generate specific output for a single
bos@559:     command, or to customise the entire appearance of the built-in web
bos@559:     interface.</para>
bos@559: 
bos@559:   <sect1 id="sec:style">
bos@559:     <title>Using precanned output styles</title>
bos@559: 
bos@584:     <para id="x_579">Packaged with Mercurial are some output styles that you can
bos@559:       use immediately.  A style is simply a precanned template that
bos@559:       someone wrote and installed somewhere that Mercurial can
bos@559:       find.</para>
bos@559: 
bos@584:     <para id="x_57a">Before we take a look at Mercurial's bundled styles, let's
bos@559:       review its normal output.</para>
bos@559: 
bos@567:     &interaction.template.simple.normal;
bos@559: 
bos@584:     <para id="x_57b">This is somewhat informative, but it takes up a lot of
bos@559:       space&emdash;five lines of output per changeset.  The
bos@559:       <literal>compact</literal> style reduces this to three lines,
bos@559:       presented in a sparse manner.</para>
bos@559: 
bos@567:     &interaction.template.simple.compact;
bos@559: 
bos@584:     <para id="x_57c">The <literal>changelog</literal> style hints at the
bos@559:       expressive power of Mercurial's templating engine.  This style
bos@559:       attempts to follow the GNU Project's changelog
bos@559:       guidelines<citation>web:changelog</citation>.</para>
bos@559: 
bos@567:     &interaction.template.simple.changelog;
bos@559: 
bos@584:     <para id="x_57d">You will not be shocked to learn that Mercurial's default
bos@559:       output style is named <literal>default</literal>.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Setting a default style</title>
bos@559: 
bos@584:       <para id="x_57e">You can modify the output style that Mercurial will use
bos@580: 	for every command by editing your <filename
bos@580: 	  role="special">~/.hgrc</filename> file, naming the style
bos@580: 	you would prefer to use.</para>
bos@580: 
bos@580:       <programlisting>[ui]
bos@580: style = compact</programlisting>
bos@559: 
bos@584:       <para id="x_57f">If you write a style of your own, you can use it by either
bos@559: 	providing the path to your style file, or copying your style
bos@559: 	file into a location where Mercurial can find it (typically
bos@559: 	the <literal>templates</literal> subdirectory of your
bos@559: 	Mercurial install directory).</para>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Commands that support styles and templates</title>
bos@559: 
bos@584:     <para id="x_580">All of Mercurial's
bos@559:       <quote><literal>log</literal>-like</quote> commands let you use
bos@559:       styles and templates: <command role="hg-cmd">hg
bos@559: 	incoming</command>, <command role="hg-cmd">hg log</command>,
bos@559:       <command role="hg-cmd">hg outgoing</command>, and <command
bos@559: 	role="hg-cmd">hg tip</command>.</para>
bos@559: 
bos@584:     <para id="x_581">As I write this manual, these are so far the only commands
bos@559:       that support styles and templates.  Since these are the most
bos@559:       important commands that need customisable output, there has been
bos@559:       little pressure from the Mercurial user community to add style
bos@559:       and template support to other commands.</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>The basics of templating</title>
bos@559: 
bos@584:     <para id="x_582">At its simplest, a Mercurial template is a piece of text.
bos@559:       Some of the text never changes, while other parts are
bos@559:       <emphasis>expanded</emphasis>, or replaced with new text, when
bos@559:       necessary.</para>
bos@559: 
bos@584:     <para id="x_583">Before we continue, let's look again at a simple example of
bos@559:       Mercurial's normal output.</para>
bos@559: 
bos@567:     &interaction.template.simple.normal;
bos@559: 
bos@584:     <para id="x_584">Now, let's run the same command, but using a template to
bos@559:       change its output.</para>
bos@559: 
bos@567:     &interaction.template.simple.simplest;
bos@559: 
bos@584:     <para id="x_585">The example above illustrates the simplest possible
bos@559:       template; it's just a piece of static text, printed once for
bos@559:       each changeset.  The <option
bos@559: 	role="hg-opt-log">--template</option> option to the <command
bos@559: 	role="hg-cmd">hg log</command> command tells Mercurial to use
bos@559:       the given text as the template when printing each
bos@559:       changeset.</para>
bos@559: 
bos@584:     <para id="x_586">Notice that the template string above ends with the text
bos@559:       <quote><literal>\n</literal></quote>.  This is an
bos@559:       <emphasis>escape sequence</emphasis>, telling Mercurial to print
bos@559:       a newline at the end of each template item.  If you omit this
bos@559:       newline, Mercurial will run each piece of output together.  See
bos@592:       <xref linkend="sec:template:escape"/> for more details
bos@559:       of escape sequences.</para>
bos@559: 
bos@584:     <para id="x_587">A template that prints a fixed string of text all the time
bos@559:       isn't very useful; let's try something a bit more
bos@559:       complex.</para>
bos@559: 
bos@567:     &interaction.template.simple.simplesub;
bos@559: 
bos@584:     <para id="x_588">As you can see, the string
bos@559:       <quote><literal>{desc}</literal></quote> in the template has
bos@559:       been replaced in the output with the description of each
bos@559:       changeset.  Every time Mercurial finds text enclosed in curly
bos@559:       braces (<quote><literal>{</literal></quote> and
bos@592:       <quote><literal>}</literal></quote>), it will try to replace the
bos@592:       braces and text with the expansion of whatever is inside.  To
bos@592:       print a literal curly brace, you must escape it, as described in
bos@592:       <xref linkend="sec:template:escape"/>.</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1 id="sec:template:keyword">
bos@559:     <title>Common template keywords</title>
bos@559: 
bos@584:     <para id="x_589">You can start writing simple templates immediately using the
bos@559:       keywords below.</para>
bos@559: 
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_58a"><literal
bos@559: 	    role="template-keyword">author</literal>: String.  The
bos@559: 	  unmodified author of the changeset.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_58b"><literal
bos@559: 	    role="template-keyword">branches</literal>: String.  The
bos@559: 	  name of the branch on which the changeset was committed.
bos@559: 	  Will be empty if the branch name was
bos@559: 	  <literal>default</literal>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_58c"><literal role="template-keyword">date</literal>:
bos@559: 	  Date information.  The date when the changeset was
bos@559: 	  committed.  This is <emphasis>not</emphasis> human-readable;
bos@559: 	  you must pass it through a filter that will render it
bos@592: 	  appropriately.  See <xref
bos@559: 	    linkend="sec:template:filter"/> for more information
bos@559: 	  on filters. The date is expressed as a pair of numbers.  The
bos@559: 	  first number is a Unix UTC timestamp (seconds since January
bos@559: 	  1, 1970); the second is the offset of the committer's
bos@559: 	  timezone from UTC, in seconds.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_58d"><literal role="template-keyword">desc</literal>:
bos@559: 	  String.  The text of the changeset description.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_58e"><literal
bos@559: 	    role="template-keyword">files</literal>: List of strings.
bos@559: 	  All files modified, added, or removed by this
bos@559: 	  changeset.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_58f"><literal
bos@559: 	    role="template-keyword">file_adds</literal>: List of
bos@559: 	  strings.  Files added by this changeset.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_590"><literal
bos@559: 	    role="template-keyword">file_dels</literal>: List of
bos@559: 	  strings.  Files removed by this changeset.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_591"><literal role="template-keyword">node</literal>:
bos@559: 	  String.  The changeset identification hash, as a
bos@559: 	  40-character hexadecimal string.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_592"><literal
bos@559: 	    role="template-keyword">parents</literal>: List of
bos@559: 	  strings.  The parents of the changeset.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_593"><literal role="template-keyword">rev</literal>:
bos@559: 	  Integer.  The repository-local changeset revision
bos@559: 	  number.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_594"><literal role="template-keyword">tags</literal>:
bos@559: 	  List of strings.  Any tags associated with the
bos@559: 	  changeset.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@584:     <para id="x_595">A few simple experiments will show us what to expect when we
bos@559:       use these keywords; you can see the results below.</para>
bos@559: 
bos@567: &interaction.template.simple.keywords;
bos@559: 
bos@584:     <para id="x_596">As we noted above, the date keyword does not produce
bos@559:       human-readable output, so we must treat it specially.  This
bos@559:       involves using a <emphasis>filter</emphasis>, about which more
bos@592:       in <xref linkend="sec:template:filter"/>.</para>
bos@559: 
bos@567:     &interaction.template.simple.datekeyword;
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1 id="sec:template:escape">
bos@559:     <title>Escape sequences</title>
bos@559: 
bos@584:     <para id="x_597">Mercurial's templating engine recognises the most commonly
bos@559:       used escape sequences in strings.  When it sees a backslash
bos@559:       (<quote><literal>\</literal></quote>) character, it looks at the
bos@559:       following character and substitutes the two characters with a
bos@559:       single replacement, as described below.</para>
bos@559: 
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_598"><literal>\</literal>:
bos@559: 	  Backslash, <quote><literal>\</literal></quote>, ASCII
bos@559: 	  134.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_599"><literal>\n</literal>: Newline,
bos@559: 	  ASCII 12.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_59a"><literal>\r</literal>: Carriage
bos@559: 	  return, ASCII 15.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_59b"><literal>\t</literal>: Tab, ASCII
bos@559: 	  11.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_59c"><literal>\v</literal>: Vertical
bos@559: 	  tab, ASCII 13.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_59d"><literal>{</literal>: Open curly
bos@559: 	  brace, <quote><literal>{</literal></quote>, ASCII
bos@559: 	  173.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_59e"><literal>}</literal>: Close curly
bos@559: 	  brace, <quote><literal>}</literal></quote>, ASCII
bos@559: 	  175.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@584:     <para id="x_59f">As indicated above, if you want the expansion of a template
bos@559:       to contain a literal <quote><literal>\</literal></quote>,
bos@559:       <quote><literal>{</literal></quote>, or
bos@559:       <quote><literal>{</literal></quote> character, you must escape
bos@559:       it.</para>
bos@559: 
bos@559:   </sect1>
bos@559:   <sect1 id="sec:template:filter">
bos@559:     <title>Filtering keywords to change their results</title>
bos@559: 
bos@584:     <para id="x_5a0">Some of the results of template expansion are not
bos@559:       immediately easy to use.  Mercurial lets you specify an optional
bos@559:       chain of <emphasis>filters</emphasis> to modify the result of
bos@559:       expanding a keyword.  You have already seen a common filter,
bos@559:       <literal role="template-kw-filt-date">isodate</literal>, in
bos@559:       action above, to make a date readable.</para>
bos@559: 
bos@584:     <para id="x_5a1">Below is a list of the most commonly used filters that
bos@559:       Mercurial supports.  While some filters can be applied to any
bos@559:       text, others can only be used in specific circumstances.  The
bos@559:       name of each filter is followed first by an indication of where
bos@559:       it can be used, then a description of its effect.</para>
bos@559: 
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_5a2"><literal
bos@559: 	    role="template-filter">addbreaks</literal>: Any text. Add
bos@559: 	  an XHTML <quote><literal>&lt;br/&gt;</literal></quote> tag
bos@559: 	  before the end of every line except the last.  For example,
bos@559: 	  <quote><literal>foo\nbar</literal></quote> becomes
bos@559: 	  <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a3"><literal
bos@559: 	    role="template-kw-filt-date">age</literal>: <literal
bos@559: 	    role="template-keyword">date</literal> keyword.  Render
bos@559: 	  the age of the date, relative to the current time.  Yields a
bos@559: 	  string like <quote><literal>10
bos@559: 	      minutes</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a4"><literal
bos@559: 	    role="template-filter">basename</literal>: Any text, but
bos@559: 	  most useful for the <literal
bos@559: 	    role="template-keyword">files</literal> keyword and its
bos@559: 	  relatives.  Treat the text as a path, and return the
bos@559: 	  basename. For example,
bos@559: 	  <quote><literal>foo/bar/baz</literal></quote> becomes
bos@559: 	  <quote><literal>baz</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a5"><literal
bos@559: 	    role="template-kw-filt-date">date</literal>: <literal
bos@559: 	    role="template-keyword">date</literal> keyword.  Render a
bos@559: 	  date in a similar format to the Unix <literal
bos@559: 	    role="template-keyword">date</literal> command, but with
bos@559: 	  timezone included.  Yields a string like <quote><literal>Mon
bos@559: 	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a6"><literal
bos@559: 	    role="template-kw-filt-author">domain</literal>: Any text,
bos@559: 	  but most useful for the <literal
bos@559: 	    role="template-keyword">author</literal> keyword.  Finds
bos@559: 	  the first string that looks like an email address, and
bos@559: 	  extract just the domain component.  For example,
bos@559: 	  <quote><literal>Bryan O'Sullivan
bos@559: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
bos@559: 	  <quote><literal>serpentine.com</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a7"><literal
bos@559: 	    role="template-kw-filt-author">email</literal>: Any text,
bos@559: 	  but most useful for the <literal
bos@559: 	    role="template-keyword">author</literal> keyword.  Extract
bos@559: 	  the first string that looks like an email address.  For
bos@559: 	  example, <quote><literal>Bryan O'Sullivan
bos@559: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
bos@559: 	  <quote><literal>bos@serpentine.com</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a8"><literal
bos@559: 	    role="template-filter">escape</literal>: Any text.
bos@559: 	  Replace the special XML/XHTML characters
bos@559: 	  <quote><literal>&amp;</literal></quote>,
bos@559: 	  <quote><literal>&lt;</literal></quote> and
bos@559: 	  <quote><literal>&gt;</literal></quote> with XML
bos@559: 	  entities.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5a9"><literal
bos@559: 	    role="template-filter">fill68</literal>: Any text.  Wrap
bos@559: 	  the text to fit in 68 columns.  This is useful before you
bos@559: 	  pass text through the <literal
bos@559: 	    role="template-filter">tabindent</literal> filter, and
bos@559: 	  still want it to fit in an 80-column fixed-font
bos@559: 	  window.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5aa"><literal
bos@559: 	    role="template-filter">fill76</literal>: Any text.  Wrap
bos@559: 	  the text to fit in 76 columns.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5ab"><literal
bos@559: 	    role="template-filter">firstline</literal>: Any text.
bos@559: 	  Yield the first line of text, without any trailing
bos@559: 	  newlines.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5ac"><literal
bos@559: 	    role="template-kw-filt-date">hgdate</literal>: <literal
bos@559: 	    role="template-keyword">date</literal> keyword.  Render
bos@559: 	  the date as a pair of readable numbers.  Yields a string
bos@559: 	  like <quote><literal>1157407993
bos@559: 	      25200</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5ad"><literal
bos@559: 	    role="template-kw-filt-date">isodate</literal>: <literal
bos@559: 	    role="template-keyword">date</literal> keyword.  Render
bos@559: 	  the date as a text string in ISO 8601 format.  Yields a
bos@559: 	  string like <quote><literal>2006-09-04 15:13:13
bos@559: 	      -0700</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5ae"><literal
bos@559: 	    role="template-filter">obfuscate</literal>: Any text, but
bos@559: 	  most useful for the <literal
bos@559: 	    role="template-keyword">author</literal> keyword.  Yield
bos@559: 	  the input text rendered as a sequence of XML entities.  This
bos@559: 	  helps to defeat some particularly stupid screen-scraping
bos@559: 	  email harvesting spambots.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5af"><literal
bos@559: 	    role="template-kw-filt-author">person</literal>: Any text,
bos@559: 	  but most useful for the <literal
bos@559: 	    role="template-keyword">author</literal> keyword.  Yield
bos@559: 	  the text before an email address. For example,
bos@559: 	  <quote><literal>Bryan O'Sullivan
bos@559: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
bos@559: 	  <quote><literal>Bryan O'Sullivan</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b0"><literal
bos@559: 	    role="template-kw-filt-date">rfc822date</literal>:
bos@559: 	  <literal role="template-keyword">date</literal> keyword.
bos@559: 	  Render a date using the same format used in email headers.
bos@559: 	  Yields a string like <quote><literal>Mon, 04 Sep 2006
bos@559: 	      15:13:13 -0700</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b1"><literal
bos@559: 	    role="template-kw-filt-node">short</literal>: Changeset
bos@559: 	  hash.  Yield the short form of a changeset hash, i.e. a
bos@559: 	  12-character hexadecimal string.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b2"><literal
bos@559: 	    role="template-kw-filt-date">shortdate</literal>: <literal
bos@559: 	    role="template-keyword">date</literal> keyword.  Render
bos@559: 	  the year, month, and day of the date.  Yields a string like
bos@559: 	  <quote><literal>2006-09-04</literal></quote>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b3"><literal role="template-filter">strip</literal>:
bos@559: 	  Any text.  Strip all leading and trailing whitespace from
bos@559: 	  the string.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b4"><literal
bos@559: 	    role="template-filter">tabindent</literal>: Any text.
bos@559: 	  Yield the text, with every line except the first starting
bos@559: 	  with a tab character.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b5"><literal
bos@559: 	    role="template-filter">urlescape</literal>: Any text.
bos@559: 	  Escape all characters that are considered
bos@559: 	  <quote>special</quote> by URL parsers.  For example,
bos@559: 	  <literal>foo bar</literal> becomes
bos@559: 	  <literal>foo%20bar</literal>.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_5b6"><literal
bos@559: 	    role="template-kw-filt-author">user</literal>: Any text,
bos@559: 	  but most useful for the <literal
bos@559: 	    role="template-keyword">author</literal> keyword.  Return
bos@559: 	  the <quote>user</quote> portion of an email address.  For
bos@559: 	  example, <quote><literal>Bryan O'Sullivan
bos@559: 	      &lt;bos@serpentine.com&gt;</literal></quote> becomes
bos@559: 	  <quote><literal>bos</literal></quote>.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@567: &interaction.template.simple.manyfilters;
bos@559: 
bos@559:     <note>
bos@584:       <para id="x_5b7">  If you try to apply a filter to a piece of data that it
bos@559: 	cannot process, Mercurial will fail and print a Python
bos@559: 	exception.  For example, trying to run the output of the
bos@559: 	<literal role="template-keyword">desc</literal> keyword into
bos@559: 	the <literal role="template-kw-filt-date">isodate</literal>
bos@559: 	filter is not a good idea.</para>
bos@559:     </note>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Combining filters</title>
bos@559: 
bos@584:       <para id="x_5b8">It is easy to combine filters to yield output in the form
bos@559: 	you would like.  The following chain of filters tidies up a
bos@559: 	description, then makes sure that it fits cleanly into 68
bos@559: 	columns, then indents it by a further 8 characters (at least
bos@559: 	on Unix-like systems, where a tab is conventionally 8
bos@559: 	characters wide).</para>
bos@559: 
bos@567:       &interaction.template.simple.combine;
bos@559: 
bos@584:       <para id="x_5b9">Note the use of <quote><literal>\t</literal></quote> (a
bos@559: 	tab character) in the template to force the first line to be
bos@559: 	indented; this is necessary since <literal
bos@559: 	  role="template-keyword">tabindent</literal> indents all
bos@559: 	lines <emphasis>except</emphasis> the first.</para>
bos@559: 
bos@584:       <para id="x_5ba">Keep in mind that the order of filters in a chain is
bos@559: 	significant.  The first filter is applied to the result of the
bos@559: 	keyword; the second to the result of the first filter; and so
bos@559: 	on.  For example, using <literal>fill68|tabindent</literal>
bos@559: 	gives very different results from
bos@559: 	<literal>tabindent|fill68</literal>.</para>
bos@559: 
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>From templates to styles</title>
bos@559: 
bos@584:     <para id="x_5bb">A command line template provides a quick and simple way to
bos@559:       format some output.  Templates can become verbose, though, and
bos@559:       it's useful to be able to give a template a name.  A style file
bos@559:       is a template with a name, stored in a file.</para>
bos@559: 
bos@584:     <para id="x_5bc">More than that, using a style file unlocks the power of
bos@559:       Mercurial's templating engine in ways that are not possible
bos@559:       using the command line <option
bos@559: 	role="hg-opt-log">--template</option> option.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>The simplest of style files</title>
bos@559: 
bos@584:       <para id="x_5bd">Our simple style file contains just one line:</para>
bos@559: 
bos@567:       &interaction.template.simple.rev;
bos@559: 
bos@584:       <para id="x_5be">This tells Mercurial, <quote>if you're printing a
bos@559: 	  changeset, use the text on the right as the
bos@559: 	  template</quote>.</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Style file syntax</title>
bos@559: 
bos@584:       <para id="x_5bf">The syntax rules for a style file are simple.</para>
bos@559: 
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_5c0">The file is processed one line at a
bos@559: 	    time.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c1">Leading and trailing white space are
bos@559: 	    ignored.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c2">Empty lines are skipped.</para>
bos@584: 	</listitem>
bos@584: 	<listitem><para id="x_5c3">If a line starts with either of the characters
bos@559: 	    <quote><literal>#</literal></quote> or
bos@559: 	    <quote><literal>;</literal></quote>, the entire line is
bos@559: 	    treated as a comment, and skipped as if empty.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c4">A line starts with a keyword.  This must start
bos@559: 	    with an alphabetic character or underscore, and can
bos@559: 	    subsequently contain any alphanumeric character or
bos@559: 	    underscore.  (In regexp notation, a keyword must match
bos@559: 	    <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c5">The next element must be an
bos@559: 	    <quote><literal>=</literal></quote> character, which can
bos@559: 	    be preceded or followed by an arbitrary amount of white
bos@559: 	    space.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c6">If the rest of the line starts and ends with
bos@559: 	    matching quote characters (either single or double quote),
bos@559: 	    it is treated as a template body.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5c7">If the rest of the line <emphasis>does
bos@559: 	      not</emphasis> start with a quote character, it is
bos@559: 	    treated as the name of a file; the contents of this file
bos@559: 	    will be read and used as a template body.</para>
bos@559: 	</listitem></itemizedlist>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Style files by example</title>
bos@559: 
bos@584:     <para id="x_5c8">To illustrate how to write a style file, we will construct a
bos@559:       few by example.  Rather than provide a complete style file and
bos@559:       walk through it, we'll mirror the usual process of developing a
bos@559:       style file by starting with something very simple, and walking
bos@559:       through a series of successively more complete examples.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Identifying mistakes in style files</title>
bos@559: 
bos@584:       <para id="x_5c9">If Mercurial encounters a problem in a style file you are
bos@559: 	working on, it prints a terse error message that, once you
bos@559: 	figure out what it means, is actually quite useful.</para>
bos@559: 
bos@567: &interaction.template.svnstyle.syntax.input;
bos@559: 
bos@584:       <para id="x_5ca">Notice that <filename>broken.style</filename> attempts to
bos@559: 	define a <literal>changeset</literal> keyword, but forgets to
bos@559: 	give any content for it. When instructed to use this style
bos@559: 	file, Mercurial promptly complains.</para>
bos@559: 
bos@567:       &interaction.template.svnstyle.syntax.error;
bos@559: 
bos@584:       <para id="x_5cb">This error message looks intimidating, but it is not too
bos@559: 	hard to follow.</para>
bos@559: 
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_5cc">The first component is simply Mercurial's way
bos@559: 	    of saying <quote>I am giving up</quote>.</para>
bos@580: 	  <programlisting>___abort___: broken.style:1: parse error</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5cd">Next comes the name of the style file that
bos@559: 	    contains the error.</para>
bos@580: 	  <programlisting>abort: ___broken.style___:1: parse error</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5ce">Following the file name is the line number
bos@559: 	    where the error was encountered.</para>
bos@580: 	  <programlisting>abort: broken.style:___1___: parse error</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5cf">Finally, a description of what went
bos@559: 	    wrong.</para>
bos@580: 	  <programlisting>abort: broken.style:1: ___parse error___</programlisting>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5d0">The description of the problem is not always
bos@559: 	    clear (as in this case), but even when it is cryptic, it
bos@559: 	    is almost always trivial to visually inspect the offending
bos@559: 	    line in the style file and see what is wrong.</para>
bos@559: 	</listitem></itemizedlist>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Uniquely identifying a repository</title>
bos@559: 
bos@584:       <para id="x_5d1">If you would like to be able to identify a Mercurial
bos@559: 	repository <quote>fairly uniquely</quote> using a short string
bos@559: 	as an identifier, you can use the first revision in the
bos@567: 	repository.</para>
bos@567: 
bos@567:       &interaction.template.svnstyle.id;
bos@567: 
bos@584:       <para id="x_5d2">This is not guaranteed to be unique, but it is
bos@567: 	nevertheless useful in many cases.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_5d3">It will not work in a completely empty
bos@559: 	    repository, because such a repository does not have a
bos@559: 	    revision zero.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5d4">Neither will it work in the (extremely rare)
bos@559: 	    case where a repository is a merge of two or more formerly
bos@559: 	    independent repositories, and you still have those
bos@559: 	    repositories around.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_5d5">Here are some uses to which you could put this
bos@559: 	identifier:</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_5d6">As a key into a table for a database that
bos@559: 	    manages repositories on a server.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5d7">As half of a {<emphasis>repository
bos@559: 	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
bos@559: 	    Save this information away when you run an automated build
bos@559: 	    or other activity, so that you can <quote>replay</quote>
bos@559: 	    the build later if necessary.</para>
bos@559: 	</listitem></itemizedlist>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Mimicking Subversion's output</title>
bos@559: 
bos@584:       <para id="x_5d8">Let's try to emulate the default output format used by
bos@567: 	another revision control tool, Subversion.</para>
bos@567: 
bos@567:       &interaction.template.svnstyle.short;
bos@559: 
bos@584:       <para id="x_5d9">Since Subversion's output style is fairly simple, it is
bos@559: 	easy to copy-and-paste a hunk of its output into a file, and
bos@559: 	replace the text produced above by Subversion with the
bos@567: 	template values we'd like to see expanded.</para>
bos@567: 
bos@567:       &interaction.template.svnstyle.template;
bos@559: 
bos@584:       <para id="x_5da">There are a few small ways in which this template deviates
bos@559: 	from the output produced by Subversion.</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_5db">Subversion prints a <quote>readable</quote>
ori@561: 	    date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the
bos@559: 	    example output above) in parentheses.  Mercurial's
bos@559: 	    templating engine does not provide a way to display a date
bos@559: 	    in this format without also printing the time and time
bos@559: 	    zone.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5dc">We emulate Subversion's printing of
bos@559: 	    <quote>separator</quote> lines full of
bos@559: 	    <quote><literal>-</literal></quote> characters by ending
bos@559: 	    the template with such a line. We use the templating
bos@559: 	    engine's <literal role="template-keyword">header</literal>
bos@559: 	    keyword to print a separator line as the first line of
bos@559: 	    output (see below), thus achieving similar output to
bos@559: 	    Subversion.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_5dd">Subversion's output includes a count in the
bos@559: 	    header of the number of lines in the commit message.  We
bos@559: 	    cannot replicate this in Mercurial; the templating engine
bos@559: 	    does not currently provide a filter that counts the number
bos@559: 	    of lines the template generates.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_5de">It took me no more than a minute or two of work to replace
bos@559: 	literal text from an example of Subversion's output with some
bos@559: 	keywords and filters to give the template above.  The style
bos@567: 	file simply refers to the template.</para>
bos@567: 
bos@567:       &interaction.template.svnstyle.style;
bos@559: 
bos@584:       <para id="x_5df">We could have included the text of the template file
bos@559: 	directly in the style file by enclosing it in quotes and
bos@559: 	replacing the newlines with
bos@559: 	<quote><literal>\n</literal></quote> sequences, but it would
bos@559: 	have made the style file too difficult to read.  Readability
bos@559: 	is a good guide when you're trying to decide whether some text
bos@559: 	belongs in a style file, or in a template file that the style
bos@559: 	file points to.  If the style file will look too big or
bos@559: 	cluttered if you insert a literal piece of text, drop it into
bos@559: 	a template instead.</para>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559: </chapter>
bos@559: 
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559: end:
bos@559: -->