comparison en/ch11-template.xml @ 724:cfdb601a3c8b

Fix imagedata fileref in xml files, and replace ':' with '.' in id attribute

723:3c5e1c03cc3e

<!-- 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

    <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>

      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>

      <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>

    <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

      <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

724:cfdb601a3c8b

<!-- 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

    <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>

      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>

      <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>

    <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

      <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