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