annotate en/ch11-template.xml @ 671:13513d2a128d

Add sensible names to chapters.

<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->

<chapter id="chap:template">
  <?dbhtml filename="customizing-the-output-of-mercurial.html"?>
  <title>Customising the output of Mercurial</title>

  <para>Mercurial provides a powerful mechanism to let you control how
    it displays information.  The mechanism is based on templates.
    You can use templates to generate specific output for a single
    command, or to customise the entire appearance of the built-in web
    interface.</para>

  <sect1 id="sec:style">
    <title>Using precanned output styles</title>

    <para>Packaged with Mercurial are some output styles that you can
      use immediately.  A style is simply a precanned template that
      someone wrote and installed somewhere that Mercurial can
      find.</para>

    <para>Before we take a look at Mercurial's bundled styles, let's
      review its normal output.</para>

    &interaction.template.simple.normal;

    <para>This is somewhat informative, but it takes up a lot of
      space&emdash;five lines of output per changeset.  The
      <literal>compact</literal> style reduces this to three lines,
      presented in a sparse manner.</para>

    &interaction.template.simple.compact;

    <para>The <literal>changelog</literal> style hints at the
      expressive power of Mercurial's templating engine.  This style
      attempts to follow the GNU Project's changelog
      guidelines<citation>web:changelog</citation>.</para>

    &interaction.template.simple.changelog;

    <para>You will not be shocked to learn that Mercurial's default
      output style is named <literal>default</literal>.</para>

    <sect2>
      <title>Setting a default style</title>

      <para>You can modify the output style that Mercurial will use
	for every command by editing your <filename role="special">
	  /.hgrc</filename>\ file, naming the style you would prefer
	to use.</para>

      <programlisting>[ui] style = compact</programlisting>

      <para>If you write a style of your own, you can use it by either
	providing the path to your style file, or copying your style
	file into a location where Mercurial can find it (typically
	the <literal>templates</literal> subdirectory of your
	Mercurial install directory).</para>

    </sect2>
  </sect1>
  <sect1>
    <title>Commands that support styles and templates</title>

    <para>All of Mercurial's
      <quote><literal>log</literal>-like</quote> commands let you use
      styles and templates: <command role="hg-cmd">hg
	incoming</command>, <command role="hg-cmd">hg log</command>,
      <command role="hg-cmd">hg outgoing</command>, and <command
	role="hg-cmd">hg tip</command>.</para>

    <para>As I write this manual, these are so far the only commands
      that support styles and templates.  Since these are the most
      important commands that need customisable output, there has been
      little pressure from the Mercurial user community to add style
      and template support to other commands.</para>

  </sect1>
  <sect1>
    <title>The basics of templating</title>

    <para>At its simplest, a Mercurial template is a piece of text.
      Some of the text never changes, while other parts are
      <emphasis>expanded</emphasis>, or replaced with new text, when
      necessary.</para>

    <para>Before we continue, let's look again at a simple example of
      Mercurial's normal output.</para>

    &interaction.template.simple.normal;

    <para>Now, let's run the same command, but using a template to
      change its output.</para>

    &interaction.template.simple.simplest;

    <para>The example above illustrates the simplest possible
      template; it's just a piece of static text, printed once for
      each changeset.  The <option
	role="hg-opt-log">--template</option> option to the <command
	role="hg-cmd">hg log</command> command tells Mercurial to use
      the given text as the template when printing each
      changeset.</para>

    <para>Notice that the template string above ends with the text
      <quote><literal>\n</literal></quote>.  This is an
      <emphasis>escape sequence</emphasis>, telling Mercurial to print
      a newline at the end of each template item.  If you omit this
      newline, Mercurial will run each piece of output together.  See
      section <xref linkend="sec:template:escape"/> for more details
      of escape sequences.</para>

    <para>A template that prints a fixed string of text all the time
      isn't very useful; let's try something a bit more
      complex.</para>

    &interaction.template.simple.simplesub;

    <para>As you can see, the string
      <quote><literal>{desc}</literal></quote> in the template has
      been replaced in the output with the description of each
      changeset.  Every time Mercurial finds text enclosed in curly
      braces (<quote><literal>{</literal></quote> and
      <quote><literal>}</literal></quote>), it will try to replace the braces
      and text with the expansion of whatever is inside.  To print a
      literal curly brace, you must escape it, as described in section
      <xref
	linkend="sec:template:escape"/>.</para>

  </sect1>
  <sect1 id="sec:template:keyword">
    <title>Common template keywords</title>

    <para>You can start writing simple templates immediately using the
      keywords below.</para>

    <itemizedlist>
      <listitem><para><literal
	    role="template-keyword">author</literal>: String.  The
	  unmodified author of the changeset.</para>
      </listitem>
      <listitem><para><literal
	    role="template-keyword">branches</literal>: String.  The
	  name of the branch on which the changeset was committed.
	  Will be empty if the branch name was
	  <literal>default</literal>.</para>
      </listitem>
      <listitem><para><literal role="template-keyword">date</literal>:
	  Date information.  The date when the changeset was
	  committed.  This is <emphasis>not</emphasis> human-readable;
	  you must pass it through a filter that will render it
	  appropriately.  See section <xref
	    linkend="sec:template:filter"/> for more information
	  on filters. The date is expressed as a pair of numbers.  The
	  first number is a Unix UTC timestamp (seconds since January
	  1, 1970); the second is the offset of the committer's
	  timezone from UTC, in seconds.</para>
      </listitem>
      <listitem><para><literal role="template-keyword">desc</literal>:
	  String.  The text of the changeset description.</para>
      </listitem>
      <listitem><para><literal
	    role="template-keyword">files</literal>: List of strings.
	  All files modified, added, or removed by this
	  changeset.</para>
      </listitem>
      <listitem><para><literal
	    role="template-keyword">file_adds</literal>: List of
	  strings.  Files added by this changeset.</para>
      </listitem>
      <listitem><para><literal
	    role="template-keyword">file_dels</literal>: List of
	  strings.  Files removed by this changeset.</para>
      </listitem>
      <listitem><para><literal role="template-keyword">node</literal>:
	  String.  The changeset identification hash, as a
	  40-character hexadecimal string.</para>
      </listitem>
      <listitem><para><literal
	    role="template-keyword">parents</literal>: List of
	  strings.  The parents of the changeset.</para>
      </listitem>
      <listitem><para><literal role="template-keyword">rev</literal>:
	  Integer.  The repository-local changeset revision
	  number.</para>
      </listitem>
      <listitem><para><literal role="template-keyword">tags</literal>:
	  List of strings.  Any tags associated with the
	  changeset.</para>
      </listitem></itemizedlist>

    <para>A few simple experiments will show us what to expect when we
      use these keywords; you can see the results below.</para>

&interaction.template.simple.keywords;

    <para>As we noted above, the date keyword does not produce
      human-readable output, so we must treat it specially.  This
      involves using a <emphasis>filter</emphasis>, about which more
      in section <xref
	linkend="sec:template:filter"/>.</para>

    &interaction.template.simple.datekeyword;

  </sect1>
  <sect1 id="sec:template:escape">
    <title>Escape sequences</title>

    <para>Mercurial's templating engine recognises the most commonly
      used escape sequences in strings.  When it sees a backslash
      (<quote><literal>\</literal></quote>) character, it looks at the
      following character and substitutes the two characters with a
      single replacement, as described below.</para>

    <itemizedlist>
      <listitem><para><literal>\textbackslash\textbackslash</literal>:
	  Backslash, <quote><literal>\</literal></quote>, ASCII
	  134.</para>
      </listitem>
      <listitem><para><literal>\textbackslash n</literal>: Newline,
	  ASCII 12.</para>
      </listitem>
      <listitem><para><literal>\textbackslash r</literal>: Carriage
	  return, ASCII 15.</para>
      </listitem>
      <listitem><para><literal>\textbackslash t</literal>: Tab, ASCII
	  11.</para>
      </listitem>
      <listitem><para><literal>\textbackslash v</literal>: Vertical
	  tab, ASCII 13.</para>
      </listitem>
      <listitem><para><literal>\textbackslash {</literal>: Open curly
	  brace, <quote><literal>{</literal></quote>, ASCII
	  173.</para>
      </listitem>
      <listitem><para><literal>\textbackslash }</literal>: Close curly
	  brace, <quote><literal>}</literal></quote>, ASCII
	  175.</para>
      </listitem></itemizedlist>

    <para>As indicated above, if you want the expansion of a template
      to contain a literal <quote><literal>\</literal></quote>,
      <quote><literal>{</literal></quote>, or
      <quote><literal>{</literal></quote> character, you must escape
      it.</para>

  </sect1>
  <sect1 id="sec:template:filter">
    <title>Filtering keywords to change their results</title>

    <para>Some of the results of template expansion are not
      immediately easy to use.  Mercurial lets you specify an optional
      chain of <emphasis>filters</emphasis> to modify the result of
      expanding a keyword.  You have already seen a common filter,
      <literal role="template-kw-filt-date">isodate</literal>, in
      action above, to make a date readable.</para>

    <para>Below is a list of the most commonly used filters that
      Mercurial supports.  While some filters can be applied to any
      text, others can only be used in specific circumstances.  The
      name of each filter is followed first by an indication of where
      it can be used, then a description of its effect.</para>

    <itemizedlist>
      <listitem><para><literal
	    role="template-filter">addbreaks</literal>: Any text. Add
	  an XHTML <quote><literal>&lt;br/&gt;</literal></quote> tag
	  before the end of every line except the last.  For example,
	  <quote><literal>foo\nbar</literal></quote> becomes
	  <quote><literal>foo&lt;br/&gt;\nbar</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">age</literal>: <literal
	    role="template-keyword">date</literal> keyword.  Render
	  the age of the date, relative to the current time.  Yields a
	  string like <quote><literal>10
	      minutes</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">basename</literal>: Any text, but
	  most useful for the <literal
	    role="template-keyword">files</literal> keyword and its
	  relatives.  Treat the text as a path, and return the
	  basename. For example,
	  <quote><literal>foo/bar/baz</literal></quote> becomes
	  <quote><literal>baz</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">date</literal>: <literal
	    role="template-keyword">date</literal> keyword.  Render a
	  date in a similar format to the Unix <literal
	    role="template-keyword">date</literal> command, but with
	  timezone included.  Yields a string like <quote><literal>Mon
	      Sep 04 15:13:13 2006 -0700</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-author">domain</literal>: Any text,
	  but most useful for the <literal
	    role="template-keyword">author</literal> keyword.  Finds
	  the first string that looks like an email address, and
	  extract just the domain component.  For example,
	  <quote><literal>Bryan O'Sullivan
	      &lt;[e-mail]&gt;</literal></quote> becomes
	  <quote><literal>serpentine.com</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-author">email</literal>: Any text,
	  but most useful for the <literal
	    role="template-keyword">author</literal> keyword.  Extract
	  the first string that looks like an email address.  For
	  example, <quote><literal>Bryan O'Sullivan
	      &lt;[e-mail]&gt;</literal></quote> becomes
	  <quote><literal>[e-mail]</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">escape</literal>: Any text.
	  Replace the special XML/XHTML characters
	  <quote><literal>&amp;</literal></quote>,
	  <quote><literal>&lt;</literal></quote> and
	  <quote><literal>&gt;</literal></quote> with XML
	  entities.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">fill68</literal>: Any text.  Wrap
	  the text to fit in 68 columns.  This is useful before you
	  pass text through the <literal
	    role="template-filter">tabindent</literal> filter, and
	  still want it to fit in an 80-column fixed-font
	  window.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">fill76</literal>: Any text.  Wrap
	  the text to fit in 76 columns.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">firstline</literal>: Any text.
	  Yield the first line of text, without any trailing
	  newlines.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">hgdate</literal>: <literal
	    role="template-keyword">date</literal> keyword.  Render
	  the date as a pair of readable numbers.  Yields a string
	  like <quote><literal>1157407993
	      25200</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">isodate</literal>: <literal
	    role="template-keyword">date</literal> keyword.  Render
	  the date as a text string in ISO 8601 format.  Yields a
	  string like <quote><literal>2006-09-04 15:13:13
	      -0700</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">obfuscate</literal>: Any text, but
	  most useful for the <literal
	    role="template-keyword">author</literal> keyword.  Yield
	  the input text rendered as a sequence of XML entities.  This
	  helps to defeat some particularly stupid screen-scraping
	  email harvesting spambots.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-author">person</literal>: Any text,
	  but most useful for the <literal
	    role="template-keyword">author</literal> keyword.  Yield
	  the text before an email address. For example,
	  <quote><literal>Bryan O'Sullivan
	      &lt;[e-mail]&gt;</literal></quote> becomes
	  <quote><literal>Bryan O'Sullivan</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">rfc822date</literal>:
	  <literal role="template-keyword">date</literal> keyword.
	  Render a date using the same format used in email headers.
	  Yields a string like <quote><literal>Mon, 04 Sep 2006
	      15:13:13 -0700</literal></quote>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-node">short</literal>: Changeset
	  hash.  Yield the short form of a changeset hash, i.e. a
	  12-character hexadecimal string.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-date">shortdate</literal>: <literal
	    role="template-keyword">date</literal> keyword.  Render
	  the year, month, and day of the date.  Yields a string like
	  <quote><literal>2006-09-04</literal></quote>.</para>
      </listitem>
      <listitem><para><literal role="template-filter">strip</literal>:
	  Any text.  Strip all leading and trailing whitespace from
	  the string.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">tabindent</literal>: Any text.
	  Yield the text, with every line except the first starting
	  with a tab character.</para>
      </listitem>
      <listitem><para><literal
	    role="template-filter">urlescape</literal>: Any text.
	  Escape all characters that are considered
	  <quote>special</quote> by URL parsers.  For example,
	  <literal>foo bar</literal> becomes
	  <literal>foo%20bar</literal>.</para>
      </listitem>
      <listitem><para><literal
	    role="template-kw-filt-author">user</literal>: Any text,
	  but most useful for the <literal
	    role="template-keyword">author</literal> keyword.  Return
	  the <quote>user</quote> portion of an email address.  For
	  example, <quote><literal>Bryan O'Sullivan
	      &lt;[e-mail]&gt;</literal></quote> becomes
	  <quote><literal>bos</literal></quote>.</para>
      </listitem></itemizedlist>

&interaction.template.simple.manyfilters;

    <note>
      <para>  If you try to apply a filter to a piece of data that it
	cannot process, Mercurial will fail and print a Python
	exception.  For example, trying to run the output of the
	<literal role="template-keyword">desc</literal> keyword into
	the <literal role="template-kw-filt-date">isodate</literal>
	filter is not a good idea.</para>
    </note>

    <sect2>
      <title>Combining filters</title>

      <para>It is easy to combine filters to yield output in the form
	you would like.  The following chain of filters tidies up a
	description, then makes sure that it fits cleanly into 68
	columns, then indents it by a further 8 characters (at least
	on Unix-like systems, where a tab is conventionally 8
	characters wide).</para>

      &interaction.template.simple.combine;

      <para>Note the use of <quote><literal>\t</literal></quote> (a
	tab character) in the template to force the first line to be
	indented; this is necessary since <literal
	  role="template-keyword">tabindent</literal> indents all
	lines <emphasis>except</emphasis> the first.</para>

      <para>Keep in mind that the order of filters in a chain is
	significant.  The first filter is applied to the result of the
	keyword; the second to the result of the first filter; and so
	on.  For example, using <literal>fill68|tabindent</literal>
	gives very different results from
	<literal>tabindent|fill68</literal>.</para>


    </sect2>
  </sect1>
  <sect1>
    <title>From templates to styles</title>

    <para>A command line template provides a quick and simple way to
      format some output.  Templates can become verbose, though, and
      it's useful to be able to give a template a name.  A style file
      is a template with a name, stored in a file.</para>

    <para>More than that, using a style file unlocks the power of
      Mercurial's templating engine in ways that are not possible
      using the command line <option
	role="hg-opt-log">--template</option> option.</para>

    <sect2>
      <title>The simplest of style files</title>

      <para>Our simple style file contains just one line:</para>

      &interaction.template.simple.rev;

      <para>This tells Mercurial, <quote>if you're printing a
	  changeset, use the text on the right as the
	  template</quote>.</para>

    </sect2>
    <sect2>
      <title>Style file syntax</title>

      <para>The syntax rules for a style file are simple.</para>

      <itemizedlist>
	<listitem><para>The file is processed one line at a
	    time.</para>
	</listitem>
	<listitem><para>Leading and trailing white space are
	    ignored.</para>
	</listitem>
	<listitem><para>Empty lines are skipped.</para>
	</listitem>
	<listitem><para>If a line starts with either of the characters
	    <quote><literal>#</literal></quote> or
	    <quote><literal>;</literal></quote>, the entire line is
	    treated as a comment, and skipped as if empty.</para>
	</listitem>
	<listitem><para>A line starts with a keyword.  This must start
	    with an alphabetic character or underscore, and can
	    subsequently contain any alphanumeric character or
	    underscore.  (In regexp notation, a keyword must match
	    <literal>[A-Za-z_][A-Za-z0-9_]*</literal>.)</para>
	</listitem>
	<listitem><para>The next element must be an
	    <quote><literal>=</literal></quote> character, which can
	    be preceded or followed by an arbitrary amount of white
	    space.</para>
	</listitem>
	<listitem><para>If the rest of the line starts and ends with
	    matching quote characters (either single or double quote),
	    it is treated as a template body.</para>
	</listitem>
	<listitem><para>If the rest of the line <emphasis>does
	      not</emphasis> start with a quote character, it is
	    treated as the name of a file; the contents of this file
	    will be read and used as a template body.</para>
	</listitem></itemizedlist>

    </sect2>
  </sect1>
  <sect1>
    <title>Style files by example</title>

    <para>To illustrate how to write a style file, we will construct a
      few by example.  Rather than provide a complete style file and
      walk through it, we'll mirror the usual process of developing a
      style file by starting with something very simple, and walking
      through a series of successively more complete examples.</para>

    <sect2>
      <title>Identifying mistakes in style files</title>

      <para>If Mercurial encounters a problem in a style file you are
	working on, it prints a terse error message that, once you
	figure out what it means, is actually quite useful.</para>

&interaction.template.svnstyle.syntax.input;

      <para>Notice that <filename>broken.style</filename> attempts to
	define a <literal>changeset</literal> keyword, but forgets to
	give any content for it. When instructed to use this style
	file, Mercurial promptly complains.</para>

      &interaction.template.svnstyle.syntax.error;

      <para>This error message looks intimidating, but it is not too
	hard to follow.</para>

      <itemizedlist>
	<listitem><para>The first component is simply Mercurial's way
	    of saying <quote>I am giving up</quote>.</para>
	  <programlisting>___abort___: broken.style:1: parse
	    error</programlisting>
	</listitem>
	<listitem><para>Next comes the name of the style file that
	    contains the error.</para>
	  <programlisting>
	    abort: ___broken.style___:1: parse error
	  </programlisting>
	</listitem>
	<listitem><para>Following the file name is the line number
	    where the error was encountered.</para>
	  <programlisting>abort: broken.style:___1___: parse
	    error</programlisting>
	</listitem>
	<listitem><para>Finally, a description of what went
	    wrong.</para>
	  <programlisting>abort: broken.style:1: ___parse
	    error___</programlisting>
	</listitem>
	<listitem><para>The description of the problem is not always
	    clear (as in this case), but even when it is cryptic, it
	    is almost always trivial to visually inspect the offending
	    line in the style file and see what is wrong.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title>Uniquely identifying a repository</title>

      <para>If you would like to be able to identify a Mercurial
	repository <quote>fairly uniquely</quote> using a short string
	as an identifier, you can use the first revision in the
	repository.</para>

      &interaction.template.svnstyle.id;

      <para>This is not guaranteed to be unique, but it is
	nevertheless useful in many cases.</para>
      <itemizedlist>
	<listitem><para>It will not work in a completely empty
	    repository, because such a repository does not have a
	    revision zero.</para>
	</listitem>
	<listitem><para>Neither will it work in the (extremely rare)
	    case where a repository is a merge of two or more formerly
	    independent repositories, and you still have those
	    repositories around.</para>
	</listitem></itemizedlist>
      <para>Here are some uses to which you could put this
	identifier:</para>
      <itemizedlist>
	<listitem><para>As a key into a table for a database that
	    manages repositories on a server.</para>
	</listitem>
	<listitem><para>As half of a {<emphasis>repository
	      ID</emphasis>, <emphasis>revision ID</emphasis>} tuple.
	    Save this information away when you run an automated build
	    or other activity, so that you can <quote>replay</quote>
	    the build later if necessary.</para>
	</listitem></itemizedlist>

    </sect2>
    <sect2>
      <title>Mimicking Subversion's output</title>

      <para>Let's try to emulate the default output format used by
	another revision control tool, Subversion.</para>

      &interaction.template.svnstyle.short;

      <para>Since Subversion's output style is fairly simple, it is
	easy to copy-and-paste a hunk of its output into a file, and
	replace the text produced above by Subversion with the
	template values we'd like to see expanded.</para>

      &interaction.template.svnstyle.template;

      <para>There are a few small ways in which this template deviates
	from the output produced by Subversion.</para>
      <itemizedlist>
	<listitem><para>Subversion prints a <quote>readable</quote>
	    date (the <quote><literal>Wed, 27 Sep 2006</literal></quote> in the
	    example output above) in parentheses.  Mercurial's
	    templating engine does not provide a way to display a date
	    in this format without also printing the time and time
	    zone.</para>
	</listitem>
	<listitem><para>We emulate Subversion's printing of
	    <quote>separator</quote> lines full of
	    <quote><literal>-</literal></quote> characters by ending
	    the template with such a line. We use the templating
	    engine's <literal role="template-keyword">header</literal>
	    keyword to print a separator line as the first line of
	    output (see below), thus achieving similar output to
	    Subversion.</para>
	</listitem>
	<listitem><para>Subversion's output includes a count in the
	    header of the number of lines in the commit message.  We
	    cannot replicate this in Mercurial; the templating engine
	    does not currently provide a filter that counts the number
	    of lines the template generates.</para>
	</listitem></itemizedlist>
      <para>It took me no more than a minute or two of work to replace
	literal text from an example of Subversion's output with some
	keywords and filters to give the template above.  The style
	file simply refers to the template.</para>

      &interaction.template.svnstyle.style;

      <para>We could have included the text of the template file
	directly in the style file by enclosing it in quotes and
	replacing the newlines with
	<quote><literal>\n</literal></quote> sequences, but it would
	have made the style file too difficult to read.  Readability
	is a good guide when you're trying to decide whether some text
	belongs in a style file, or in a template file that the style
	file points to.  If the style file will look too big or
	cluttered if you insert a literal piece of text, drop it into
	a template instead.</para>

    </sect2>
  </sect1>
</chapter>

<!--
local variables: 
sgml-parent-document: ("00book.xml" "book" "chapter")
end:
-->