Mercurial > hgbook
annotate ja/template.tex @ 361:96437101a088
more template.tex
author | Yoshiki Yazawa <yaz@honeyplanet.jp> |
---|---|
date | Mon, 22 Sep 2008 22:48:57 +0900 |
parents | 45ad9986748a |
children | df4ac9043db0 |
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 | |
361 | 67 Mercurial$B$NA4$F$N%3%^%s%I$GMQ$$$i$l$k=PNO%9%?%$%k$O(B \hgrc $B%U%!%$%k$rJT=8(B |
68 $B$9$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 |
361 | 277 %Mercurial's templating engine recognises the most commonly used escape |
278 %sequences in strings. When it sees a backslash (``\Verb+\+'') | |
279 %character, it looks at the following character and substitutes the two | |
280 %characters with a single replacement, as described below. | |
281 | |
282 Mercurial$B$N%F%s%W%l!<%H%(%s%8%s$OJ8;zNs$G:G$b$h$/;HMQ$5$l$k%(%9%1!<%W%7!<(B | |
283 $B%1%s%9$rG'<1$9$k!%%(%s%8%s$O%P%C%/%9%i%C%7%e(B(``\Verb+\+'')$B$r8+$D$1$k$H8e(B | |
284 $BB3$NJ8;z$r4^$`(B2$BJ8;z$r0J2<$N$h$&$J(B1$BJ8;z$GCV49$9$k!%(B | |
80
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 \begin{itemize} |
361 | 287 %\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'', |
288 % ASCII~134. | |
289 %\item[\Verb+\textbackslash n+] Newline, ASCII~12. | |
290 %\item[\Verb+\textbackslash r+] Carriage return, ASCII~15. | |
291 %\item[\Verb+\textbackslash t+] Tab, ASCII~11. | |
292 %\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13. | |
293 %\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173. | |
294 %\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175. | |
295 \item[\Verb+\textbackslash\textbackslash+] $B%P%C%/%9%i%C%7%e(B, ``\Verb+\+'', | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
296 ASCII~134. |
361 | 297 \item[\Verb+\textbackslash n+] $B2~9T(B, ASCII~12. |
298 \item[\Verb+\textbackslash r+] $BI|5"(B, ASCII~15. | |
299 \item[\Verb+\textbackslash t+] $B%?%V(B, ASCII~11. | |
300 \item[\Verb+\textbackslash v+] $B?bD>%?%V(B, ASCII~13. | |
301 \item[\Verb+\textbackslash \{+] $B3+$-Cf3g8L(B, ``\Verb+{+'', ASCII~173. | |
302 \item[\Verb+\textbackslash \}+] $BJD$8Cf3g8L(B, ``\Verb+}+'', ASCII~175. | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
303 \end{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
304 |
361 | 305 %As indicated above, if you want the expansion of a template to contain |
306 %a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you | |
307 %must escape it. | |
308 | |
309 $B>e$K<($7$?$h$&$K!$%F%s%W%l!<%H$NE83+$N:]$KJ8;z(B | |
310 ``\Verb+\+'', ``\Verb+{+'', $B$^$?$O(B``\Verb+{+''$B$rF~$l$?$$>l9g$O%(%9%1!<%W(B | |
311 $B$9$k$3$H$,I,MW$G$"$k!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
312 |
360 | 313 %\section{Filtering keywords to change their results} |
314 \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
|
315 \label{sec:template:filter} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
316 |
361 | 317 %Some of the results of template expansion are not immediately easy to |
318 %use. Mercurial lets you specify an optional chain of \emph{filters} | |
319 %to modify the result of expanding a keyword. You have already seen a | |
320 %common filter, \tplkwfilt{date}{isodate}, in action above, to make a | |
321 %date readable. | |
322 | |
323 $B%F%s%W%l!<%HE83+$N7k2L$N$&$A!$$$$/$D$+$O$?$d$9$/MxMQ$G$-$k$b$N$G$O$J$$!%(B | |
324 Mercurial$B$OE83+$5$l$k%-!<%o!<%I$rJQ99$9$k$?$a$N0lO"$N(B\emph{filters}$B%*%W%7%g(B | |
325 $B%s$rDs6!$7$F$$$k!%F|;~$r2DFI$K$9$k$?$a$K$h$/MQ$$$i$l$k(B | |
326 \tplkwfilt{date}{isodate}$B%U%#%k%?$NF0:nNc$K$D$$$F$O4{$K8+$F$-$?!%(B | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
327 |
361 | 328 %Below is a list of the most commonly used filters that Mercurial |
329 %supports. While some filters can be applied to any text, others can | |
330 %only be used in specific circumstances. The name of each filter is | |
331 %followed first by an indication of where it can be used, then a | |
332 %description of its effect. | |
333 | |
334 $B0J2<$K<($9$N$O(BMercurial$B$,%5%]!<%H$9$k%U%#%k%?$NCf$G:G$b$h$/;H$o$l$k$b$N$G(B | |
335 $B$"$k!%$$$/$D$+$N%U%#%k%?$OG$0U$NJ8;zNs$KBP$7$FE,MQ2DG=$J0lJ}!$B>$N$b$N$O(B | |
336 $BFCDj$N>u67$K$*$$$F$N$_MxMQ2DG=$G$"$k!%3F!9$N%U%#%k%?$NL>A0$O!$MxMQ2DG=$J(B | |
337 $B>u67$r<($9I=<($G;O$^$j!$F@$i$l$k8z2L$N@bL@$,B3$/!%(B | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
338 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
339 \begin{itemize} |
361 | 340 %\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+'' |
341 % tag before the end of every line except the last. For example, | |
342 % ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''. | |
343 | |
344 \item[\tplfilter{addbreaks}] $BG$0U$N%F%-%9%H!%(BXHTML$B%?%0(B``\Verb+<br/>+'' | |
345 $B$r:G=*9T0J30$N3F9T$NKvHx$KDI2C$9$k!%Nc$($P(B``\Verb+foo\nbar+''$B$O(B | |
346 ``\Verb+foo<br/>\nbar+''$B$H$J$k!%(B | |
347 | |
348 %\item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the | |
349 % age of the date, relative to the current time. Yields a string like | |
350 % ``\Verb+10 minutes+''. | |
351 | |
352 \item[\tplkwfilt{date}{age}] \tplkword{date}$B%-!<%o!<%I!%F|;~$N7P2a;~4V$r(B | |
353 $B8=:_$r5/E@$K@07A$9$k!%7k2L$O(B | |
354 ``\Verb+10 minutes+''$B$N$h$&$K$J$k(B | |
355 | |
356 %\item[\tplfilter{basename}] Any text, but most useful for the | |
357 % \tplkword{files} keyword and its relatives. Treat the text as a | |
358 % path, and return the basename. For example, ``\Verb+foo/bar/baz+'' | |
359 % becomes ``\Verb+baz+''. | |
360 | |
361 \item[\tplfilter{basename}] $BG$0U$N%F%-%9%H$@$,!$(B\tplkword{files}$B%-!<%o!<(B | |
362 $B%I$d$=$N4XO"%-!<%o!<%I$KBP$7$F:G$bM-MQ$G$"(B | |
363 $B$k!%%F%-%9%H$r%Q%9$H$7$F07$$!$%Y!<%9%M!<%`$r(B | |
364 $BJV$9!%Nc$($P(B``\Verb+foo/bar/baz+''$B$O(B | |
365 ``\Verb+baz+''$B$H$J$k!%(B | |
366 | |
367 %\item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date | |
368 % in a similar format to the Unix \tplkword{date} command, but with | |
369 % timezone included. Yields a string like | |
370 % ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''. | |
371 | |
372 \item[\tplkwfilt{date}{date}] \tplkword{date}$B%-!<%o!<%I!%F|;~$r(BUnix$B$N(B | |
373 \tplkword{date}$B%3%^%s%I$N=PNO$K%?%$%`%>!<%s(B | |
374 $B>pJs$rDI2C$7$?7A<0$K@07A$9$k!%7k2L$O(B | |
375 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''$B$N(B | |
376 $B$h$&$K$J$k!%(B | |
377 | |
378 %\item[\tplkwfilt{author}{domain}] Any text, but most useful for the | |
379 % \tplkword{author} keyword. Finds the first string that looks like | |
380 % an email address, and extract just the domain component. For | |
381 % example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes | |
382 % ``\Verb+serpentine.com+''. | |
383 | |
384 \item[\tplkwfilt{author}{domain}] $BG$0U$N%F%-%9%H!%(B\tplkword{author}$B%-!<%o!<(B | |
385 $B%I$G$N;HMQ$K:G$bM-MQ!%:G=i$K8=$l$k(Bemail$B%"%I(B | |
386 $B%l%97A<0$NJ8;zNs$r8+$D$1!$%I%a%$%sItJ,$@$1$r(B | |
387 $BH4$-=P$9!%Nc$($P(B | |
388 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' | |
389 $B$O(B``\Verb+serpentine.com+''$B$H$J$k!%(B | |
390 | |
391 %\item[\tplkwfilt{author}{email}] Any text, but most useful for the | |
392 % \tplkword{author} keyword. Extract the first string that looks like | |
393 % an email address. For example, | |
394 % ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes | |
395 % ``\Verb+bos@serpentine.com+''. | |
396 | |
397 \item[\tplkwfilt{author}{email}] $BG$0U$N%F%-%9%H!%(B\tplkword{author}$B%-!<%o!<(B | |
398 $B%I$G:G$bM-MQ!%:G=i$K8=$l$k(Bemail$B%"%I%l%97A<0(B | |
399 $B$NJ8;zNs$rH4$-=P$9!%Nc$($P(B | |
400 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' | |
401 $B$O(B``\Verb+bos@serpentine.com+''$B$H$J$k!%(B | |
402 | |
403 %\item[\tplfilter{escape}] Any text. Replace the special XML/XHTML | |
404 % characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with | |
405 % XML entities. | |
406 | |
407 \item[\tplfilter{escape}] $BG$0U$N%F%-%9%H!%(BXML/XHTML$BJ8;z(B | |
408 ``\Verb+&+'', ``\Verb+<+''$B$*$h$S(B | |
409 ``\Verb+>+''$B$r(BXML$B%(%s%F%#%F%#$GCV49$9$k!%(B | |
410 | |
411 %\item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68 | |
412 % columns. This is useful before you pass text through the | |
413 % \tplfilter{tabindent} filter, and still want it to fit in an | |
414 % 80-column fixed-font window. | |
415 | |
416 \item[\tplfilter{fill68}] $BG$0U$N%F%-%9%H!%%F%-%9%H$r(B68$B7e$K<}$^$k$h$&$K@0(B | |
417 $B7A$9$k!%$3$l$O(B80$B7e$K8GDj$5$l$?C<Kv$G$NI=<(MQ(B | |
418 $B$K(B\tplfilter{tabindent}$B%U%#%k%?$r;H$&:]$KJX(B | |
419 $BMx$G$"$k!%(B | |
420 | |
421 %\item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76 | |
422 % columns. | |
423 | |
424 \item[\tplfilter{fill76}] $BG$0U$N%F%-%9%H!%(B76$B7e$K<}$^$k$h$&$K@07A$9$k!%(B | |
425 | |
426 %\item[\tplfilter{firstline}] Any text. Yield the first line of text, | |
427 % without any trailing newlines. | |
428 | |
429 \item[\tplfilter{firstline}] $BG$0U$N%F%-%9%H:G=i$N9T$@$1$r=PNO$7!$8eB3$N(B | |
430 $B9T$O0l@Z=PNO$7$J$$!%(B | |
431 | |
432 %\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the | |
433 % date as a pair of readable numbers. Yields a string like | |
434 % ``\Verb+1157407993 25200+''. | |
435 | |
436 \item[\tplkwfilt{date}{hgdate}] \tplkword{date}$B%-!<%o!<%I!%F|;~$r2DFI$J(B | |
437 $B?t;z$N%Z%"$K@07A$9$k!%(B``\Verb+115740799325200+''$B$N$h$&$JJ8;zNs$r=PNO$9$k!%(B | |
438 | |
439 %\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the | |
440 % date as a text string in ISO~8601 format. Yields a string like | |
441 % ``\Verb+2006-09-04 15:13:13 -0700+''. | |
442 | |
443 \item[\tplkwfilt{date}{isodate}] \tplkword{date}$B%-!<%o!<%I!%F|;~$r(B | |
444 ISO~8601$B%U%)!<%^%C%H$K@07A$9$k!%=PNO$O(B | |
445 ``\Verb+2006-09-04 15:13:13 -0700+''$B$N$h$&$K(B | |
446 $B$J$k!%(B | |
447 | |
448 %\item[\tplfilter{obfuscate}] Any text, but most useful for the | |
449 % \tplkword{author} keyword. Yield the input text rendered as a | |
450 % sequence of XML entities. This helps to defeat some particularly | |
451 % stupid screen-scraping email harvesting spambots. | |
452 | |
453 \item[\tplfilter{obfuscate}]$BG$0U$N%F%-%9%H!%(B\tplkword{author}$B%-!<%o!<%I$H(B | |
454 $BJ;$;$FMxMQ$9$k>l9g:G$bM-MQ!%F~NO$5$l$?%F%-%9(B | |
455 $B%H$r(BXML$B%(%s%F%#%F%#$N%7!<%1%s%9$H$7$F=PNO$9(B | |
456 $B$k!%$3$l$O2hLL$r%9%/%l%$%T%s%0$9$k4VH4$1$J%9(B | |
457 $B%Q%`%\%C%H$rHr$1$kF/$-$,$"$k!%(B | |
458 | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
459 \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
|
460 \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
|
461 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
462 becomes ``\Verb+Bryan O'Sullivan+''. |
361 | 463 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
464 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
465 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
|
466 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''. |
361 | 467 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
468 \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
|
469 of a changeset hash, i.e.~a 12-byte hexadecimal string. |
361 | 470 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
471 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
472 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
|
473 ``\Verb+2006-09-04+''. |
361 | 474 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
475 \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
|
476 whitespace from the string. |
361 | 477 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
478 \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
|
479 except the first starting with a tab character. |
361 | 480 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
481 \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
|
482 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
|
483 becomes \Verb+foo%20bar+. |
361 | 484 |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
485 \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
|
486 \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
|
487 address. For example, |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
488 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
489 ``\Verb+bos+''. |
361 | 490 |
491 | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
492 \end{itemize} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
493 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
494 \begin{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
495 \interaction{template.simple.manyfilters} |
361 | 496 % \caption{Template filters in action} |
497 \caption{$B%F%s%W%l!<%H%U%#%k%?$NF0:n(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
498 \label{fig:template:filters} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
499 \end{figure} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
500 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
501 \begin{note} |
361 | 502 % If you try to apply a filter to a piece of data that it cannot |
503 % process, Mercurial will fail and print a Python exception. For | |
504 % example, trying to run the output of the \tplkword{desc} keyword | |
505 % into the \tplkwfilt{date}{isodate} filter is not a good idea. | |
506 $B%U%#%k%?$rE,MQITG=$J%G!<%?$KBP$7$F;H$*$&$H$9$k$H(BMercurial$B$O%(%i!<$r5/$3(B | |
507 $B$7!$(BPython$B$+$i$NNc30$r=PNO$9$k!%Nc$($P(B\tplkword{desc}$B%-!<%o!<%I$N=PNO$K(B | |
508 \tplkwfilt{date}{isodate}$B%U%#%k%?$rE,MQ$9$k$N$O$$$$9M$($H$O8@$($J$$!%(B | |
509 | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
510 \end{note} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
511 |
360 | 512 %\subsection{Combining filters} |
513 \subsection{$BAH$_9g$o$;%U%#%k%?(B} | |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
514 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
515 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
|
516 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
|
517 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
|
518 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
|
519 conventionally 8~characters wide). |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
520 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
521 \interaction{template.simple.combine} |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
522 |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
523 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
|
524 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
|
525 \tplkword{tabindent} indents all lines \emph{except} the first. |
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
526 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
527 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
|
528 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
|
529 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
|
530 \Verb+fill68|tabindent+ gives very different results from |
80
ea951cfb5cd9
Much template-related content.
Bryan O'Sullivan <bos@serpentine.com>
parents:
76
diff
changeset
|
531 \Verb+tabindent|fill68+. |
76
df88df78288d
Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
532 |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
533 |
360 | 534 %\section{From templates to styles} |
535 \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
|
536 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
537 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
|
538 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
|
539 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
|
540 name, stored in a file. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
541 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
542 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
|
543 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
|
544 \hgopt{log}{--template} option. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
545 |
360 | 546 %\subsection{The simplest of style files} |
547 \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
|
548 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
549 Our simple style file contains just one line: |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
550 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
551 \interaction{template.simple.rev} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
552 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
553 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
|
554 on the right as the template''. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
555 |
360 | 556 %\subsection{Style file syntax} |
557 \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
|
558 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
559 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
|
560 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
561 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
562 \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
|
563 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
564 \item Leading and trailing white space are ignored. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
565 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
566 \item Empty lines are skipped. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
567 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
568 \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
|
569 ``\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
|
570 as if empty. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
571 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
572 \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
|
573 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
|
574 alphanumeric character or underscore. (In regexp notation, a |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
575 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
|
576 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
577 \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
|
578 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
|
579 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
580 \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
|
581 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
|
582 template body. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
583 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
584 \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
|
585 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
|
586 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
|
587 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
588 |
360 | 589 %\section{Style files by example} |
590 \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
|
591 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
592 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
|
593 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
|
594 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
|
595 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
|
596 successively more complete examples. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
597 |
360 | 598 %\subsection{Identifying mistakes in style files} |
599 \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
|
600 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
601 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
|
602 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
|
603 means, is actually quite useful. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
604 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
605 \interaction{template.svnstyle.syntax.input} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
606 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
607 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
|
608 \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
|
609 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
|
610 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
611 \interaction{template.svnstyle.syntax.error} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
612 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
613 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
|
614 follow. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
615 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
616 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
617 \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
|
618 giving up''. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
619 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
620 \textbf{abort:} broken.style:1: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
621 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
622 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
623 \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
|
624 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
625 abort: \textbf{broken.style}:1: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
626 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
627 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
628 \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
|
629 encountered. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
630 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
631 abort: broken.style:\textbf{1}: parse error |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
632 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
633 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
634 \item Finally, a description of what went wrong. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
635 \begin{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
636 abort: broken.style:1: \textbf{parse error} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
637 \end{codesample4} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
638 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
|
639 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
|
640 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
|
641 is wrong. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
642 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
643 |
360 | 644 %\subsection{Uniquely identifying a repository} |
645 \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
|
646 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
647 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
|
648 ``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
|
649 use the first revision in the repository. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
650 \interaction{template.svnstyle.id} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
651 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
|
652 many cases. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
653 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
654 \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
|
655 a repository does not have a revision~zero. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
656 \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
|
657 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
|
658 repositories, and you still have those repositories around. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
659 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
660 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
|
661 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
662 \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
|
663 on a server. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
664 \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
|
665 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
|
666 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
|
667 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
668 |
360 | 669 %\subsection{Mimicking Subversion's output} |
670 \subsection{Subversion$B=PNO$NLOJo(B} | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
671 |
360 | 672 %Let's try to emulate the default output format used by another |
673 %revision control tool, Subversion. | |
674 %\interaction{template.svnstyle.short} | |
675 | |
676 $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
|
677 \interaction{template.svnstyle.short} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
678 |
360 | 679 %Since Subversion's output style is fairly simple, it is easy to |
680 %copy-and-paste a hunk of its output into a file, and replace the text | |
681 %produced above by Subversion with the template values we'd like to see | |
682 %expanded. | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
683 |
360 | 684 Subversion$B$N=PNO%9%?%$%k$O$+$J$jC1=c$J$N$G!$=PNO$+$i%U%!%$%k$X(Bhunk$B$r%3%T!<(B |
685 $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 | |
686 $B$N$O4JC1$G$"$k!%(B \interaction{template.svnstyle.template} | |
687 | |
688 %There are a few small ways in which this template deviates from the | |
689 %output produced by Subversion. | |
690 | |
83
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
691 \begin{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
692 \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
|
693 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
|
694 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
|
695 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
|
696 \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
|
697 ``\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
|
698 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
|
699 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
|
700 achieving similar output to Subversion. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
701 \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
|
702 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
|
703 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
|
704 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
|
705 \end{itemize} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
706 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
|
707 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
|
708 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
|
709 the template. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
710 \interaction{template.svnstyle.style} |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
711 |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
712 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
|
713 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
|
714 ``\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
|
715 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
|
716 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
|
717 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
|
718 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
|
719 template instead. |
b476081a9c04
Much progress in template chapter.
Bryan O'Sullivan <bos@serpentine.com>
parents:
80
diff
changeset
|
720 |
360 | 721 %%% Local Variables: |
293
3b1291f24c0d
- replaved latex-mode to yatex-mode
Yoshiki Yazawa <yaz@cc.rim.or.jp>
parents:
290
diff
changeset
|
722 %%% mode: yatex |
76
df88df78288d
Add template chapter to build.
Bryan O'Sullivan <bos@serpentine.com>
parents:
diff
changeset
|
723 %%% TeX-master: "00book" |
360 | 724 %%% End: |