1.1 --- a/en/template.tex	Wed Sep 06 23:36:47 2006 -0700
     1.2 +++ b/en/template.tex	Fri Dec 29 17:54:14 2006 -0800
     1.3 @@ -11,7 +11,7 @@
     1.4  
     1.5  Packaged with Mercurial are some output styles that you can use
     1.6  immediately.  A style is simply a precanned template that someone
     1.7 -wrote.
     1.8 +wrote and installed somewhere that Mercurial can find.
     1.9  
    1.10  Before we take a look at Mercurial's bundled styles, let's review its
    1.11  normal output.
    1.12 @@ -33,7 +33,7 @@
    1.13  You will not be shocked to learn that Mercurial's default output style
    1.14  is named \texttt{default}.
    1.15  
    1.16 -\subsection{Setting an output style to use}
    1.17 +\subsection{Setting a default style}
    1.18  
    1.19  You can modify the output style that Mercurial will use for every
    1.20  command by editing your \hgrc\ file, naming the style you would
    1.21 @@ -101,7 +101,7 @@
    1.22  the expansion of whatever is inside.  To print a literal curly brace,
    1.23  you must escape it, as described in section~\ref{sec:template:escape}.
    1.24  
    1.25 -\section{Basic template keywords}
    1.26 +\section{Common template keywords}
    1.27  \label{sec:template:keyword}
    1.28  
    1.29  You can start writing simple templates immediately using the keywords
    1.30 @@ -172,15 +172,21 @@
    1.31  a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
    1.32  must escape it.
    1.33  
    1.34 -\section{Filtering expanded keywords}
    1.35 +\section{Filtering keywords to change their results}
    1.36  \label{sec:template:filter}
    1.37  
    1.38 -Some of the results of template expansion are not entirely easy to
    1.39 +Some of the results of template expansion are not immediately easy to
    1.40  use.  Mercurial lets you specify an optional chain of \emph{filters}
    1.41  to modify the result of expanding a keyword.  You have already seen a
    1.42  common filter, \tplkwfilt{date}{isodate}, in action above, to make a
    1.43  date readable.
    1.44  
    1.45 +Below is a list of the most commonly used filters that Mercurial
    1.46 +supports.  While some filters can be applied to any text, others can
    1.47 +only be used in specific circumstances.  The name of each filter is
    1.48 +followed first by an indication of where it can be used, then a
    1.49 +description of its effect.
    1.50 +
    1.51  \begin{itemize}
    1.52  \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
    1.53    tag before the end of every line except the last.  For example,
    1.54 @@ -280,10 +286,186 @@
    1.55  force the first line to be indented; this is necessary since
    1.56  \tplkword{tabindent} indents all lines \emph{except} the first.
    1.57  
    1.58 -Keep in mind that the order of filters in a chain is significant.
    1.59 -Using \Verb+fill68|tabindent+ gives very different results from
    1.60 +Keep in mind that the order of filters in a chain is significant.  The
    1.61 +first filter is applied to the result of the keyword; the second to
    1.62 +the result of the first filter; and so on.  For example, using
    1.63 +\Verb+fill68|tabindent+ gives very different results from
    1.64  \Verb+tabindent|fill68+.
    1.65  
    1.66 +
    1.67 +\section{From templates to styles}
    1.68 +
    1.69 +A command line template provides a quick and simple way to format some
    1.70 +output.  Templates can become verbose, though, and it's useful to be
    1.71 +able to give a template a name.  A style file is a template with a
    1.72 +name, stored in a file.
    1.73 +
    1.74 +More than that, using a style file unlocks the power of Mercurial's
    1.75 +templating engine in ways that are not possible using the command line
    1.76 +\hgopt{log}{--template} option.
    1.77 +
    1.78 +\subsection{The simplest of style files}
    1.79 +
    1.80 +Our simple style file contains just one line:
    1.81 +
    1.82 +\interaction{template.simple.rev}
    1.83 +
    1.84 +This tells Mercurial, ``if you're printing a changeset, use the text
    1.85 +on the right as the template''.
    1.86 +
    1.87 +\subsection{Style file syntax}
    1.88 +
    1.89 +The syntax rules for a style file are simple.
    1.90 +
    1.91 +\begin{itemize}
    1.92 +\item The file is processed one line at a time.
    1.93 +
    1.94 +\item Leading and trailing white space are ignored.
    1.95 +
    1.96 +\item Empty lines are skipped.
    1.97 +
    1.98 +\item If a line starts with either of the characters ``\texttt{\#}'' or
    1.99 +  ``\texttt{;}'', the entire line is treated as a comment, and skipped
   1.100 +  as if empty.
   1.101 +
   1.102 +\item A line starts with a keyword.  This must start with an
   1.103 +  alphabetic character or underscore, and can subsequently contain any
   1.104 +  alphanumeric character or underscore.  (In regexp notation, a
   1.105 +  keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
   1.106 +
   1.107 +\item The next element must be an ``\texttt{=}'' character, which can
   1.108 +  be preceded or followed by an arbitrary amount of white space.
   1.109 +
   1.110 +\item If the rest of the line starts and ends with matching quote
   1.111 +  characters (either single or double quote), it is treated as a
   1.112 +  template body.
   1.113 +
   1.114 +\item If the rest of the line \emph{does not} start with a quote
   1.115 +  character, it is treated as the name of a file; the contents of this
   1.116 +  file will be read and used as a template body.
   1.117 +\end{itemize}
   1.118 +
   1.119 +\section{Style files by example}
   1.120 +
   1.121 +To illustrate how to write a style file, we will construct a few by
   1.122 +example.  Rather than provide a complete style file and walk through
   1.123 +it, we'll mirror the usual process of developing a style file by
   1.124 +starting with something very simple, and walking through a series of
   1.125 +successively more complete examples.
   1.126 +
   1.127 +\subsection{Identifying mistakes in style files}
   1.128 +
   1.129 +If Mercurial encounters a problem in a style file you are working on,
   1.130 +it prints a terse error message that, once you figure out what it
   1.131 +means, is actually quite useful.
   1.132 +
   1.133 +\interaction{template.svnstyle.syntax.input}
   1.134 +
   1.135 +Notice that \filename{broken.style} attempts to define a
   1.136 +\texttt{changeset} keyword, but forgets to give any content for it.
   1.137 +When instructed to use this style file, Mercurial promptly complains.
   1.138 +
   1.139 +\interaction{template.svnstyle.syntax.error}
   1.140 +
   1.141 +This error message looks intimidating, but it is not too hard to
   1.142 +follow.
   1.143 +
   1.144 +\begin{itemize}
   1.145 +\item The first component is simply Mercurial's way of saying ``I am
   1.146 +  giving up''.
   1.147 +  \begin{codesample4}
   1.148 +    \textbf{abort:} broken.style:1: parse error
   1.149 +  \end{codesample4}
   1.150 +
   1.151 +\item Next comes the name of the style file that contains the error.
   1.152 +  \begin{codesample4}
   1.153 +    abort: \textbf{broken.style}:1: parse error
   1.154 +  \end{codesample4}
   1.155 +
   1.156 +\item Following the file name is the line number where the error was
   1.157 +  encountered.
   1.158 +  \begin{codesample4}
   1.159 +    abort: broken.style:\textbf{1}: parse error
   1.160 +  \end{codesample4}
   1.161 +
   1.162 +\item Finally, a description of what went wrong.
   1.163 +  \begin{codesample4}
   1.164 +    abort: broken.style:1: \textbf{parse error}
   1.165 +  \end{codesample4}
   1.166 +  The description of the problem is not always clear (as in this
   1.167 +  case), but even when it is cryptic, it is almost always trivial to
   1.168 +  visually inspect the offending line in the style file and see what
   1.169 +  is wrong.
   1.170 +\end{itemize}
   1.171 +
   1.172 +\subsection{Uniquely identifying a repository}
   1.173 +
   1.174 +If you would like to be able to identify a Mercurial repository
   1.175 +``fairly uniquely'' using a short string as an identifier, you can
   1.176 +use the first revision in the repository.
   1.177 +\interaction{template.svnstyle.id} 
   1.178 +This is not guaranteed to be unique, but it is nevertheless useful in
   1.179 +many cases.
   1.180 +\begin{itemize}
   1.181 +\item It will not work in a completely empty repository, because such
   1.182 +  a repository does not have a revision~zero.
   1.183 +\item Neither will it work in the (extremely rare) case where a
   1.184 +  repository is a merge of two or more formerly independent
   1.185 +  repositories, and you still have those repositories around.
   1.186 +\end{itemize}
   1.187 +Here are some uses to which you could put this identifier:
   1.188 +\begin{itemize}
   1.189 +\item As a key into a table for a database that manages repositories
   1.190 +  on a server.
   1.191 +\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
   1.192 +  Save this information away when you run an automated build or other
   1.193 +  activity, so that you can ``replay'' the build later if necessary.
   1.194 +\end{itemize}
   1.195 +
   1.196 +\subsection{Mimicking Subversion's output}
   1.197 +
   1.198 +Let's try to emulate the default output format used by another
   1.199 +revision control tool, Subversion.
   1.200 +\interaction{template.svnstyle.short}
   1.201 +
   1.202 +Since Subversion's output style is fairly simple, it is easy to
   1.203 +copy-and-paste a hunk of its output into a file, and replace the text
   1.204 +produced above by Subversion with the template values we'd like to see
   1.205 +expanded.
   1.206 +\interaction{template.svnstyle.template}
   1.207 +
   1.208 +There are a few small ways in which this template deviates from the
   1.209 +output produced by Subversion.
   1.210 +\begin{itemize}
   1.211 +\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
   1.212 +    2006}'' in the example output above) in parentheses.  Mercurial's
   1.213 +  templating engine does not provide a way to display a date in this
   1.214 +  format without also printing the time and time zone.
   1.215 +\item We emulate Subversion's printing of ``separator'' lines full of
   1.216 +  ``\texttt{-}'' characters by ending the template with such a line.
   1.217 +  We use the templating engine's \tplkword{header} keyword to print a
   1.218 +  separator line as the first line of output (see below), thus
   1.219 +  achieving similar output to Subversion.
   1.220 +\item Subversion's output includes a count in the header of the number
   1.221 +  of lines in the commit message.  We cannot replicate this in
   1.222 +  Mercurial; the templating engine does not currently provide a filter
   1.223 +  that counts the number of items it is passed.
   1.224 +\end{itemize}
   1.225 +It took me no more than a minute or two of work to replace literal
   1.226 +text from an example of Subversion's output with some keywords and
   1.227 +filters to give the template above.  The style file simply refers to
   1.228 +the template.
   1.229 +\interaction{template.svnstyle.style}
   1.230 +
   1.231 +We could have included the text of the template file directly in the
   1.232 +style file by enclosing it in quotes and replacing the newlines with
   1.233 +``\texttt{\\n}'' sequences, but it would have made the style file too
   1.234 +difficult to read.  Readability is a good guide when you're trying to
   1.235 +decide whether some text belongs in a style file, or in a template
   1.236 +file that the style file points to.  If the style file will look too
   1.237 +big or cluttered if you insert a literal piece of text, drop it into a
   1.238 +template instead.
   1.239 +
   1.240  %%% Local Variables: 
   1.241  %%% mode: latex
   1.242  %%% TeX-master: "00book"