annotate ja/template.tex @ 290:b0db5adf11c1 ja_root

fork Japanese translation.
author Yoshiki Yazawa <yaz@cc.rim.or.jp>
date Wed, 06 Feb 2008 17:43:11 +0900
parents en/template.tex@a239cd51dcd3
children 3b1291f24c0d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
1 \chapter{Customising the output of Mercurial}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
2 \label{chap:template}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
3
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
4 Mercurial provides a powerful mechanism to let you control how it
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
5 displays information. The mechanism is based on templates. You can
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
6 use templates to generate specific output for a single command, or to
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
7 customise the entire appearance of the built-in web interface.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
8
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
9 \section{Using precanned output styles}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
10 \label{sec:style}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
11
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
12 Packaged with Mercurial are some output styles that you can use
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
13 immediately. A style is simply a precanned template that someone
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
14 wrote and installed somewhere that Mercurial can find.
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
15
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
16 Before we take a look at Mercurial's bundled styles, let's review its
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
17 normal output.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
18
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
19 \interaction{template.simple.normal}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
20
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
21 This is somewhat informative, but it takes up a lot of space---five
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
22 lines of output per changeset. The \texttt{compact} style reduces
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
23 this to three lines, presented in a sparse manner.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
24
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
25 \interaction{template.simple.compact}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
26
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
27 The \texttt{changelog} style hints at the expressive power of
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
28 Mercurial's templating engine. This style attempts to follow the GNU
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
29 Project's changelog guidelines\cite{web:changelog}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
30
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
31 \interaction{template.simple.changelog}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
32
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
33 You will not be shocked to learn that Mercurial's default output style
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
34 is named \texttt{default}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
35
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
36 \subsection{Setting a default style}
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
37
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
38 You can modify the output style that Mercurial will use for every
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
39 command by editing your \hgrc\ file, naming the style you would
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
40 prefer to use.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
41
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
42 \begin{codesample2}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
43 [ui]
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
44 style = compact
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
45 \end{codesample2}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
46
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
47 If you write a style of your own, you can use it by either providing
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
48 the path to your style file, or copying your style file into a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
49 location where Mercurial can find it (typically the \texttt{templates}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
50 subdirectory of your Mercurial install directory).
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
51
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
52 \section{Commands that support styles and templates}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
53
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
54 All of Mercurial's ``\texttt{log}-like'' commands let you use styles
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
55 and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
56 \hgcmd{tip}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
57
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
58 As I write this manual, these are so far the only commands that
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
59 support styles and templates. Since these are the most important
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
60 commands that need customisable output, there has been little pressure
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
61 from the Mercurial user community to add style and template support to
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
62 other commands.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
63
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
64 \section{The basics of templating}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
65
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
66 At its simplest, a Mercurial template is a piece of text. Some of the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
67 text never changes, while other parts are \emph{expanded}, or replaced
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
68 with new text, when necessary.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
69
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
70 Before we continue, let's look again at a simple example of
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
71 Mercurial's normal output.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
72
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
73 \interaction{template.simple.normal}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
74
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
75 Now, let's run the same command, but using a template to change its
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
76 output.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
77
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
78 \interaction{template.simple.simplest}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
79
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
80 The example above illustrates the simplest possible template; it's
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
81 just a piece of static text, printed once for each changeset. The
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
82 \hgopt{log}{--template} option to the \hgcmd{log} command tells
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
83 Mercurial to use the given text as the template when printing each
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
84 changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
85
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
86 Notice that the template string above ends with the text
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
87 ``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
88 to print a newline at the end of each template item. If you omit this
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
89 newline, Mercurial will run each piece of output together. See
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
90 section~\ref{sec:template:escape} for more details of escape sequences.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
91
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
92 A template that prints a fixed string of text all the time isn't very
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
93 useful; let's try something a bit more complex.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
94
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
95 \interaction{template.simple.simplesub}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
96
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
97 As you can see, the string ``\Verb+{desc}+'' in the template has been
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
98 replaced in the output with the description of each changeset. Every
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
99 time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
100 and ``\texttt{\}}''), it will try to replace the braces and text with
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
101 the expansion of whatever is inside. To print a literal curly brace,
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
102 you must escape it, as described in section~\ref{sec:template:escape}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
103
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
104 \section{Common template keywords}
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
105 \label{sec:template:keyword}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
106
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
107 You can start writing simple templates immediately using the keywords
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
108 below.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
109
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
110 \begin{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
111 \item[\tplkword{author}] String. The unmodified author of the changeset.
208
a239cd51dcd3 Note "branches" keyword for templates.
Bryan O'Sullivan <bos@serpentine.com>
parents: 83
diff changeset
112 \item[\tplkword{branches}] String. The name of the branch on which
a239cd51dcd3 Note "branches" keyword for templates.
Bryan O'Sullivan <bos@serpentine.com>
parents: 83
diff changeset
113 the changeset was committed. Will be empty if the branch name was
a239cd51dcd3 Note "branches" keyword for templates.
Bryan O'Sullivan <bos@serpentine.com>
parents: 83
diff changeset
114 \texttt{default}.
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
115 \item[\tplkword{date}] Date information. The date when the changeset
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
116 was committed. This is \emph{not} human-readable; you must pass it
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
117 through a filter that will render it appropriately. See
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
118 section~\ref{sec:template:filter} for more information on filters.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
119 The date is expressed as a pair of numbers. The first number is a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
120 Unix UTC timestamp (seconds since January 1, 1970); the second is
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
121 the offset of the committer's timezone from UTC, in seconds.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
122 \item[\tplkword{desc}] String. The text of the changeset description.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
123 \item[\tplkword{files}] List of strings. All files modified, added, or
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
124 removed by this changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
125 \item[\tplkword{file\_adds}] List of strings. Files added by this
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
126 changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
127 \item[\tplkword{file\_dels}] List of strings. Files removed by this
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
128 changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
129 \item[\tplkword{node}] String. The changeset identification hash, as a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
130 40-character hexadecimal string.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
131 \item[\tplkword{parents}] List of strings. The parents of the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
132 changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
133 \item[\tplkword{rev}] Integer. The repository-local changeset revision
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
134 number.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
135 \item[\tplkword{tags}] List of strings. Any tags associated with the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
136 changeset.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
137 \end{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
138
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
139 A few simple experiments will show us what to expect when we use these
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
140 keywords; you can see the results in
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
141 figure~\ref{fig:template:keywords}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
142
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
143 \begin{figure}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
144 \interaction{template.simple.keywords}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
145 \caption{Template keywords in use}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
146 \label{fig:template:keywords}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
147 \end{figure}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
148
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
149 As we noted above, the date keyword does not produce human-readable
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
150 output, so we must treat it specially. This involves using a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
151 \emph{filter}, about which more in section~\ref{sec:template:filter}.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
152
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
153 \interaction{template.simple.datekeyword}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
154
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
155 \section{Escape sequences}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
156 \label{sec:template:escape}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
157
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
158 Mercurial's templating engine recognises the most commonly used escape
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
159 sequences in strings. When it sees a backslash (``\Verb+\+'')
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
160 character, it looks at the following character and substitutes the two
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
161 characters with a single replacement, as described below.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
162
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
163 \begin{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
164 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
165 ASCII~134.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
166 \item[\Verb+\textbackslash n+] Newline, ASCII~12.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
167 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
168 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
169 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
170 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
171 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
172 \end{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
173
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
174 As indicated above, if you want the expansion of a template to contain
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
175 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
176 must escape it.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
177
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
178 \section{Filtering keywords to change their results}
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
179 \label{sec:template:filter}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
180
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
181 Some of the results of template expansion are not immediately easy to
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
182 use. Mercurial lets you specify an optional chain of \emph{filters}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
183 to modify the result of expanding a keyword. You have already seen a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
184 common filter, \tplkwfilt{date}{isodate}, in action above, to make a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
185 date readable.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
186
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
187 Below is a list of the most commonly used filters that Mercurial
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
188 supports. While some filters can be applied to any text, others can
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
189 only be used in specific circumstances. The name of each filter is
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
190 followed first by an indication of where it can be used, then a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
191 description of its effect.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
192
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
193 \begin{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
194 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
195 tag before the end of every line except the last. For example,
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
196 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
197 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
198 age of the date, relative to the current time. Yields a string like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
199 ``\Verb+10 minutes+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
200 \item[\tplfilter{basename}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
201 \tplkword{files} keyword and its relatives. Treat the text as a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
202 path, and return the basename. For example, ``\Verb+foo/bar/baz+''
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
203 becomes ``\Verb+baz+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
204 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
205 in a similar format to the Unix \tplkword{date} command, but with
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
206 timezone included. Yields a string like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
207 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
208 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
209 \tplkword{author} keyword. Finds the first string that looks like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
210 an email address, and extract just the domain component. For
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
211 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
212 ``\Verb+serpentine.com+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
213 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
214 \tplkword{author} keyword. Extract the first string that looks like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
215 an email address. For example,
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
216 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
217 ``\Verb+bos@serpentine.com+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
218 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
219 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
220 XML entities.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
221 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
222 columns. This is useful before you pass text through the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
223 \tplfilter{tabindent} filter, and still want it to fit in an
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
224 80-column fixed-font window.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
225 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
226 columns.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
227 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
228 without any trailing newlines.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
229 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
230 date as a pair of readable numbers. Yields a string like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
231 ``\Verb+1157407993 25200+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
232 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
233 date as a text string in ISO~8601 format. Yields a string like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
234 ``\Verb+2006-09-04 15:13:13 -0700+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
235 \item[\tplfilter{obfuscate}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
236 \tplkword{author} keyword. Yield the input text rendered as a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
237 sequence of XML entities. This helps to defeat some particularly
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
238 stupid screen-scraping email harvesting spambots.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
239 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
240 \tplkword{author} keyword. Yield the text before an email address.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
241 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
242 becomes ``\Verb+Bryan O'Sullivan+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
243 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
244 date using the same format used in email headers. Yields a string
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
245 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
246 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
247 of a changeset hash, i.e.~a 12-byte hexadecimal string.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
248 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
249 the year, month, and day of the date. Yields a string like
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
250 ``\Verb+2006-09-04+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
251 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
252 whitespace from the string.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
253 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
254 except the first starting with a tab character.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
255 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
256 considered ``special'' by URL parsers. For example, \Verb+foo bar+
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
257 becomes \Verb+foo%20bar+.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
258 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
259 \tplkword{author} keyword. Return the ``user'' portion of an email
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
260 address. For example,
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
261 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
262 ``\Verb+bos+''.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
263 \end{itemize}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
264
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
265 \begin{figure}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
266 \interaction{template.simple.manyfilters}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
267 \caption{Template filters in action}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
268 \label{fig:template:filters}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
269 \end{figure}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
270
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
271 \begin{note}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
272 If you try to apply a filter to a piece of data that it cannot
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
273 process, Mercurial will fail and print a Python exception. For
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
274 example, trying to run the output of the \tplkword{desc} keyword
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
275 into the \tplkwfilt{date}{isodate} filter is not a good idea.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
276 \end{note}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
277
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
278 \subsection{Combining filters}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
279
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
280 It is easy to combine filters to yield output in the form you would
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
281 like. The following chain of filters tidies up a description, then
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
282 makes sure that it fits cleanly into 68 columns, then indents it by a
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
283 further 8~characters (at least on Unix-like systems, where a tab is
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
284 conventionally 8~characters wide).
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
285
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
286 \interaction{template.simple.combine}
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
287
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
288 Note the use of ``\Verb+\t+'' (a tab character) in the template to
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
289 force the first line to be indented; this is necessary since
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
290 \tplkword{tabindent} indents all lines \emph{except} the first.
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
291
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
292 Keep in mind that the order of filters in a chain is significant. The
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
293 first filter is applied to the result of the keyword; the second to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
294 the result of the first filter; and so on. For example, using
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
295 \Verb+fill68|tabindent+ gives very different results from
80
ea951cfb5cd9 Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents: 76
diff changeset
296 \Verb+tabindent|fill68+.
76
df88df78288d Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
297
83
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
298
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
299 \section{From templates to styles}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
300
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
301 A command line template provides a quick and simple way to format some
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
302 output. Templates can become verbose, though, and it's useful to be
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
303 able to give a template a name. A style file is a template with a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
304 name, stored in a file.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
305
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
306 More than that, using a style file unlocks the power of Mercurial's
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
307 templating engine in ways that are not possible using the command line
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
308 \hgopt{log}{--template} option.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
309
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
310 \subsection{The simplest of style files}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
311
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
312 Our simple style file contains just one line:
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
313
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
314 \interaction{template.simple.rev}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
315
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
316 This tells Mercurial, ``if you're printing a changeset, use the text
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
317 on the right as the template''.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
318
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
319 \subsection{Style file syntax}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
320
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
321 The syntax rules for a style file are simple.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
322
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
323 \begin{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
324 \item The file is processed one line at a time.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
325
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
326 \item Leading and trailing white space are ignored.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
327
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
328 \item Empty lines are skipped.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
329
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
330 \item If a line starts with either of the characters ``\texttt{\#}'' or
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
331 ``\texttt{;}'', the entire line is treated as a comment, and skipped
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
332 as if empty.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
333
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
334 \item A line starts with a keyword. This must start with an
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
335 alphabetic character or underscore, and can subsequently contain any
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
336 alphanumeric character or underscore. (In regexp notation, a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
337 keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
338
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
339 \item The next element must be an ``\texttt{=}'' character, which can
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
340 be preceded or followed by an arbitrary amount of white space.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
341
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
342 \item If the rest of the line starts and ends with matching quote
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
343 characters (either single or double quote), it is treated as a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
344 template body.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
345
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
346 \item If the rest of the line \emph{does not} start with a quote
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
347 character, it is treated as the name of a file; the contents of this
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
348 file will be read and used as a template body.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
349 \end{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
350
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
351 \section{Style files by example}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
352
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
353 To illustrate how to write a style file, we will construct a few by
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
354 example. Rather than provide a complete style file and walk through
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
355 it, we'll mirror the usual process of developing a style file by
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
356 starting with something very simple, and walking through a series of
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
357 successively more complete examples.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
358
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
359 \subsection{Identifying mistakes in style files}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
360
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
361 If Mercurial encounters a problem in a style file you are working on,
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
362 it prints a terse error message that, once you figure out what it
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
363 means, is actually quite useful.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
364
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
365 \interaction{template.svnstyle.syntax.input}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
366
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
367 Notice that \filename{broken.style} attempts to define a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
368 \texttt{changeset} keyword, but forgets to give any content for it.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
369 When instructed to use this style file, Mercurial promptly complains.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
370
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
371 \interaction{template.svnstyle.syntax.error}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
372
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
373 This error message looks intimidating, but it is not too hard to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
374 follow.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
375
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
376 \begin{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
377 \item The first component is simply Mercurial's way of saying ``I am
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
378 giving up''.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
379 \begin{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
380 \textbf{abort:} broken.style:1: parse error
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
381 \end{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
382
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
383 \item Next comes the name of the style file that contains the error.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
384 \begin{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
385 abort: \textbf{broken.style}:1: parse error
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
386 \end{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
387
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
388 \item Following the file name is the line number where the error was
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
389 encountered.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
390 \begin{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
391 abort: broken.style:\textbf{1}: parse error
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
392 \end{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
393
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
394 \item Finally, a description of what went wrong.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
395 \begin{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
396 abort: broken.style:1: \textbf{parse error}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
397 \end{codesample4}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
398 The description of the problem is not always clear (as in this
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
399 case), but even when it is cryptic, it is almost always trivial to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
400 visually inspect the offending line in the style file and see what
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
401 is wrong.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
402 \end{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
403
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
404 \subsection{Uniquely identifying a repository}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
405
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
406 If you would like to be able to identify a Mercurial repository
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
407 ``fairly uniquely'' using a short string as an identifier, you can
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
408 use the first revision in the repository.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
409 \interaction{template.svnstyle.id}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
410 This is not guaranteed to be unique, but it is nevertheless useful in
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
411 many cases.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
412 \begin{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
413 \item It will not work in a completely empty repository, because such
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
414 a repository does not have a revision~zero.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
415 \item Neither will it work in the (extremely rare) case where a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
416 repository is a merge of two or more formerly independent
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
417 repositories, and you still have those repositories around.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
418 \end{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
419 Here are some uses to which you could put this identifier:
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
420 \begin{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
421 \item As a key into a table for a database that manages repositories
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
422 on a server.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
423 \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
424 Save this information away when you run an automated build or other
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
425 activity, so that you can ``replay'' the build later if necessary.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
426 \end{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
427
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
428 \subsection{Mimicking Subversion's output}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
429
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
430 Let's try to emulate the default output format used by another
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
431 revision control tool, Subversion.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
432 \interaction{template.svnstyle.short}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
433
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
434 Since Subversion's output style is fairly simple, it is easy to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
435 copy-and-paste a hunk of its output into a file, and replace the text
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
436 produced above by Subversion with the template values we'd like to see
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
437 expanded.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
438 \interaction{template.svnstyle.template}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
439
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
440 There are a few small ways in which this template deviates from the
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
441 output produced by Subversion.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
442 \begin{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
443 \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
444 2006}'' in the example output above) in parentheses. Mercurial's
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
445 templating engine does not provide a way to display a date in this
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
446 format without also printing the time and time zone.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
447 \item We emulate Subversion's printing of ``separator'' lines full of
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
448 ``\texttt{-}'' characters by ending the template with such a line.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
449 We use the templating engine's \tplkword{header} keyword to print a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
450 separator line as the first line of output (see below), thus
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
451 achieving similar output to Subversion.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
452 \item Subversion's output includes a count in the header of the number
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
453 of lines in the commit message. We cannot replicate this in
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
454 Mercurial; the templating engine does not currently provide a filter
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
455 that counts the number of items it is passed.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
456 \end{itemize}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
457 It took me no more than a minute or two of work to replace literal
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
458 text from an example of Subversion's output with some keywords and
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
459 filters to give the template above. The style file simply refers to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
460 the template.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
461 \interaction{template.svnstyle.style}
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
462
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
463 We could have included the text of the template file directly in the
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
464 style file by enclosing it in quotes and replacing the newlines with
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
465 ``\texttt{\\n}'' sequences, but it would have made the style file too
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
466 difficult to read. Readability is a good guide when you're trying to
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
467 decide whether some text belongs in a style file, or in a template
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
468 file that the style file points to. If the style file will look too
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
469 big or cluttered if you insert a literal piece of text, drop it into a
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
470 template instead.
b476081a9c04 Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents: 80
diff changeset
471
76
df88df78288d Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
472 %%% Local Variables:
df88df78288d Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
473 %%% mode: latex
df88df78288d Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
474 %%% TeX-master: "00book"
df88df78288d Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff changeset
475 %%% End: