1.1 --- a/en/Makefile	Mon Oct 02 15:16:47 2006 -0700
     1.2 +++ b/en/Makefile	Tue Oct 03 13:03:42 2006 -0700
     1.3 @@ -29,7 +29,8 @@
     1.4  	examples/mq.tarball \
     1.5  	examples/mq.tools \
     1.6  	examples/mq.tutorial \
     1.7 -	examples/template.simple
     1.8 +	examples/template.simple \
     1.9 +	examples/template.svnstyle
    1.10  
    1.11  latex-options = \
    1.12  	-interaction batchmode \

     2.1 --- a/en/examples/run-example	Mon Oct 02 15:16:47 2006 -0700
     2.2 +++ b/en/examples/run-example	Tue Oct 03 13:03:42 2006 -0700
     2.3 @@ -129,6 +129,7 @@
     2.4          rcfile = os.path.join(tmpdir, '.bashrc')
     2.5          rcfp = open(rcfile, 'w')
     2.6          print >> rcfp, 'PS1="%s"' % self.prompt
     2.7 +        print >> rcfp, 'PS2="%s"' % self.prompt
     2.8          print >> rcfp, 'unset HISTFILE'
     2.9          print >> rcfp, 'export EXAMPLE_DIR="%s"' % os.getcwd()
    2.10          print >> rcfp, 'export LANG=C'

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/examples/svn-long.txt	Tue Oct 03 13:03:42 2006 -0700
     3.3 @@ -0,0 +1,11 @@
     3.4 +------------------------------------------------------------------------
     3.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
     3.6 +Changed paths:
     3.7 +   M /gen2/trunk/src/linux-kernel/infiniband/core/cma.c
     3.8 +
     3.9 +On reporting a route error, also include the status for the error,
    3.10 +rather than indicating a status of 0 when an error has occurred.
    3.11 +
    3.12 +Signed-off-by: Sean Hefty <sean.hefty@intel.com>
    3.13 +
    3.14 +------------------------------------------------------------------------

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/examples/svn-short.txt	Tue Oct 03 13:03:42 2006 -0700
     4.3 @@ -0,0 +1,9 @@
     4.4 +------------------------------------------------------------------------
     4.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines
     4.6 +
     4.7 +On reporting a route error, also include the status for the error,
     4.8 +rather than indicating a status of 0 when an error has occurred.
     4.9 +
    4.10 +Signed-off-by: Sean Hefty <sean.hefty@intel.com>
    4.11 +
    4.12 +------------------------------------------------------------------------

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/svn.style	Tue Oct 03 13:03:42 2006 -0700
     5.3 @@ -0,0 +1,2 @@
     5.4 +header = '------------------------------------------------------------------------\n\n'
     5.5 +changeset = svn.template

     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/en/examples/svn.template	Tue Oct 03 13:03:42 2006 -0700
     6.3 @@ -0,0 +1,5 @@
     6.4 +r{rev} | {author|user} | {date|isodate} ({date|rfc822date})
     6.5 +
     6.6 +{desc|strip|fill76}
     6.7 +
     6.8 +------------------------------------------------------------------------

     7.1 --- a/en/examples/template.simple	Mon Oct 02 15:16:47 2006 -0700
     7.2 +++ b/en/examples/template.simple	Tue Oct 03 13:03:42 2006 -0700
     7.3 @@ -85,3 +85,8 @@
     7.4  #$ name: combine
     7.5  
     7.6  hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'
     7.7 +
     7.8 +#$ name: rev
     7.9 +
    7.10 +echo 'changeset = "rev: {rev}\n"' > rev
    7.11 +hg log -l1 --style ./rev

     8.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     8.2 +++ b/en/examples/template.svnstyle	Tue Oct 03 13:03:42 2006 -0700
     8.3 @@ -0,0 +1,69 @@
     8.4 +#!/bin/bash
     8.5 +
     8.6 +svn() {
     8.7 +  cat $EXAMPLE_DIR/svn-short.txt
     8.8 +}
     8.9 +
    8.10 +#$ name: short
    8.11 +
    8.12 +svn log -r9653
    8.13 +
    8.14 +#$ name:
    8.15 +
    8.16 +hg init myrepo
    8.17 +cd myrepo
    8.18 +
    8.19 +echo hello > hello
    8.20 +hg commit -Am'added hello'
    8.21 +
    8.22 +echo hello >> hello
    8.23 +echo goodbye > goodbye
    8.24 +echo '   added line to end of <<hello>> file.' > ../msg
    8.25 +echo '' >> ../msg
    8.26 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg
    8.27 +
    8.28 +hg commit -Al../msg
    8.29 +
    8.30 +hg tag mytag
    8.31 +hg tag v0.1
    8.32 +
    8.33 +echo 'changeset = "{node|short}\n"' > svn.style
    8.34 +
    8.35 +#$ name: id
    8.36 +
    8.37 +hg log -r0 --template '{node}'
    8.38 +
    8.39 +#$ name: simplest
    8.40 +
    8.41 +cat svn.style
    8.42 +hg log -r1 --style svn.style
    8.43 +
    8.44 +#$ name:
    8.45 +
    8.46 +echo 'changeset =' > broken.style
    8.47 +
    8.48 +#$ name: syntax.input
    8.49 +
    8.50 +cat broken.style
    8.51 +
    8.52 +#$ name: syntax.error
    8.53 +
    8.54 +hg log -r1 --style broken.style
    8.55 +
    8.56 +#$ name:
    8.57 +
    8.58 +cp $EXAMPLE_DIR/svn.style .
    8.59 +cp $EXAMPLE_DIR/svn.template .
    8.60 +
    8.61 +#$ name: template
    8.62 +
    8.63 +cat svn.template
    8.64 +
    8.65 +#$ name: style
    8.66 +
    8.67 +cat svn.style
    8.68 +
    8.69 +#$ name: result
    8.70 +
    8.71 +hg log -r1 --style svn.style
    8.72 +

     9.1 --- a/en/template.tex	Mon Oct 02 15:16:47 2006 -0700
     9.2 +++ b/en/template.tex	Tue Oct 03 13:03:42 2006 -0700
     9.3 @@ -11,7 +11,7 @@
     9.4  
     9.5  Packaged with Mercurial are some output styles that you can use
     9.6  immediately.  A style is simply a precanned template that someone
     9.7 -wrote.
     9.8 +wrote and installed somewhere that Mercurial can find.
     9.9  
    9.10  Before we take a look at Mercurial's bundled styles, let's review its
    9.11  normal output.
    9.12 @@ -33,7 +33,7 @@
    9.13  You will not be shocked to learn that Mercurial's default output style
    9.14  is named \texttt{default}.
    9.15  
    9.16 -\subsection{Setting an output style to use}
    9.17 +\subsection{Setting a default style}
    9.18  
    9.19  You can modify the output style that Mercurial will use for every
    9.20  command by editing your \hgrc\ file, naming the style you would
    9.21 @@ -101,7 +101,7 @@
    9.22  the expansion of whatever is inside.  To print a literal curly brace,
    9.23  you must escape it, as described in section~\ref{sec:template:escape}.
    9.24  
    9.25 -\section{Basic template keywords}
    9.26 +\section{Common template keywords}
    9.27  \label{sec:template:keyword}
    9.28  
    9.29  You can start writing simple templates immediately using the keywords
    9.30 @@ -172,15 +172,21 @@
    9.31  a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
    9.32  must escape it.
    9.33  
    9.34 -\section{Filtering expanded keywords}
    9.35 +\section{Filtering keywords to change their results}
    9.36  \label{sec:template:filter}
    9.37  
    9.38 -Some of the results of template expansion are not entirely easy to
    9.39 +Some of the results of template expansion are not immediately easy to
    9.40  use.  Mercurial lets you specify an optional chain of \emph{filters}
    9.41  to modify the result of expanding a keyword.  You have already seen a
    9.42  common filter, \tplkwfilt{date}{isodate}, in action above, to make a
    9.43  date readable.
    9.44  
    9.45 +Below is a list of the most commonly used filters that Mercurial
    9.46 +supports.  While some filters can be applied to any text, others can
    9.47 +only be used in specific circumstances.  The name of each filter is
    9.48 +followed first by an indication of where it can be used, then a
    9.49 +description of its effect.
    9.50 +
    9.51  \begin{itemize}
    9.52  \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
    9.53    tag before the end of every line except the last.  For example,
    9.54 @@ -280,10 +286,186 @@
    9.55  force the first line to be indented; this is necessary since
    9.56  \tplkword{tabindent} indents all lines \emph{except} the first.
    9.57  
    9.58 -Keep in mind that the order of filters in a chain is significant.
    9.59 -Using \Verb+fill68|tabindent+ gives very different results from
    9.60 +Keep in mind that the order of filters in a chain is significant.  The
    9.61 +first filter is applied to the result of the keyword; the second to
    9.62 +the result of the first filter; and so on.  For example, using
    9.63 +\Verb+fill68|tabindent+ gives very different results from
    9.64  \Verb+tabindent|fill68+.
    9.65  
    9.66 +
    9.67 +\section{From templates to styles}
    9.68 +
    9.69 +A command line template provides a quick and simple way to format some
    9.70 +output.  Templates can become verbose, though, and it's useful to be
    9.71 +able to give a template a name.  A style file is a template with a
    9.72 +name, stored in a file.
    9.73 +
    9.74 +More than that, using a style file unlocks the power of Mercurial's
    9.75 +templating engine in ways that are not possible using the command line
    9.76 +\hgopt{log}{--template} option.
    9.77 +
    9.78 +\subsection{The simplest of style files}
    9.79 +
    9.80 +Our simple style file contains just one line:
    9.81 +
    9.82 +\interaction{template.simple.rev}
    9.83 +
    9.84 +This tells Mercurial, ``if you're printing a changeset, use the text
    9.85 +on the right as the template''.
    9.86 +
    9.87 +\subsection{Style file syntax}
    9.88 +
    9.89 +The syntax rules for a style file are simple.
    9.90 +
    9.91 +\begin{itemize}
    9.92 +\item The file is processed one line at a time.
    9.93 +
    9.94 +\item Leading and trailing white space are ignored.
    9.95 +
    9.96 +\item Empty lines are skipped.
    9.97 +
    9.98 +\item If a line starts with either of the characters ``\texttt{\#}'' or
    9.99 +  ``\texttt{;}'', the entire line is treated as a comment, and skipped
   9.100 +  as if empty.
   9.101 +
   9.102 +\item A line starts with a keyword.  This must start with an
   9.103 +  alphabetic character or underscore, and can subsequently contain any
   9.104 +  alphanumeric character or underscore.  (In regexp notation, a
   9.105 +  keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
   9.106 +
   9.107 +\item The next element must be an ``\texttt{=}'' character, which can
   9.108 +  be preceded or followed by an arbitrary amount of white space.
   9.109 +
   9.110 +\item If the rest of the line starts and ends with matching quote
   9.111 +  characters (either single or double quote), it is treated as a
   9.112 +  template body.
   9.113 +
   9.114 +\item If the rest of the line \emph{does not} start with a quote
   9.115 +  character, it is treated as the name of a file; the contents of this
   9.116 +  file will be read and used as a template body.
   9.117 +\end{itemize}
   9.118 +
   9.119 +\section{Style files by example}
   9.120 +
   9.121 +To illustrate how to write a style file, we will construct a few by
   9.122 +example.  Rather than provide a complete style file and walk through
   9.123 +it, we'll mirror the usual process of developing a style file by
   9.124 +starting with something very simple, and walking through a series of
   9.125 +successively more complete examples.
   9.126 +
   9.127 +\subsection{Identifying mistakes in style files}
   9.128 +
   9.129 +If Mercurial encounters a problem in a style file you are working on,
   9.130 +it prints a terse error message that, once you figure out what it
   9.131 +means, is actually quite useful.
   9.132 +
   9.133 +\interaction{template.svnstyle.syntax.input}
   9.134 +
   9.135 +Notice that \filename{broken.style} attempts to define a
   9.136 +\texttt{changeset} keyword, but forgets to give any content for it.
   9.137 +When instructed to use this style file, Mercurial promptly complains.
   9.138 +
   9.139 +\interaction{template.svnstyle.syntax.error}
   9.140 +
   9.141 +This error message looks intimidating, but it is not too hard to
   9.142 +follow.
   9.143 +
   9.144 +\begin{itemize}
   9.145 +\item The first component is simply Mercurial's way of saying ``I am
   9.146 +  giving up''.
   9.147 +  \begin{codesample4}
   9.148 +    \textbf{abort:} broken.style:1: parse error
   9.149 +  \end{codesample4}
   9.150 +
   9.151 +\item Next comes the name of the style file that contains the error.
   9.152 +  \begin{codesample4}
   9.153 +    abort: \textbf{broken.style}:1: parse error
   9.154 +  \end{codesample4}
   9.155 +
   9.156 +\item Following the file name is the line number where the error was
   9.157 +  encountered.
   9.158 +  \begin{codesample4}
   9.159 +    abort: broken.style:\textbf{1}: parse error
   9.160 +  \end{codesample4}
   9.161 +
   9.162 +\item Finally, a description of what went wrong.
   9.163 +  \begin{codesample4}
   9.164 +    abort: broken.style:1: \textbf{parse error}
   9.165 +  \end{codesample4}
   9.166 +  The description of the problem is not always clear (as in this
   9.167 +  case), but even when it is cryptic, it is almost always trivial to
   9.168 +  visually inspect the offending line in the style file and see what
   9.169 +  is wrong.
   9.170 +\end{itemize}
   9.171 +
   9.172 +\subsection{Uniquely identifying a repository}
   9.173 +
   9.174 +If you would like to be able to identify a Mercurial repository
   9.175 +``fairly uniquely'' using a short string as an identifier, you can
   9.176 +use the first revision in the repository.
   9.177 +\interaction{template.svnstyle.id} 
   9.178 +This is not guaranteed to be unique, but it is nevertheless useful in
   9.179 +many cases.
   9.180 +\begin{itemize}
   9.181 +\item It will not work in a completely empty repository, because such
   9.182 +  a repository does not have a revision~zero.
   9.183 +\item Neither will it work in the (extremely rare) case where a
   9.184 +  repository is a merge of two or more formerly independent
   9.185 +  repositories, and you still have those repositories around.
   9.186 +\end{itemize}
   9.187 +Here are some uses to which you could put this identifier:
   9.188 +\begin{itemize}
   9.189 +\item As a key into a table for a database that manages repositories
   9.190 +  on a server.
   9.191 +\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
   9.192 +  Save this information away when you run an automated build or other
   9.193 +  activity, so that you can ``replay'' the build later if necessary.
   9.194 +\end{itemize}
   9.195 +
   9.196 +\subsection{Mimicking Subversion's output}
   9.197 +
   9.198 +Let's try to emulate the default output format used by another
   9.199 +revision control tool, Subversion.
   9.200 +\interaction{template.svnstyle.short}
   9.201 +
   9.202 +Since Subversion's output style is fairly simple, it is easy to
   9.203 +copy-and-paste a hunk of its output into a file, and replace the text
   9.204 +produced above by Subversion with the template values we'd like to see
   9.205 +expanded.
   9.206 +\interaction{template.svnstyle.template}
   9.207 +
   9.208 +There are a few small ways in which this template deviates from the
   9.209 +output produced by Subversion.
   9.210 +\begin{itemize}
   9.211 +\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
   9.212 +    2006}'' in the example output above) in parentheses.  Mercurial's
   9.213 +  templating engine does not provide a way to display a date in this
   9.214 +  format without also printing the time and time zone.
   9.215 +\item We emulate Subversion's printing of ``separator'' lines full of
   9.216 +  ``\texttt{-}'' characters by ending the template with such a line.
   9.217 +  We use the templating engine's \tplkword{header} keyword to print a
   9.218 +  separator line as the first line of output (see below), thus
   9.219 +  achieving similar output to Subversion.
   9.220 +\item Subversion's output includes a count in the header of the number
   9.221 +  of lines in the commit message.  We cannot replicate this in
   9.222 +  Mercurial; the templating engine does not currently provide a filter
   9.223 +  that counts the number of items it is passed.
   9.224 +\end{itemize}
   9.225 +It took me no more than a minute or two of work to replace literal
   9.226 +text from an example of Subversion's output with some keywords and
   9.227 +filters to give the template above.  The style file simply refers to
   9.228 +the template.
   9.229 +\interaction{template.svnstyle.style}
   9.230 +
   9.231 +We could have included the text of the template file directly in the
   9.232 +style file by enclosing it in quotes and replacing the newlines with
   9.233 +``\texttt{\\n}'' sequences, but it would have made the style file too
   9.234 +difficult to read.  Readability is a good guide when you're trying to
   9.235 +decide whether some text belongs in a style file, or in a template
   9.236 +file that the style file points to.  If the style file will look too
   9.237 +big or cluttered if you insert a literal piece of text, drop it into a
   9.238 +template instead.
   9.239 +
   9.240  %%% Local Variables: 
   9.241  %%% mode: latex
   9.242  %%% TeX-master: "00book"