Mercurial > hgbook
annotate ja/template.tex @ 360:45ad9986748a
started template.tex
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Mon, 22 Sep 2008 01:42:57 +0900 |
parents | 3b1291f24c0d |
children | 96437101a088 |
rev | line source |
---|---|
360 | 1 %\chapter{Customising the output of Mercurial} |
2 \chapter{Mercurial$B$N=PNO$N%+%9%?%^%$%:(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
3 \label{chap:template} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
4 |
360 | 5 %Mercurial provides a powerful mechanism to let you control how it |
6 %displays information. The mechanism is based on templates. You can | |
7 %use templates to generate specific output for a single command, or to | |
8 %customise the entire appearance of the built-in web interface. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
9 |
360 | 10 Mercurial$B$K$O>pJs$NI=<($r%3%s%H%m!<%k$9$k$?$a$N6/NO$J5!9=$,$"$k!%$3$N5!9=(B |
11 $B$O%F%s%W%l!<%H$r%Y!<%9$H$7$F$$$k!%%F%s%W%l!<%H$K$h$C$F$"$k%3%^%s%I$+$iFC(B | |
12 $BJL$N=PNO$r9T$C$?$j!$FbB"$N%&%'%V%$%s%?%U%'!<%9$N8+$?L\$r%+%9%?%^%$%:$9$k(B | |
13 $B$3$H$,$G$-$k!%(B | |
14 | |
15 %\section{Using precanned output styles} | |
16 \section{$BMQ0U$5$l$?=PNO%9%?%$%k$NMxMQ(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
17 \label{sec:style} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
18 |
360 | 19 %Packaged with Mercurial are some output styles that you can use |
20 %immediately. A style is simply a precanned template that someone | |
21 %wrote and installed somewhere that Mercurial can find. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
22 |
360 | 23 $B$9$0$K;H$&$3$H$N$G$-$k$$$/$D$+$N%9%?%$%k$,(BMercurial$B$KF1:-$5$l$F$$$k!%%9%?(B |
24 $B%$%k$H$O4L5M$5$l$?%F%s%W%l!<%H$G$"$j!$(B Mercurial$B$N%$%s%9%H!<%k$5$l$?$I$3(B | |
25 $B$+$N%^%7%s$GC/$+$,=q$$$F%$%s%9%H!<%k$7$?$b$N$G$"$k!%(B | |
26 | |
27 %Before we take a look at Mercurial's bundled styles, let's review its | |
28 %normal output. | |
29 | |
30 Mercurial$BF1:-$N%9%?%$%k$r8+$kA0$K!$DL>o$N=PNO$r8+$F$_$h$&!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
31 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
32 \interaction{template.simple.normal} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
33 |
360 | 34 %This is somewhat informative, but it takes up a lot of space---five |
35 %lines of output per changeset. The \texttt{compact} style reduces | |
36 %this to three lines, presented in a sparse manner. | |
37 | |
38 $B$3$N=PNO$K$OM-1W$J>pJs$,4^$^$l$F$$$k$,!$(B1$B$D$N%A%'%s%8%;%C%HKh$K(B5$B9T$r;H$&(B | |
39 $B$J$I!$B?$/$N%9%Z!<%9$rHq$d$9!%(B\texttt{compact}$B%9%?%$%k$OAB$i$JJ}K!$r;H$&(B | |
40 $B$3$H$G$3$l$r(B3$B9T$K8:$i$9!%(B | |
80
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 \interaction{template.simple.compact} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
43 |
360 | 44 %The \texttt{changelog} style hints at the expressive power of |
45 %Mercurial's templating engine. This style attempts to follow the GNU | |
46 %Project's changelog guidelines\cite{web:changelog}. | |
47 | |
48 \texttt{changelog}$B%9%?%$%k$O(BMercurial$B$N%F%s%W%l!<%H%(%s%8%s$N0RNO$rCN$k$$(B | |
49 $B$$Nc$G$"$k!%$3$N%9%?%$%k$O(BGNU$B%W%m%8%'%/%H$N(Bchangelog$B%,%$%I%i%$%s(B | |
50 \cite{web:changelog}$B$K=>$*$&$H$9$k!%(B | |
80
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 \interaction{template.simple.changelog} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
53 |
360 | 54 %You will not be shocked to learn that Mercurial's default output style |
55 %is named \texttt{default}. | |
56 | |
57 Mercurial$B$N%G%U%)%k%H=PNO%9%?%$%k$,(B\texttt{default}$B$HL>IU$1$i$l$F$$$k$N(B | |
58 $B$O6C$/$KCM$7$J$$!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
59 |
360 | 60 %\subsection{Setting a default style} |
61 \subsection{$B%G%U%)%k%H%9%?%$%k$N@_Dj(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
62 |
360 | 63 %You can modify the output style that Mercurial will use for every |
64 %command by editing your \hgrc file, naming the style you would | |
65 %prefer to use. | |
66 | |
67 Mercurial$B$NA4$F$N%3%^%s%I$GMQ$$$i$l$k=PNO%9%?%$%k$O(B\hgrc$B%U%!%$%k$rJT=8$9(B | |
68 $B$k$3$H$G@_Dj$G$-!$9%$-$JL>A0$rIU$1$k$3$H$,$G$-$k!%(B | |
80
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 \begin{codesample2} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
71 [ui] |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
72 style = compact |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
73 \end{codesample2} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
74 |
360 | 75 %If you write a style of your own, you can use it by either providing |
76 %the path to your style file, or copying your style file into a | |
77 %location where Mercurial can find it (typically the \texttt{templates} | |
78 %subdirectory of your Mercurial install directory). | |
79 | |
80 $B<+J,$G%9%?%$%k$r=q$$$?$H$-$O!$%9%?%$%k%U%!%$%k$N%Q%9$rDI2C$7$?$j!$%U%!%$(B | |
81 $B%k$r(BMercurial$B$,H/8+$G$-$k>l=j(B($BE57?E*$K$O!$(BMercurial$B$N%$%s%9%H!<%k%G%#%l%/(B | |
82 $B%H%j$N(B\texttt{templates}$B%5%V%G%#%l%/%H%j(B)$B$K%3%T!<$9$k$3$H$GMxMQ2DG=$K$J(B | |
83 $B$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
84 |
360 | 85 %\section{Commands that support styles and templates} |
86 \section{$B%9%?%$%k$H%F%s%W%l!<%H$r%5%]!<%H$9$k%3%^%s%I(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
87 |
360 | 88 %All of Mercurial's ``\texttt{log}-like'' commands let you use styles |
89 %and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and | |
90 %\hgcmd{tip}. | |
91 | |
92 Mercurial$B$N(B``\texttt{log}$B7O(B''$B$NA4$F$N%3%^%s%I(B: \hgcmd{incoming}, | |
93 \hgcmd{log}, \hgcmd{outgoing}, $B$*$h$S(B\hgcmd{tip}$B$O%9%?%$%k$H%F%s%W%l!<%H(B | |
94 $B$rMxMQ$7$F$$$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
95 |
360 | 96 %As I write this manual, these are so far the only commands that |
97 %support styles and templates. Since these are the most important | |
98 %commands that need customisable output, there has been little pressure | |
99 %from the Mercurial user community to add style and template support to | |
100 %other commands. | |
101 | |
102 $B$3$N%^%K%e%"%k$G=q$$$F$$$k$h$&$K!$$3$l$^$G$N$H$3$m!$$3$l$i$N%3%^%s%I$@$1(B | |
103 $B$,%9%?%$%k$H%F%s%W%l!<%H$r%5%]!<%H$7$F$$$k!%$3$l$i$,%+%9%?%^%$%:2DG=$J=P(B | |
104 $BNO$,I,MW$J:G$b=EMW$J%3%^%s%I$G$"$k$?$a!$(B Mercurial$B$N%f!<%6%3%_%e%K%F%#$+(B | |
105 $B$iB>$N%3%^%s%I$K%9%?%$%k$H%F%s%W%l!<%H%5%]!<%H$rE,MQ$+$N$&$K$;$h$H$$$&%W(B | |
106 $B%l%C%7%c!<$O$[$H$s$I$J$$!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
107 |
360 | 108 %\section{The basics of templating} |
109 \section{$B%F%s%W%l!<%H$N4pK\(B} | |
110 | |
111 %At its simplest, a Mercurial template is a piece of text. Some of the | |
112 %text never changes, while other parts are \emph{expanded}, or replaced | |
113 %with new text, when necessary. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
114 |
360 | 115 $B:G$bC1=c$J(BMercurial$B%F%s%W%l!<%H$O%F%-%9%HJR$G$"$k!%%F%-%9%H$N$"$kItJ,$OIT(B |
116 $BJQ$G!$B>$NItJ,$OI,MW$K1~$8$F(B\emph{$BE83+(B}$B$5$l$k$?$j?7$7$$%F%-%9%H$KCV49$5$l(B | |
117 $B$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
118 |
360 | 119 %Before we continue, let's look again at a simple example of |
120 %Mercurial's normal output. | |
121 | |
122 $B$5$i$KB3$1$kA0$K(BMercurial$BI8=`=PNO$NNc$r$b$&0lEY8+$F$_$h$&!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
123 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
124 \interaction{template.simple.normal} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
125 |
360 | 126 %Now, let's run the same command, but using a template to change its |
127 %output. | |
128 | |
129 $B$3$3$GF1$8%3%^%s%I$r=PNO$rJQ2=$5$;$k$?$a$K%F%s%W%l!<%H$r;H$C$F$_$h$&!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
130 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
131 \interaction{template.simple.simplest} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
132 |
360 | 133 %The example above illustrates the simplest possible template; it's |
134 %just a piece of static text, printed once for each changeset. The | |
135 %\hgopt{log}{--template} option to the \hgcmd{log} command tells | |
136 %Mercurial to use the given text as the template when printing each | |
137 %changeset. | |
138 | |
139 $B>e$NNc$O:G$bC1=c$J%F%s%W%l!<%H$r<($7$?(B; $B@EE*$J%F%-%9%H$@$1$+$i$J$j!$3F%A%'(B | |
140 $B%s%8%;%C%H$K$D$$$F0lEY$@$1=PNO$r9T$&!%(B\hgcmd{log}$B%3%^%s%I$K(B | |
141 \hgopt{log}{--template}$B%*%W%7%g%s$r;H$&$H(BMercurial$B$O3F!9$N%A%'%s%8%;%C%H(B | |
142 $B$r=PNO$9$k$H$-$K!$M?$($i$l$?%F%-%9%H$r%F%s%W%l!<%H$H$7$FMQ$$$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
143 |
360 | 144 %Notice that the template string above ends with the text |
145 %``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial | |
146 %to print a newline at the end of each template item. If you omit this | |
147 %newline, Mercurial will run each piece of output together. See | |
148 %section~\ref{sec:template:escape} for more details of escape sequences. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
149 |
360 | 150 $B%F%s%W%l!<%HJ8;zNs$O(B``\Verb+\n+''$B$G=*$k$3$H$KCm0U!%$3$l$O(BMercurial$B$K%F%s(B |
151 $B%W%l!<%H$N3FMWAG$NKvHx$K2~9T$r=PNO$9$k$h$&;X<($9$k(B\emph{$B%(%9%1!<%W%7!<%1(B | |
152 $B%s%9(B}$B$G$"$k!%$3$N2~9T$r>JN,$9$k$H(BMercurial$B$O3FMWAG$r7R$2$F=PNO$9$k!%%(%9(B | |
153 $B%1!<%W%7!<%1%s%9$N$h$j>\:Y$J@bL@$K$D$$$F$O(B~\ref{sec:template:escape}$B@a$r(B | |
154 $B;2>H$N$3$H!%(B | |
155 | |
156 %A template that prints a fixed string of text all the time isn't very | |
157 %useful; let's try something a bit more complex. | |
158 | |
159 $B>o$K8GDjJ8;zNs$r=PNO$9$k%F%s%W%l!<%H$O$"$^$jM-MQ$G$"$k$H$O8@$($J$$!%$b$&(B | |
160 $B>/$79~$_F~$C$?%F%s%W%l!<%H$r;n$=$&!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
161 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
162 \interaction{template.simple.simplesub} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
163 |
360 | 164 %As you can see, the string ``\Verb+{desc}+'' in the template has been |
165 %replaced in the output with the description of each changeset. Every | |
166 %time Mercurial finds text enclosed in curly braces (``\texttt{\{}'' | |
167 %and ``\texttt{\}}''), it will try to replace the braces and text with | |
168 %the expansion of whatever is inside. To print a literal curly brace, | |
169 %you must escape it, as described in section~\ref{sec:template:escape}. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
170 |
360 | 171 $B%F%s%W%l!<%HFb$N(B``\Verb+{desc}+''$B$H$$$&J8;zNs$O=PNO$G$O!$3F!9$N%A%'%s%8%;%C(B |
172 $B%H$N@bL@$KCV49$5$l$k!%(BMercurial$B$OCf3g8L(B(``\texttt{\{}''$B$H(B | |
173 ``\texttt{\}}'')$B$G0O$^$l$?%F%-%9%H$r8+$D$1$k$HCf3g8L$H%F%-%9%H$rFbIt$N%F(B | |
174 $B%-%9%H$rE83+$7$?$b$N$KCV49$7$h$&$H;n$_$k!%J8;z$H$7$FCf3g8L$r0u;z$7$?$$>l(B | |
175 $B9g$O(B~\ref{sec:template:escape}$B@a$G<($9$h$&$K%(%9%1!<%W$9$kI,MW$,$"$k!%(B | |
176 | |
177 %\section{Common template keywords} | |
178 \section{$B%F%s%W%l!<%H$N6&DL%-!<%o!<%I(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
179 \label{sec:template:keyword} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
180 |
360 | 181 %You can start writing simple templates immediately using the keywords |
182 %below. | |
183 | |
184 $BC1=c$J%F%s%W%l!<%H$O0J2<$N$h$&$J%-!<%o!<%I$r;H$C$FD>$A$K=q$/$3$H$,$G$-$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
185 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
186 \begin{itemize} |
360 | 187 %\item[\tplkword{author}] String. The unmodified author of the changeset. |
188 \item[\tplkword{author}] $BJ8;zNs!%%A%'%s%8%;%C%H$NCx<T$,$=$N$b$N!%(B | |
189 %\item[\tplkword{branches}] String. The name of the branch on which | |
190 % the changeset was committed. Will be empty if the branch name was | |
191 % \texttt{default}. | |
192 \item[\tplkword{branches}] $BJ8;zNs!%%A%'%s%8%;%C%H$,%3%_%C%H$5$l$?%V%i%s(B | |
193 $B%A$NL>A0!%%V%i%s%AL>$,(B\texttt{default}$B$N>l9g$O(B | |
194 $B6uMs$H$J$k!%(B | |
195 %\item[\tplkword{date}] Date information. The date when the changeset | |
196 % was committed. This is \emph{not} human-readable; you must pass it | |
197 % through a filter that will render it appropriately. See | |
198 % section~\ref{sec:template:filter} for more information on filters. | |
199 % The date is expressed as a pair of numbers. The first number is a | |
200 % Unix UTC timestamp (seconds since January 1, 1970); the second is | |
201 % the offset of the committer's timezone from UTC, in seconds. | |
202 \item[\tplkword{date}] $BF|;~>pJs!%%A%'%s%8%;%C%H$,%3%_%C%H$5$l$?F|;~!%$3$l(B | |
203 $B$O?M4V$N2DFI$J7A<0$G$O(B\emph{$B$J$$(B}$B!%I,$:E,@Z$J%U%#(B | |
204 $B%k%?$r8F$S=P$7$FJQ49$9$kI,MW$,$"$k!%%U%#%k%?$K4X(B | |
205 $B$9$k$h$j>\:Y$J@bL@$O(B~\ref{sec:template:filter} | |
206 $B@a$r;2>H$N$3$H!%F|;~$O(B2$B$D$N?t;z$NAH$_9g$o$;$GI=(B | |
207 $B$5$l$k!%:G=i$N?t;z$O(BUTC$B$G$N(BUnix$B%?%$%`%9%?%s%W(B | |
208 (1970$BG/(B1$B7n(B1$BF|$+$i$NIC?t(B)$B$G!$(B2$BHVL\$N?t;z$O%3%_%C(B | |
209 $B%?$N%?%$%`%>!<%s$N(BUTC$B$+$i$N;~:9$rIC?t$GI=$7$?$b(B | |
210 $B$N$G$"$k!%(B | |
211 %\item[\tplkword{desc}] String. The text of the changeset description. | |
212 \item[\tplkword{desc}] $BJ8;zNs!%%A%'%s%8%;%C%H$N@bL@J8!%(B | |
213 | |
214 %\item[\tplkword{files}] List of strings. All files modified, added, or | |
215 % removed by this changeset. | |
216 \item[\tplkword{files}] $BJ8;zNs$N%j%9%H!%$3$N%A%'%s%8%;%C%H$GJQ99!$DI2C!$(B | |
217 $B:o=|$5$l$?A4$F$N%U%!%$%k$NL>A0!%(B | |
218 | |
219 %\item[\tplkword{file\_adds}] List of strings. Files added by this | |
220 % changeset. | |
221 \item[\tplkword{file\_adds}] $BJ8;zNs$N%j%9%H!%$3$N%A%'%s%8%;%C%H$GDI2C$5(B | |
222 $B$l$?%U%!%$%k$NL>A0!%(B | |
223 | |
224 %\item[\tplkword{file\_dels}] List of strings. Files removed by this | |
225 % changeset. | |
226 \item[\tplkword{file\_dels}] $BJ8;zNs$N%j%9%H!%$3$N%A%'%s%8%;%C%H$G:o=|$5(B | |
227 $B$l$?%U%!%$%k$NL>A0!%(B | |
228 | |
229 %\item[\tplkword{node}] String. The changeset identification hash, as a | |
230 % 40-character hexadecimal string. | |
231 \item[\tplkword{node}] $BJ8;zNs!%%A%'%s%8%;%C%H$N<1JL%O%C%7%e$r(B40$BJ8;z$N(B16 | |
232 $B?J?t$G<($7$?$b$N!%(B | |
233 | |
234 %\item[\tplkword{parents}] List of strings. The parents of the | |
235 % changeset. | |
236 \item[\tplkword{parents}] $BJ8;zNs$N%j%9%H!%%A%'%s%8%;%C%H$N?F!%(B | |
237 | |
238 %\item[\tplkword{rev}] Integer. The repository-local changeset revision | |
239 % number. | |
240 \item[\tplkword{rev}] $B@0?t!%%j%]%8%H%j%m!<%+%k$N%A%'%s%8%;%C%H%j%S%8%g%s(B | |
241 $BHV9f!%(B | |
242 | |
243 %\item[\tplkword{tags}] List of strings. Any tags associated with the | |
244 % changeset. | |
245 \item[\tplkword{tags}] $BJ8;zNs$N%j%9%H!%%A%'%s%8%;%C%H$K4XO"$E$1$i$l$?G$(B | |
246 $B0U$N%?%0!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
247 \end{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
248 |
360 | 249 %A few simple experiments will show us what to expect when we use these |
250 %keywords; you can see the results in | |
251 %figure~\ref{fig:template:keywords}. | |
252 | |
253 $B$$$/$D$+;n$7$F$_$l$P$3$l$i$N%-!<%o!<%I$K$I$N$h$&$J8z2L$,$"$k$N$+$rCN$k$3(B | |
254 $B$H$,$G$-$k!%7k2L$r?^(B~\ref{fig:template:keywords}$B$K<($9!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
255 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
256 \begin{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
257 \interaction{template.simple.keywords} |
360 | 258 % \caption{Template keywords in use} |
259 \caption{$B%F%s%W%l!<%H%-!<%o!<%I$N;HMQ(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
260 \label{fig:template:keywords} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
261 \end{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
262 |
360 | 263 %As we noted above, the date keyword does not produce human-readable |
264 %output, so we must treat it specially. This involves using a | |
265 %\emph{filter}, about which more in section~\ref{sec:template:filter}. | |
266 | |
267 $B4{$K=R$Y$?$h$&$K!$(Bdate$B%-!<%o!<%I$O2DFI$J=PNO$r9T$o$J$$$?$a!$FCJL$J<h$j07(B | |
268 $B$$$,I,MW$G$"$k!%$=$NL\E*$G(B\emph{filter}$B$r;HMQ$9$k$,!$$h$j>\:Y$K(B | |
269 $B$O(B~\ref{sec:template:filter}$B@a$G<h$j07$&!%(B | |
80
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 \interaction{template.simple.datekeyword} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
272 |
360 | 273 %\section{Escape sequences} |
274 \section{$B%(%9%1!<%W%7!<%1%s%9(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
275 \label{sec:template:escape} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
276 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
277 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
|
278 sequences in strings. When it sees a backslash (``\Verb+\+'') |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
279 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
|
280 characters with a single replacement, as described below. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
281 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
282 \begin{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
283 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'', |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
284 ASCII~134. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
285 \item[\Verb+\textbackslash n+] Newline, ASCII~12. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
286 \item[\Verb+\textbackslash r+] Carriage return, ASCII~15. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
287 \item[\Verb+\textbackslash t+] Tab, ASCII~11. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
288 \item[\Verb+\textbackslash v+] Vertical tab, ASCII~13. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
289 \item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
290 \item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
291 \end{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
292 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
293 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
|
294 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
295 must escape it. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
296 |
360 | 297 %\section{Filtering keywords to change their results} |
298 \section{$B7k2L$r2~JQ$9$k%U%#%k%?%-!<%o!<%I(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
299 \label{sec:template:filter} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
300 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
301 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
|
302 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
|
303 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
|
304 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
|
305 date readable. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
306 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
307 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
|
308 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
|
309 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
|
310 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
|
311 description of its effect. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
312 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
313 \begin{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
314 \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
|
315 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
|
316 ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
317 \item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
318 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
|
319 ``\Verb+10 minutes+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
320 \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
|
321 \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
|
322 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
|
323 becomes ``\Verb+baz+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
324 \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
|
325 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
|
326 timezone included. Yields a string like |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
327 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
328 \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
|
329 \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
|
330 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
|
331 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
332 ``\Verb+serpentine.com+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
333 \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
|
334 \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
|
335 an email address. For example, |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
336 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
337 ``\Verb+bos@serpentine.com+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
338 \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
|
339 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
340 XML entities. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
341 \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
|
342 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
|
343 \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
|
344 80-column fixed-font window. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
345 \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
|
346 columns. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
347 \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
|
348 without any trailing newlines. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
349 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
350 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
|
351 ``\Verb+1157407993 25200+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
352 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
353 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
|
354 ``\Verb+2006-09-04 15:13:13 -0700+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
355 \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
|
356 \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
|
357 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
|
358 stupid screen-scraping email harvesting spambots. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
359 \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
|
360 \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
|
361 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
362 becomes ``\Verb+Bryan O'Sullivan+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
363 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
364 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
|
365 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
|
366 \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
|
367 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
|
368 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
369 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
|
370 ``\Verb+2006-09-04+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
371 \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
|
372 whitespace from the string. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
373 \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
|
374 except the first starting with a tab character. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
375 \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
|
376 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
|
377 becomes \Verb+foo%20bar+. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
378 \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
|
379 \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
|
380 address. For example, |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
381 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
382 ``\Verb+bos+''. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
383 \end{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
384 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
385 \begin{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
386 \interaction{template.simple.manyfilters} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
387 \caption{Template filters in action} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
388 \label{fig:template:filters} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
389 \end{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
390 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
391 \begin{note} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
392 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
|
393 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
|
394 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
|
395 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
|
396 \end{note} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
397 |
360 | 398 %\subsection{Combining filters} |
399 \subsection{$BAH$_9g$o$;%U%#%k%?(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
400 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
401 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
|
402 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
|
403 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
|
404 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
|
405 conventionally 8~characters wide). |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
406 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
407 \interaction{template.simple.combine} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
408 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
409 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
|
410 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
|
411 \tplkword{tabindent} indents all lines \emph{except} the first. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
412 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
413 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
|
414 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
|
415 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
|
416 \Verb+fill68|tabindent+ gives very different results from |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
417 \Verb+tabindent|fill68+. |
76
df88df78288d
Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
418 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
419 |
360 | 420 %\section{From templates to styles} |
421 \section{$B%F%s%W%l!<%H$+$i%9%?%$%k$X(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
422 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
423 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
|
424 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
|
425 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
|
426 name, stored in a file. |
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 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
|
429 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
|
430 \hgopt{log}{--template} option. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
431 |
360 | 432 %\subsection{The simplest of style files} |
433 \subsection{$B:G$bC1=c$J%9%?%$%k%U%!%$%k(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
434 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
435 Our simple style file contains just one line: |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
436 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
437 \interaction{template.simple.rev} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
438 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
439 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
|
440 on the right as the template''. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
441 |
360 | 442 %\subsection{Style file syntax} |
443 \subsection{$B%9%?%$%k%U%!%$%k$NJ8K!(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
444 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
445 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
|
446 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
447 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
448 \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
|
449 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
450 \item Leading and trailing white space are ignored. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
451 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
452 \item Empty lines are skipped. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
453 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
454 \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
|
455 ``\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
|
456 as if empty. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
457 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
458 \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
|
459 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
|
460 alphanumeric character or underscore. (In regexp notation, a |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
461 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
|
462 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
463 \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
|
464 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
|
465 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
466 \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
|
467 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
|
468 template body. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
469 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
470 \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
|
471 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
|
472 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
|
473 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
474 |
360 | 475 %\section{Style files by example} |
476 \section{$B%9%?%$%k%U%!%$%k$NNc(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
477 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
478 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
|
479 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
|
480 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
|
481 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
|
482 successively more complete examples. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
483 |
360 | 484 %\subsection{Identifying mistakes in style files} |
485 \subsection{$B%9%?%$%k%U%!%$%k$G$N8m$j$rFCDj$9$k(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
486 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
487 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
|
488 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
|
489 means, is actually quite useful. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
490 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
491 \interaction{template.svnstyle.syntax.input} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
492 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
493 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
|
494 \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
|
495 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
|
496 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
497 \interaction{template.svnstyle.syntax.error} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
498 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
499 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
|
500 follow. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
501 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
502 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
503 \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
|
504 giving up''. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
505 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
506 \textbf{abort:} broken.style:1: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
507 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
508 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
509 \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
|
510 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
511 abort: \textbf{broken.style}:1: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
512 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
513 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
514 \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
|
515 encountered. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
516 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
517 abort: broken.style:\textbf{1}: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
518 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
519 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
520 \item Finally, a description of what went wrong. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
521 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
522 abort: broken.style:1: \textbf{parse error} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
523 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
524 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
|
525 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
|
526 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
|
527 is wrong. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
528 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
529 |
360 | 530 %\subsection{Uniquely identifying a repository} |
531 \subsection{$B%j%]%8%H%j$NFCDj(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
532 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
533 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
|
534 ``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
|
535 use the first revision in the repository. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
536 \interaction{template.svnstyle.id} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
537 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
|
538 many cases. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
539 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
540 \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
|
541 a repository does not have a revision~zero. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
542 \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
|
543 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
|
544 repositories, and you still have those repositories around. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
545 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
546 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
|
547 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
548 \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
|
549 on a server. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
550 \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
|
551 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
|
552 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
|
553 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
554 |
360 | 555 %\subsection{Mimicking Subversion's output} |
556 \subsection{Subversion$B=PNO$NLOJo(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
557 |
360 | 558 %Let's try to emulate the default output format used by another |
559 %revision control tool, Subversion. | |
560 %\interaction{template.svnstyle.short} | |
561 | |
562 $BJL$N%P!<%8%g%s4IM}%D!<%k$G$"$k(BSubversion$B$N=PNO$r%(%_%e%l!<%H$7$F$_$h$&!%(B | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
563 \interaction{template.svnstyle.short} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
564 |
360 | 565 %Since Subversion's output style is fairly simple, it is easy to |
566 %copy-and-paste a hunk of its output into a file, and replace the text | |
567 %produced above by Subversion with the template values we'd like to see | |
568 %expanded. | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
569 |
360 | 570 Subversion$B$N=PNO%9%?%$%k$O$+$J$jC1=c$J$N$G!$=PNO$+$i%U%!%$%k$X(Bhunk$B$r%3%T!<(B |
571 $B!u%Z!<%9%H$7!$(BSubversion$B$,@8@.$7$?%F%-%9%H$r%F%s%W%l!<%H$K$h$C$FCV49$9$k(B | |
572 $B$N$O4JC1$G$"$k!%(B \interaction{template.svnstyle.template} | |
573 | |
574 %There are a few small ways in which this template deviates from the | |
575 %output produced by Subversion. | |
576 | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
577 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
578 \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
|
579 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
|
580 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
|
581 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
|
582 \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
|
583 ``\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
|
584 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
|
585 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
|
586 achieving similar output to Subversion. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
587 \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
|
588 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
|
589 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
|
590 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
|
591 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
592 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
|
593 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
|
594 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
|
595 the template. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
596 \interaction{template.svnstyle.style} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
597 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
598 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
|
599 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
|
600 ``\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
|
601 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
|
602 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
|
603 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
|
604 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
|
605 template instead. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
606 |
360 | 607 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
608 %%% mode: yatex |
76
df88df78288d
Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
609 %%% TeX-master: "00book" |
360 | 610 %%% End: |