1.1 --- a/.hgignore	Mon Sep 04 14:31:17 2006 -0700
     1.2 +++ b/.hgignore	Wed Sep 06 23:36:47 2006 -0700
     1.3 @@ -5,6 +5,7 @@
     1.4  
     1.5  beta/*.tex
     1.6  build_id.tex
     1.7 +*.4[ct][ct]
     1.8  *.aux
     1.9  *.bbl
    1.10  *.bib

     2.1 --- a/en/99book.bib	Mon Sep 04 14:31:17 2006 -0700
     2.2 +++ b/en/99book.bib	Wed Sep 06 23:36:47 2006 -0700
     2.3 @@ -49,3 +49,9 @@
     2.4    title =	 {MySQL for Python},
     2.5    note =	 {\url{http://sourceforge.net/projects/mysql-python}},
     2.6  }
     2.7 +
     2.8 +@Misc{web:changelog,
     2.9 +  autor =	 {Richard Stallman, GNU Project volunteers},
    2.10 +  title =	 {GNU Coding Standards---Change Logs},
    2.11 +  note =	 {\url{http://www.gnu.org/prep/standards/html_node/Change-Logs.html}},
    2.12 +}

     3.1 --- a/en/99defs.tex	Mon Sep 04 14:31:17 2006 -0700
     3.2 +++ b/en/99defs.tex	Wed Sep 06 23:36:47 2006 -0700
     3.3 @@ -29,6 +29,16 @@
     3.4  % Mercurial command, with arguments.
     3.5  \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''}
     3.6  
     3.7 +\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}}
     3.8 +
     3.9 +\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2}
    3.10 +    filter}\index{template filters!\texttt{#2}}\index{\texttt{#2}
    3.11 +    template filter}\texttt{#2}}
    3.12 +
    3.13 +\newcommand{\tplfilter}[1]{\index{template
    3.14 +    filters!\texttt{#1}}\index{\texttt{#1} template
    3.15 +    filter}\texttt{#1}}
    3.16 +
    3.17  % Shell/system command.
    3.18  \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}}
    3.19  

     4.1 --- a/en/Makefile	Mon Sep 04 14:31:17 2006 -0700
     4.2 +++ b/en/Makefile	Wed Sep 06 23:36:47 2006 -0700
     4.3 @@ -28,7 +28,8 @@
     4.4  	examples/mq.id \
     4.5  	examples/mq.tarball \
     4.6  	examples/mq.tools \
     4.7 -	examples/mq.tutorial
     4.8 +	examples/mq.tutorial \
     4.9 +	examples/template.simple
    4.10  
    4.11  latex-options = \
    4.12  	-interaction batchmode \

     5.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.2 +++ b/en/examples/template.simple	Wed Sep 06 23:36:47 2006 -0700
     5.3 @@ -0,0 +1,87 @@
     5.4 +#!/bin/bash
     5.5 +
     5.6 +hg init myrepo
     5.7 +cd myrepo
     5.8 +echo hello > hello
     5.9 +hg commit -Am'added hello'
    5.10 +
    5.11 +echo hello >> hello
    5.12 +echo goodbye > goodbye
    5.13 +echo '   added line to end of <<hello>> file.' > ../msg
    5.14 +echo '' >> ../msg
    5.15 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg
    5.16 +
    5.17 +hg commit -Al../msg
    5.18 +
    5.19 +hg tag mytag
    5.20 +hg tag v0.1
    5.21 +
    5.22 +#$ name: normal
    5.23 +
    5.24 +hg log -r1
    5.25 +
    5.26 +#$ name: compact
    5.27 +
    5.28 +hg log --style compact
    5.29 +
    5.30 +#$ name: changelog
    5.31 +
    5.32 +hg log --style changelog
    5.33 +
    5.34 +#$ name: simplest
    5.35 +
    5.36 +hg log -r1 --template 'i saw a changeset\n'
    5.37 +
    5.38 +#$ name: simplesub
    5.39 +
    5.40 +hg log --template 'i saw a changeset: {desc}\n'
    5.41 +
    5.42 +#$ name: keywords
    5.43 +
    5.44 +hg log -r1 --template 'author: {author}\n'
    5.45 +hg log -r1 --template 'desc:\n{desc}\n'
    5.46 +hg log -r1 --template 'files: {files}\n'
    5.47 +hg log -r1 --template 'file_adds: {file_adds}\n'
    5.48 +hg log -r1 --template 'file_dels: {file_dels}\n'
    5.49 +hg log -r1 --template 'node: {node}\n'
    5.50 +hg log -r1 --template 'parents: {parents}\n'
    5.51 +hg log -r1 --template 'rev: {rev}\n'
    5.52 +hg log -r1 --template 'tags: {tags}\n'
    5.53 +
    5.54 +#$ name: datekeyword
    5.55 +
    5.56 +hg log -r1 --template 'date: {date}\n'
    5.57 +hg log -r1 --template 'date: {date|isodate}\n'
    5.58 +
    5.59 +#$ name: manyfilters
    5.60 +
    5.61 +hg log -r1 --template '{author}\n'
    5.62 +hg log -r1 --template '{author|domain}\n'
    5.63 +hg log -r1 --template '{author|email}\n'
    5.64 +hg log -r1 --template '{author|obfuscate}\n' | cut -c-76
    5.65 +hg log -r1 --template '{author|person}\n'
    5.66 +hg log -r1 --template '{author|user}\n'
    5.67 +
    5.68 +hg log -r1 --template 'looks almost right, but actually garbage: {date}\n'
    5.69 +hg log -r1 --template '{date|age}\n'
    5.70 +hg log -r1 --template '{date|date}\n'
    5.71 +hg log -r1 --template '{date|hgdate}\n'
    5.72 +hg log -r1 --template '{date|isodate}\n'
    5.73 +hg log -r1 --template '{date|rfc822date}\n'
    5.74 +hg log -r1 --template '{date|shortdate}\n'
    5.75 +
    5.76 +hg log -r1 --template '{desc}\n' | cut -c-76
    5.77 +hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76
    5.78 +hg log -r1 --template '{desc|escape}\n' | cut -c-76
    5.79 +hg log -r1 --template '{desc|fill68}\n'
    5.80 +hg log -r1 --template '{desc|fill76}\n'
    5.81 +hg log -r1 --template '{desc|firstline}\n'
    5.82 +hg log -r1 --template '{desc|strip}\n' | cut -c-76
    5.83 +hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76
    5.84 +
    5.85 +hg log -r1 --template '{node}\n'
    5.86 +hg log -r1 --template '{node|short}\n'
    5.87 +
    5.88 +#$ name: combine
    5.89 +
    5.90 +hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'

     6.1 --- a/en/template.tex	Mon Sep 04 14:31:17 2006 -0700
     6.2 +++ b/en/template.tex	Wed Sep 06 23:36:47 2006 -0700
     6.3 @@ -1,5 +1,288 @@
     6.4 -\chapter{Using templates to customise output}
     6.5 -\label{chap:templates}
     6.6 +\chapter{Customising the output of Mercurial}
     6.7 +\label{chap:template}
     6.8 +
     6.9 +Mercurial provides a powerful mechanism to let you control how it
    6.10 +displays information.  The mechanism is based on templates.  You can
    6.11 +use templates to generate specific output for a single command, or to
    6.12 +customise the entire appearance of the built-in web interface.
    6.13 +
    6.14 +\section{Using precanned output styles}
    6.15 +\label{sec:style}
    6.16 +
    6.17 +Packaged with Mercurial are some output styles that you can use
    6.18 +immediately.  A style is simply a precanned template that someone
    6.19 +wrote.
    6.20 +
    6.21 +Before we take a look at Mercurial's bundled styles, let's review its
    6.22 +normal output.
    6.23 +
    6.24 +\interaction{template.simple.normal}
    6.25 +
    6.26 +This is somewhat informative, but it takes up a lot of space---five
    6.27 +lines of output per changeset.  The \texttt{compact} style reduces
    6.28 +this to three lines, presented in a sparse manner.
    6.29 +
    6.30 +\interaction{template.simple.compact}
    6.31 +
    6.32 +The \texttt{changelog} style hints at the expressive power of
    6.33 +Mercurial's templating engine.  This style attempts to follow the GNU
    6.34 +Project's changelog guidelines\cite{web:changelog}.
    6.35 +
    6.36 +\interaction{template.simple.changelog}
    6.37 +
    6.38 +You will not be shocked to learn that Mercurial's default output style
    6.39 +is named \texttt{default}.
    6.40 +
    6.41 +\subsection{Setting an output style to use}
    6.42 +
    6.43 +You can modify the output style that Mercurial will use for every
    6.44 +command by editing your \hgrc\ file, naming the style you would
    6.45 +prefer to use.
    6.46 +
    6.47 +\begin{codesample2}
    6.48 +  [ui]
    6.49 +  style = compact
    6.50 +\end{codesample2}
    6.51 +
    6.52 +If you write a style of your own, you can use it by either providing
    6.53 +the path to your style file, or copying your style file into a
    6.54 +location where Mercurial can find it (typically the \texttt{templates}
    6.55 +subdirectory of your Mercurial install directory).
    6.56 +
    6.57 +\section{Commands that support styles and templates}
    6.58 +
    6.59 +All of Mercurial's ``\texttt{log}-like'' commands let you use styles
    6.60 +and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
    6.61 +\hgcmd{tip}.
    6.62 +
    6.63 +As I write this manual, these are so far the only commands that
    6.64 +support styles and templates.  Since these are the most important
    6.65 +commands that need customisable output, there has been little pressure
    6.66 +from the Mercurial user community to add style and template support to
    6.67 +other commands.
    6.68 +
    6.69 +\section{The basics of templating}
    6.70 +
    6.71 +At its simplest, a Mercurial template is a piece of text.  Some of the
    6.72 +text never changes, while other parts are \emph{expanded}, or replaced
    6.73 +with new text, when necessary.
    6.74 +
    6.75 +Before we continue, let's look again at a simple example of
    6.76 +Mercurial's normal output.
    6.77 +
    6.78 +\interaction{template.simple.normal}
    6.79 +
    6.80 +Now, let's run the same command, but using a template to change its
    6.81 +output.
    6.82 +
    6.83 +\interaction{template.simple.simplest}
    6.84 +
    6.85 +The example above illustrates the simplest possible template; it's
    6.86 +just a piece of static text, printed once for each changeset.  The
    6.87 +\hgopt{log}{--template} option to the \hgcmd{log} command tells
    6.88 +Mercurial to use the given text as the template when printing each
    6.89 +changeset.
    6.90 +
    6.91 +Notice that the template string above ends with the text
    6.92 +``\Verb+\n+''.  This is an \emph{escape sequence}, telling Mercurial
    6.93 +to print a newline at the end of each template item.  If you omit this
    6.94 +newline, Mercurial will run each piece of output together.  See
    6.95 +section~\ref{sec:template:escape} for more details of escape sequences.
    6.96 +
    6.97 +A template that prints a fixed string of text all the time isn't very
    6.98 +useful; let's try something a bit more complex.
    6.99 +
   6.100 +\interaction{template.simple.simplesub}
   6.101 +
   6.102 +As you can see, the string ``\Verb+{desc}+'' in the template has been
   6.103 +replaced in the output with the description of each changeset.  Every
   6.104 +time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
   6.105 +and ``\texttt{\}}''), it will try to replace the braces and text with
   6.106 +the expansion of whatever is inside.  To print a literal curly brace,
   6.107 +you must escape it, as described in section~\ref{sec:template:escape}.
   6.108 +
   6.109 +\section{Basic template keywords}
   6.110 +\label{sec:template:keyword}
   6.111 +
   6.112 +You can start writing simple templates immediately using the keywords
   6.113 +below.
   6.114 +
   6.115 +\begin{itemize}
   6.116 +\item[\tplkword{author}] String.  The unmodified author of the changeset.
   6.117 +\item[\tplkword{date}] Date information.  The date when the changeset
   6.118 +  was committed.  This is \emph{not} human-readable; you must pass it
   6.119 +  through a filter that will render it appropriately.  See
   6.120 +  section~\ref{sec:template:filter} for more information on filters.
   6.121 +  The date is expressed as a pair of numbers.  The first number is a
   6.122 +  Unix UTC timestamp (seconds since January 1, 1970); the second is
   6.123 +  the offset of the committer's timezone from UTC, in seconds.
   6.124 +\item[\tplkword{desc}] String.  The text of the changeset description.
   6.125 +\item[\tplkword{files}] List of strings.  All files modified, added, or
   6.126 +  removed by this changeset.
   6.127 +\item[\tplkword{file\_adds}] List of strings.  Files added by this
   6.128 +  changeset.
   6.129 +\item[\tplkword{file\_dels}] List of strings.  Files removed by this
   6.130 +  changeset.
   6.131 +\item[\tplkword{node}] String.  The changeset identification hash, as a
   6.132 +  40-character hexadecimal string.
   6.133 +\item[\tplkword{parents}] List of strings.  The parents of the
   6.134 +  changeset.
   6.135 +\item[\tplkword{rev}] Integer.  The repository-local changeset revision
   6.136 +  number.
   6.137 +\item[\tplkword{tags}] List of strings.  Any tags associated with the
   6.138 +  changeset.
   6.139 +\end{itemize}
   6.140 +
   6.141 +A few simple experiments will show us what to expect when we use these
   6.142 +keywords; you can see the results in
   6.143 +figure~\ref{fig:template:keywords}.
   6.144 +
   6.145 +\begin{figure}
   6.146 +  \interaction{template.simple.keywords}
   6.147 +  \caption{Template keywords in use}
   6.148 +  \label{fig:template:keywords}
   6.149 +\end{figure}
   6.150 +
   6.151 +As we noted above, the date keyword does not produce human-readable
   6.152 +output, so we must treat it specially.  This involves using a
   6.153 +\emph{filter}, about which more in section~\ref{sec:template:filter}.
   6.154 +
   6.155 +\interaction{template.simple.datekeyword}
   6.156 +
   6.157 +\section{Escape sequences}
   6.158 +\label{sec:template:escape}
   6.159 +
   6.160 +Mercurial's templating engine recognises the most commonly used escape
   6.161 +sequences in strings.  When it sees a backslash (``\Verb+\+'')
   6.162 +character, it looks at the following character and substitutes the two
   6.163 +characters with a single replacement, as described below.
   6.164 +
   6.165 +\begin{itemize}
   6.166 +\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
   6.167 +  ASCII~134.
   6.168 +\item[\Verb+\textbackslash n+] Newline, ASCII~12.
   6.169 +\item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
   6.170 +\item[\Verb+\textbackslash t+] Tab, ASCII~11.
   6.171 +\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
   6.172 +\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
   6.173 +\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
   6.174 +\end{itemize}
   6.175 +
   6.176 +As indicated above, if you want the expansion of a template to contain
   6.177 +a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
   6.178 +must escape it.
   6.179 +
   6.180 +\section{Filtering expanded keywords}
   6.181 +\label{sec:template:filter}
   6.182 +
   6.183 +Some of the results of template expansion are not entirely easy to
   6.184 +use.  Mercurial lets you specify an optional chain of \emph{filters}
   6.185 +to modify the result of expanding a keyword.  You have already seen a
   6.186 +common filter, \tplkwfilt{date}{isodate}, in action above, to make a
   6.187 +date readable.
   6.188 +
   6.189 +\begin{itemize}
   6.190 +\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
   6.191 +  tag before the end of every line except the last.  For example,
   6.192 +  ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
   6.193 +\item[\tplkwfilt{date}{age}] \tplkword{date} keyword.  Render the
   6.194 +  age of the date, relative to the current time.  Yields a string like
   6.195 +  ``\Verb+10 minutes+''.
   6.196 +\item[\tplfilter{basename}] Any text, but most useful for the
   6.197 +  \tplkword{files} keyword and its relatives.  Treat the text as a
   6.198 +  path, and return the basename. For example, ``\Verb+foo/bar/baz+''
   6.199 +  becomes ``\Verb+baz+''.
   6.200 +\item[\tplkwfilt{date}{date}] \tplkword{date} keyword.  Render a date
   6.201 +  in a similar format to the Unix \tplkword{date} command, but with
   6.202 +  timezone included.  Yields a string like
   6.203 +  ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
   6.204 +\item[\tplkwfilt{author}{domain}] Any text, but most useful for the
   6.205 +  \tplkword{author} keyword.  Finds the first string that looks like
   6.206 +  an email address, and extract just the domain component.  For
   6.207 +  example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   6.208 +  ``\Verb+serpentine.com+''.
   6.209 +\item[\tplkwfilt{author}{email}] Any text, but most useful for the
   6.210 +  \tplkword{author} keyword.  Extract the first string that looks like
   6.211 +  an email address.  For example,
   6.212 +  ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   6.213 +  ``\Verb+bos@serpentine.com+''.
   6.214 +\item[\tplfilter{escape}] Any text.  Replace the special XML/XHTML
   6.215 +  characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
   6.216 +  XML entities.
   6.217 +\item[\tplfilter{fill68}] Any text.  Wrap the text to fit in 68
   6.218 +  columns.  This is useful before you pass text through the
   6.219 +  \tplfilter{tabindent} filter, and still want it to fit in an
   6.220 +  80-column fixed-font window.
   6.221 +\item[\tplfilter{fill76}] Any text.  Wrap the text to fit in 76
   6.222 +  columns.
   6.223 +\item[\tplfilter{firstline}] Any text.  Yield the first line of text,
   6.224 +  without any trailing newlines.
   6.225 +\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword.  Render the
   6.226 +  date as a pair of readable numbers.  Yields a string like
   6.227 +  ``\Verb+1157407993 25200+''.
   6.228 +\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword.  Render the
   6.229 +  date as a text string in ISO~8601 format.  Yields a string like
   6.230 +  ``\Verb+2006-09-04 15:13:13 -0700+''.
   6.231 +\item[\tplfilter{obfuscate}] Any text, but most useful for the
   6.232 +  \tplkword{author} keyword.  Yield the input text rendered as a
   6.233 +  sequence of XML entities.  This helps to defeat some particularly
   6.234 +  stupid screen-scraping email harvesting spambots.
   6.235 +\item[\tplkwfilt{author}{person}] Any text, but most useful for the
   6.236 +  \tplkword{author} keyword.  Yield the text before an email address.
   6.237 +  For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
   6.238 +  becomes ``\Verb+Bryan O'Sullivan+''.
   6.239 +\item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword.  Render a
   6.240 +  date using the same format used in email headers.  Yields a string
   6.241 +  like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
   6.242 +\item[\tplkwfilt{node}{short}] Changeset hash.  Yield the short form
   6.243 +  of a changeset hash, i.e.~a 12-byte hexadecimal string.
   6.244 +\item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword.  Render
   6.245 +  the year, month, and day of the date.  Yields a string like
   6.246 +  ``\Verb+2006-09-04+''.
   6.247 +\item[\tplfilter{strip}] Any text.  Strip all leading and trailing
   6.248 +  whitespace from the string.
   6.249 +\item[\tplfilter{tabindent}] Any text.  Yield the text, with every line
   6.250 +  except the first starting with a tab character.
   6.251 +\item[\tplfilter{urlescape}] Any text.  Escape all characters that are
   6.252 +  considered ``special'' by URL parsers.  For example, \Verb+foo bar+
   6.253 +  becomes \Verb+foo%20bar+.
   6.254 +\item[\tplkwfilt{author}{user}] Any text, but most useful for the
   6.255 +  \tplkword{author} keyword.  Return the ``user'' portion of an email
   6.256 +  address.  For example,
   6.257 +  ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
   6.258 +  ``\Verb+bos+''.
   6.259 +\end{itemize}
   6.260 +
   6.261 +\begin{figure}
   6.262 +  \interaction{template.simple.manyfilters}
   6.263 +  \caption{Template filters in action}
   6.264 +  \label{fig:template:filters}
   6.265 +\end{figure}
   6.266 +
   6.267 +\begin{note}
   6.268 +  If you try to apply a filter to a piece of data that it cannot
   6.269 +  process, Mercurial will fail and print a Python exception.  For
   6.270 +  example, trying to run the output of the \tplkword{desc} keyword
   6.271 +  into the \tplkwfilt{date}{isodate} filter is not a good idea.
   6.272 +\end{note}
   6.273 +
   6.274 +\subsection{Combining filters}
   6.275 +
   6.276 +It is easy to combine filters to yield output in the form you would
   6.277 +like.  The following chain of filters tidies up a description, then
   6.278 +makes sure that it fits cleanly into 68 columns, then indents it by a
   6.279 +further 8~characters (at least on Unix-like systems, where a tab is
   6.280 +conventionally 8~characters wide).
   6.281 +
   6.282 +\interaction{template.simple.combine}
   6.283 +
   6.284 +Note the use of ``\Verb+\t+'' (a tab character) in the template to
   6.285 +force the first line to be indented; this is necessary since
   6.286 +\tplkword{tabindent} indents all lines \emph{except} the first.
   6.287 +
   6.288 +Keep in mind that the order of filters in a chain is significant.
   6.289 +Using \Verb+fill68|tabindent+ gives very different results from
   6.290 +\Verb+tabindent|fill68+.
   6.291  
   6.292  %%% Local Variables: 
   6.293  %%% mode: latex