| rev |
line source |
|
igor@470
|
1 \chapter{Personalizar los mensajes de Mercurial}
|
|
igor@402
|
2 \label{chap:template}
|
|
igor@402
|
3
|
|
igor@470
|
4 Mercurial provee un poderoso mecanismo que permite controlar como
|
|
igor@470
|
5 despliega la información. El mecanismo se basa en plantillas. Puede
|
|
igor@470
|
6 usar plantillas para generar salida específica para una orden
|
|
igor@470
|
7 particular o para especificar la visualización completa de la interfaz
|
|
igor@470
|
8 web embebida.
|
|
igor@470
|
9
|
|
igor@470
|
10 \section{Usar estilos que vienen con Mercurial}
|
|
igor@402
|
11 \label{sec:style}
|
|
igor@402
|
12
|
|
igor@470
|
13 Hay ciertos estilos listos que vienen con Mercurial. Un estilo es
|
|
igor@470
|
14 simplemente una plantilla predeterminada que alguien escribió e
|
|
igor@470
|
15 instaló en un sitio en el cual Mercurial puede encontrarla.
|
|
igor@470
|
16
|
|
igor@470
|
17 Antes de dar un vistazo a los estilos que trae Mercurial, revisemos su
|
|
igor@470
|
18 salida usual.
|
|
igor@402
|
19
|
|
igor@402
|
20 \interaction{template.simple.normal}
|
|
igor@402
|
21
|
|
igor@470
|
22 Es en cierta medida informativa, pero ocupa mucho espacio---cinco
|
|
igor@470
|
23 líneas de salida por cada conjunto de cambios. El estilo
|
|
igor@470
|
24 \texttt{compact} lo reduce a tres líneas, presentadas de forma
|
|
igor@470
|
25 suscinta.
|
|
igor@402
|
26
|
|
igor@402
|
27 \interaction{template.simple.compact}
|
|
igor@402
|
28
|
|
igor@470
|
29 El estilo de la \texttt{bitácora de cambios} vislumbra el poder
|
|
igor@470
|
30 expresivo del sistema de plantillas de Mercurial. Este estilo busca
|
|
igor@470
|
31 seguir los estándares de bitácora de cambios del proyecto
|
|
igor@470
|
32 GNU\cite{web:changelog}.
|
|
igor@402
|
33
|
|
igor@402
|
34 \interaction{template.simple.changelog}
|
|
igor@402
|
35
|
|
igor@470
|
36 No es una sorpresa que el estilo predeterminado de Mercurial se llame
|
|
igor@470
|
37 \texttt{default}\ndt{predeterminado}.
|
|
igor@470
|
38
|
|
igor@470
|
39 \subsection{Especificar un estilo predeterminado}
|
|
igor@470
|
40
|
|
igor@470
|
41 Puede modificar el estilo de presentación que Mercurial usará para
|
|
igor@470
|
42 toda orden vía el fichero \hgrc\, indicando el estilo que prefiere
|
|
igor@470
|
43 usar.
|
|
igor@402
|
44
|
|
igor@402
|
45 \begin{codesample2}
|
|
igor@402
|
46 [ui]
|
|
igor@402
|
47 style = compact
|
|
igor@402
|
48 \end{codesample2}
|
|
igor@402
|
49
|
|
igor@470
|
50 Si escribe un estilo, puede usarlo bien sea proveyendo la ruta a su
|
|
igor@470
|
51 fichero de estilo o copiando su fichero de estilo a un lugar en el
|
|
igor@470
|
52 cual Mercurial pueda encontrarlo(típicamente el subdirectorio
|
|
igor@470
|
53 \texttt{templates} de su directorio de instalación de Mercurial).
|
|
igor@470
|
54
|
|
igor@470
|
55 \section{Órdenes que soportan estilos y plantillas}
|
|
igor@470
|
56
|
|
igor@470
|
57 Todas las órdenes de Mercurial``relacionadas con \texttt{log}'' le
|
|
igor@470
|
58 permiten usar estilos y plantillas: \hgcmd{incoming}, \hgcmd{log},
|
|
igor@470
|
59 \hgcmd{outgoing} y \hgcmd{tip}.
|
|
igor@470
|
60
|
|
igor@470
|
61 Al momento de la escritura del manual estas son las únicas órdenes que
|
|
igor@470
|
62 soportan estilos y plantillas. Dado que son las órdenes más
|
|
igor@470
|
63 importantes que necesitan personalización, no ha habido muchas
|
|
igor@470
|
64 solicitudes desde la comunidad de usuarios de Mercurial para añadir
|
|
igor@470
|
65 soporte de plantillas y estilos a otras órdenes.
|
|
igor@470
|
66
|
|
igor@470
|
67 \section{Cuestiones básicas de plantillas}
|
|
igor@470
|
68
|
|
igor@470
|
69 Una plantilla de Mercurial es sencillamente una pieza de texto.
|
|
igor@470
|
70 Cierta porción nunca cambia, otras partes se \emph{expanden}, o
|
|
igor@470
|
71 reemplazan con texto nuevo cuando es necesario.
|
|
igor@470
|
72
|
|
igor@470
|
73 Antes de continuar, veamos de nuevo un ejemplo sencillo de la salida
|
|
igor@470
|
74 usual de Mercurial:
|
|
igor@402
|
75
|
|
igor@402
|
76 \interaction{template.simple.normal}
|
|
igor@402
|
77
|
|
igor@470
|
78 Ahora, ejecutemos la misma orden, pero usemos una plantilla para
|
|
igor@470
|
79 modificar su salida:
|
|
igor@402
|
80
|
|
igor@402
|
81 \interaction{template.simple.simplest}
|
|
igor@402
|
82
|
|
igor@470
|
83 El ejemplo anterior ilustra la plantilla más sencilla posible; es
|
|
igor@470
|
84 solamente una porción estática de código que se imprime una vez por
|
|
igor@470
|
85 cada conjunto de cambios. La opción \hgopt{log}{--template} de la
|
|
igor@470
|
86 orden \hgcmd{log} indica a Mercurial usar el texto dado como la
|
|
igor@470
|
87 plantilla cuando se imprime cada conjunto de cambios.
|
|
igor@470
|
88
|
|
igor@470
|
89 Observe que la cadena de plantilla anterior termina con el texto
|
|
igor@470
|
90 ``\Verb+\n+''. Es una \emph{secuencia de control}, que le indica a
|
|
igor@470
|
91 Mercurial imprimira una nueva línea al final de cada objeto de la
|
|
igor@470
|
92 plantilla. Si omite esta nueva línea, Mercurial colocará cada pieza
|
|
igor@470
|
93 de salida seguida. Si desea más detalles acerca de secuencias de
|
|
igor@470
|
94 control, vea la sección~\ref{sec:template:escape}.
|
|
igor@470
|
95
|
|
igor@470
|
96 Una plantilla que imprime una cadena fija de texto siempre no es muy
|
|
igor@470
|
97 útil; intentemos algo un poco más complejo.
|
|
igor@402
|
98
|
|
igor@402
|
99 \interaction{template.simple.simplesub}
|
|
igor@402
|
100
|
|
igor@470
|
101 Como puede ver, la cadena ``\Verb+{desc}+'' en la plantilla ha sido
|
|
igor@470
|
102 reemplazada en la salida con la descricipción de cada conjunto de
|
|
igor@470
|
103 cambios. Cada vez que Mercurial encuentra texto encerrado entre
|
|
igor@470
|
104 corchetes(``\texttt{\{}'' y ``\texttt{\}}''), intentará reemplazar los
|
|
igor@470
|
105 corchetes y el texto con la expansión de lo que sea está adentro.
|
|
igor@470
|
106 Para imprimir un corchete de forma literal, debe escaparlo, como se
|
|
igor@470
|
107 describe en la sección~\ref{sec:template:escape}.
|
|
igor@470
|
108
|
|
igor@470
|
109 \section{Palabras claves más comunes en las plantillas}
|
|
igor@402
|
110 \label{sec:template:keyword}
|
|
igor@402
|
111
|
|
igor@470
|
112 Puede empezar a escribir plantillas sencillas rápidamente con las
|
|
igor@470
|
113 palabras claves descritas a continuación:
|
|
igor@470
|
114
|
|
igor@470
|
115 \begin{itemize}
|
|
igor@470
|
116 \item[\tplkword{author}] Cadena. El autor NO modificado del conjunto
|
|
igor@470
|
117 de cambios.
|
|
igor@470
|
118 \item[\tplkword{branches}] Cadena. El nombre de la rama en la cual se
|
|
igor@470
|
119 consignó el conjunto de cambios. Será vacía si el nombre de la rama es
|
|
igor@402
|
120 \texttt{default}.
|
|
igor@470
|
121 \item[\tplkword{date}] Información de fecha. La fecha en la cual se
|
|
igor@470
|
122 consignó el conjunto de cambios. \emph{No} es legible por un
|
|
igor@470
|
123 humano, debe pasarla por un firltro que la desplegará
|
|
igor@470
|
124 apropiadamente. En la sección~\ref{sec:template:filter} hay más
|
|
igor@470
|
125 detalles acerca de filtros. La fecha se expresa como un par de
|
|
igor@470
|
126 números. El primer número corresponde a una marca de tiempo UNIX
|
|
igor@470
|
127 UTC(segundos desde el primero de enero de 1970); la segunda es el
|
|
igor@470
|
128 corrimiento horario de la zona horaria del UTC en la cual se encontraba
|
|
igor@470
|
129 quien hizo la consignación, en segundos.
|
|
igor@470
|
130 \item[\tplkword{desc}] Cadena. La descripción en texto del conjunto
|
|
igor@470
|
131 de cambios.
|
|
igor@470
|
132 \item[\tplkword{files}] Lista de cadenas. Todos los ficheros
|
|
igor@470
|
133 modificados, adicionados o eliminados por este conjunto de cambios.
|
|
igor@470
|
134 \item[\tplkword{file\_adds}] Lista de cadenas. Ficheros adicionados
|
|
igor@470
|
135 por este conjunto de cambios.
|
|
igor@470
|
136 \item[\tplkword{file\_dels}] Lista de cadenas. Ficheros eliminados
|
|
igor@470
|
137 por este conjunto de cambios.
|
|
igor@470
|
138 \item[\tplkword{node}] Cadena. El hash de identificación de este
|
|
igor@470
|
139 conjunto de cambios como una cadena hexadecimal de 40 caracteres.
|
|
igor@470
|
140 \item[\tplkword{parents}] Lista de cadenas. Los ancestros del
|
|
igor@470
|
141 conjunto de cambios.
|
|
igor@470
|
142 \item[\tplkword{rev}] Entero. El número de revisión del repositorio
|
|
igor@470
|
143 local.
|
|
igor@470
|
144 \item[\tplkword{tags}] Lista de cadenas. Todas las etiquetas
|
|
igor@470
|
145 asociadas al conjunto de cambios.
|
|
igor@470
|
146 \end{itemize}
|
|
igor@470
|
147
|
|
igor@470
|
148 Unos experimentos sencillos nos mostrarán qué esperar cuando usamos
|
|
igor@470
|
149 estas palabras claves; puede ver los resultados en la
|
|
igor@470
|
150 figura~\ref{fig:template:keywords}.
|
|
igor@402
|
151
|
|
igor@402
|
152 \begin{figure}
|
|
igor@402
|
153 \interaction{template.simple.keywords}
|
|
igor@402
|
154 \caption{Template keywords in use}
|
|
igor@402
|
155 \label{fig:template:keywords}
|
|
igor@402
|
156 \end{figure}
|
|
igor@402
|
157
|
|
igor@470
|
158 Como mencionamos anteriormente, la palabra clave de fecha no produce
|
|
igor@470
|
159 salida legible por un humano, debemos tratarla de forma especial.
|
|
igor@470
|
160 Esto involucra usar un \emph{filtro}, acerca de lo cual hay más en la
|
|
igor@470
|
161 sección~\ref{sec:template:filter}.
|
|
igor@402
|
162
|
|
igor@402
|
163 \interaction{template.simple.datekeyword}
|
|
igor@402
|
164
|
|
igor@470
|
165 \section{Secuencias de Control}
|
|
igor@402
|
166 \label{sec:template:escape}
|
|
igor@402
|
167
|
|
igor@470
|
168 El motor de plantillas de Mercurial reconoce las secuencias de control
|
|
igor@470
|
169 más comunmente usadas dentro de las cadenas. Cuando ve un backslash
|
|
igor@470
|
170 (``\Verb+\+''), ve el caracter siguiente y sustituye los dos
|
|
igor@470
|
171 caracteres con un reemplazo sencillo, como se describe a continuación:
|
|
igor@402
|
172
|
|
igor@402
|
173 \begin{itemize}
|
|
igor@402
|
174 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
|
|
igor@402
|
175 ASCII~134.
|
|
igor@470
|
176 \item[\Verb+\textbackslash n+] Nueva línea, ASCII~12.
|
|
igor@470
|
177 \item[\Verb+\textbackslash r+] Cambio de línea, ASCII~15.
|
|
igor@402
|
178 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
|
|
igor@470
|
179 \item[\Verb+\textbackslash v+] Tab Vertical, ASCII~13.
|
|
igor@470
|
180 \item[\Verb+\textbackslash \{+] Corchete abierto, ``\Verb+{+'', ASCII~173.
|
|
igor@470
|
181 \item[\Verb+\textbackslash \}+] Corchete cerrado, ``\Verb+}+'', ASCII~175.
|
|
igor@470
|
182 \end{itemize}
|
|
igor@470
|
183
|
|
igor@470
|
184 Como se indicó arriba, si desea que la expansión en una plantilla
|
|
igor@470
|
185 contenga un caracter literal ``\Verb+\+'', ``\Verb+{+'', o
|
|
igor@470
|
186 ``\Verb+{+'', debe escaparlo.
|
|
igor@470
|
187
|
|
igor@470
|
188 \section{Uso de filtros con palabras claves}
|
|
igor@402
|
189 \label{sec:template:filter}
|
|
igor@402
|
190
|
|
igor@470
|
191 Algunos de los resultados de la expansión de la plantilla no son
|
|
igor@470
|
192 fáciles de usar de inmediato. Mercurial le permite especificar una
|
|
igor@470
|
193 cadena de \emph{filtros} opcionales para modificar el resultado de
|
|
igor@470
|
194 expandir una palabra clave. Ya ha visto el filtro usual
|
|
igor@470
|
195 \tplkwfilt{date}{isodate} en acción con anterioridad para hacer
|
|
igor@470
|
196 legible la fecha.
|
|
igor@470
|
197
|
|
igor@470
|
198 A continuación hay una lista de los filtros de Mercurial más
|
|
igor@470
|
199 comunmente usados. Ciertos filtros pueden aplicarse a cualquier
|
|
igor@470
|
200 texto, otros pueden usarse únicamente en circunstancias específicas.
|
|
igor@470
|
201 El nombre de cada filtro está seguido de la indicación de dónde puede
|
|
igor@470
|
202 ser usado y una descripción de su efecto.
|
|
igor@470
|
203
|
|
igor@470
|
204 \begin{itemize}
|
|
igor@470
|
205 \item[\tplfilter{addbreaks}] Cualquier texto. Añade una etiqueta XHTML
|
|
igor@470
|
206 ``\Verb+<br/>+'' antes del final de cada línea excepto en la final.
|
|
igor@470
|
207 Por ejemplo, ``\Verb+foo\nbar+'' se convierte en ``\Verb+foo<br/>\nbar+''.
|
|
igor@470
|
208 \item[\tplkwfilt{date}{age}] palabra clave \tplkword{date}. Muestra
|
|
igor@470
|
209 la edad de la fecha, relativa al tiempo actual. Ofrece una cadena como
|
|
igor@402
|
210 ``\Verb+10 minutes+''.
|
|
igor@470
|
211 \item[\tplfilter{basename}] Cualquier texto, pero de utilidad sobre
|
|
igor@470
|
212 todo en palabras claves relativas a \tplkword{ficheros}. Trata el
|
|
igor@470
|
213 texto como una ruta, retornando el nombre base. Por ejemplo,
|
|
igor@470
|
214 ``\Verb+foo/bar/baz+'', se convierte en ``\Verb+baz+''.
|
|
igor@402
|
215 \item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date
|
|
igor@402
|
216 in a similar format to the Unix \tplkword{date} command, but with
|
|
igor@402
|
217 timezone included. Yields a string like
|
|
igor@402
|
218 ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
|
|
igor@402
|
219 \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
|
|
igor@402
|
220 \tplkword{author} keyword. Finds the first string that looks like
|
|
igor@402
|
221 an email address, and extract just the domain component. For
|
|
igor@402
|
222 example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
igor@402
|
223 ``\Verb+serpentine.com+''.
|
|
igor@402
|
224 \item[\tplkwfilt{author}{email}] Any text, but most useful for the
|
|
igor@402
|
225 \tplkword{author} keyword. Extract the first string that looks like
|
|
igor@402
|
226 an email address. For example,
|
|
igor@402
|
227 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
igor@402
|
228 ``\Verb+bos@serpentine.com+''.
|
|
igor@402
|
229 \item[\tplfilter{escape}] Any text. Replace the special XML/XHTML
|
|
igor@402
|
230 characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
|
|
igor@402
|
231 XML entities.
|
|
igor@402
|
232 \item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68
|
|
igor@402
|
233 columns. This is useful before you pass text through the
|
|
igor@402
|
234 \tplfilter{tabindent} filter, and still want it to fit in an
|
|
igor@402
|
235 80-column fixed-font window.
|
|
igor@402
|
236 \item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76
|
|
igor@402
|
237 columns.
|
|
igor@402
|
238 \item[\tplfilter{firstline}] Any text. Yield the first line of text,
|
|
igor@402
|
239 without any trailing newlines.
|
|
igor@402
|
240 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the
|
|
igor@402
|
241 date as a pair of readable numbers. Yields a string like
|
|
igor@402
|
242 ``\Verb+1157407993 25200+''.
|
|
igor@402
|
243 \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the
|
|
igor@402
|
244 date as a text string in ISO~8601 format. Yields a string like
|
|
igor@402
|
245 ``\Verb+2006-09-04 15:13:13 -0700+''.
|
|
igor@402
|
246 \item[\tplfilter{obfuscate}] Any text, but most useful for the
|
|
igor@402
|
247 \tplkword{author} keyword. Yield the input text rendered as a
|
|
igor@402
|
248 sequence of XML entities. This helps to defeat some particularly
|
|
igor@402
|
249 stupid screen-scraping email harvesting spambots.
|
|
igor@402
|
250 \item[\tplkwfilt{author}{person}] Any text, but most useful for the
|
|
igor@402
|
251 \tplkword{author} keyword. Yield the text before an email address.
|
|
igor@402
|
252 For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
|
|
igor@402
|
253 becomes ``\Verb+Bryan O'Sullivan+''.
|
|
igor@402
|
254 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a
|
|
igor@402
|
255 date using the same format used in email headers. Yields a string
|
|
igor@402
|
256 like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
|
|
igor@402
|
257 \item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form
|
|
igor@402
|
258 of a changeset hash, i.e.~a 12-byte hexadecimal string.
|
|
igor@402
|
259 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render
|
|
igor@402
|
260 the year, month, and day of the date. Yields a string like
|
|
igor@402
|
261 ``\Verb+2006-09-04+''.
|
|
igor@402
|
262 \item[\tplfilter{strip}] Any text. Strip all leading and trailing
|
|
igor@402
|
263 whitespace from the string.
|
|
igor@402
|
264 \item[\tplfilter{tabindent}] Any text. Yield the text, with every line
|
|
igor@402
|
265 except the first starting with a tab character.
|
|
igor@402
|
266 \item[\tplfilter{urlescape}] Any text. Escape all characters that are
|
|
igor@402
|
267 considered ``special'' by URL parsers. For example, \Verb+foo bar+
|
|
igor@402
|
268 becomes \Verb+foo%20bar+.
|
|
igor@402
|
269 \item[\tplkwfilt{author}{user}] Any text, but most useful for the
|
|
igor@402
|
270 \tplkword{author} keyword. Return the ``user'' portion of an email
|
|
igor@402
|
271 address. For example,
|
|
igor@402
|
272 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
|
|
igor@402
|
273 ``\Verb+bos+''.
|
|
igor@402
|
274 \end{itemize}
|
|
igor@402
|
275
|
|
igor@402
|
276 \begin{figure}
|
|
igor@402
|
277 \interaction{template.simple.manyfilters}
|
|
igor@402
|
278 \caption{Template filters in action}
|
|
igor@402
|
279 \label{fig:template:filters}
|
|
igor@402
|
280 \end{figure}
|
|
igor@402
|
281
|
|
igor@402
|
282 \begin{note}
|
|
igor@402
|
283 If you try to apply a filter to a piece of data that it cannot
|
|
igor@402
|
284 process, Mercurial will fail and print a Python exception. For
|
|
igor@402
|
285 example, trying to run the output of the \tplkword{desc} keyword
|
|
igor@402
|
286 into the \tplkwfilt{date}{isodate} filter is not a good idea.
|
|
igor@402
|
287 \end{note}
|
|
igor@402
|
288
|
|
igor@402
|
289 \subsection{Combining filters}
|
|
igor@402
|
290
|
|
igor@402
|
291 It is easy to combine filters to yield output in the form you would
|
|
igor@402
|
292 like. The following chain of filters tidies up a description, then
|
|
igor@402
|
293 makes sure that it fits cleanly into 68 columns, then indents it by a
|
|
igor@402
|
294 further 8~characters (at least on Unix-like systems, where a tab is
|
|
igor@402
|
295 conventionally 8~characters wide).
|
|
igor@402
|
296
|
|
igor@402
|
297 \interaction{template.simple.combine}
|
|
igor@402
|
298
|
|
igor@402
|
299 Note the use of ``\Verb+\t+'' (a tab character) in the template to
|
|
igor@402
|
300 force the first line to be indented; this is necessary since
|
|
igor@402
|
301 \tplkword{tabindent} indents all lines \emph{except} the first.
|
|
igor@402
|
302
|
|
igor@402
|
303 Keep in mind that the order of filters in a chain is significant. The
|
|
igor@402
|
304 first filter is applied to the result of the keyword; the second to
|
|
igor@402
|
305 the result of the first filter; and so on. For example, using
|
|
igor@402
|
306 \Verb+fill68|tabindent+ gives very different results from
|
|
igor@402
|
307 \Verb+tabindent|fill68+.
|
|
igor@402
|
308
|
|
igor@402
|
309
|
|
igor@402
|
310 \section{From templates to styles}
|
|
igor@402
|
311
|
|
igor@402
|
312 A command line template provides a quick and simple way to format some
|
|
igor@402
|
313 output. Templates can become verbose, though, and it's useful to be
|
|
igor@402
|
314 able to give a template a name. A style file is a template with a
|
|
igor@402
|
315 name, stored in a file.
|
|
igor@402
|
316
|
|
igor@402
|
317 More than that, using a style file unlocks the power of Mercurial's
|
|
igor@402
|
318 templating engine in ways that are not possible using the command line
|
|
igor@402
|
319 \hgopt{log}{--template} option.
|
|
igor@402
|
320
|
|
igor@402
|
321 \subsection{The simplest of style files}
|
|
igor@402
|
322
|
|
igor@402
|
323 Our simple style file contains just one line:
|
|
igor@402
|
324
|
|
igor@402
|
325 \interaction{template.simple.rev}
|
|
igor@402
|
326
|
|
igor@402
|
327 This tells Mercurial, ``if you're printing a changeset, use the text
|
|
igor@402
|
328 on the right as the template''.
|
|
igor@402
|
329
|
|
igor@402
|
330 \subsection{Style file syntax}
|
|
igor@402
|
331
|
|
igor@402
|
332 The syntax rules for a style file are simple.
|
|
igor@402
|
333
|
|
igor@402
|
334 \begin{itemize}
|
|
igor@402
|
335 \item The file is processed one line at a time.
|
|
igor@402
|
336
|
|
igor@402
|
337 \item Leading and trailing white space are ignored.
|
|
igor@402
|
338
|
|
igor@402
|
339 \item Empty lines are skipped.
|
|
igor@402
|
340
|
|
igor@402
|
341 \item If a line starts with either of the characters ``\texttt{\#}'' or
|
|
igor@402
|
342 ``\texttt{;}'', the entire line is treated as a comment, and skipped
|
|
igor@402
|
343 as if empty.
|
|
igor@402
|
344
|
|
igor@402
|
345 \item A line starts with a keyword. This must start with an
|
|
igor@402
|
346 alphabetic character or underscore, and can subsequently contain any
|
|
igor@402
|
347 alphanumeric character or underscore. (In regexp notation, a
|
|
igor@402
|
348 keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
|
|
igor@402
|
349
|
|
igor@402
|
350 \item The next element must be an ``\texttt{=}'' character, which can
|
|
igor@402
|
351 be preceded or followed by an arbitrary amount of white space.
|
|
igor@402
|
352
|
|
igor@402
|
353 \item If the rest of the line starts and ends with matching quote
|
|
igor@402
|
354 characters (either single or double quote), it is treated as a
|
|
igor@402
|
355 template body.
|
|
igor@402
|
356
|
|
igor@402
|
357 \item If the rest of the line \emph{does not} start with a quote
|
|
igor@402
|
358 character, it is treated as the name of a file; the contents of this
|
|
igor@402
|
359 file will be read and used as a template body.
|
|
igor@402
|
360 \end{itemize}
|
|
igor@402
|
361
|
|
igor@402
|
362 \section{Style files by example}
|
|
igor@402
|
363
|
|
igor@402
|
364 To illustrate how to write a style file, we will construct a few by
|
|
igor@402
|
365 example. Rather than provide a complete style file and walk through
|
|
igor@402
|
366 it, we'll mirror the usual process of developing a style file by
|
|
igor@402
|
367 starting with something very simple, and walking through a series of
|
|
igor@402
|
368 successively more complete examples.
|
|
igor@402
|
369
|
|
igor@402
|
370 \subsection{Identifying mistakes in style files}
|
|
igor@402
|
371
|
|
igor@402
|
372 If Mercurial encounters a problem in a style file you are working on,
|
|
igor@402
|
373 it prints a terse error message that, once you figure out what it
|
|
igor@402
|
374 means, is actually quite useful.
|
|
igor@402
|
375
|
|
igor@402
|
376 \interaction{template.svnstyle.syntax.input}
|
|
igor@402
|
377
|
|
igor@402
|
378 Notice that \filename{broken.style} attempts to define a
|
|
igor@402
|
379 \texttt{changeset} keyword, but forgets to give any content for it.
|
|
igor@402
|
380 When instructed to use this style file, Mercurial promptly complains.
|
|
igor@402
|
381
|
|
igor@402
|
382 \interaction{template.svnstyle.syntax.error}
|
|
igor@402
|
383
|
|
igor@402
|
384 This error message looks intimidating, but it is not too hard to
|
|
igor@402
|
385 follow.
|
|
igor@402
|
386
|
|
igor@402
|
387 \begin{itemize}
|
|
igor@402
|
388 \item The first component is simply Mercurial's way of saying ``I am
|
|
igor@402
|
389 giving up''.
|
|
igor@402
|
390 \begin{codesample4}
|
|
igor@402
|
391 \textbf{abort:} broken.style:1: parse error
|
|
igor@402
|
392 \end{codesample4}
|
|
igor@402
|
393
|
|
igor@402
|
394 \item Next comes the name of the style file that contains the error.
|
|
igor@402
|
395 \begin{codesample4}
|
|
igor@402
|
396 abort: \textbf{broken.style}:1: parse error
|
|
igor@402
|
397 \end{codesample4}
|
|
igor@402
|
398
|
|
igor@402
|
399 \item Following the file name is the line number where the error was
|
|
igor@402
|
400 encountered.
|
|
igor@402
|
401 \begin{codesample4}
|
|
igor@402
|
402 abort: broken.style:\textbf{1}: parse error
|
|
igor@402
|
403 \end{codesample4}
|
|
igor@402
|
404
|
|
igor@402
|
405 \item Finally, a description of what went wrong.
|
|
igor@402
|
406 \begin{codesample4}
|
|
igor@402
|
407 abort: broken.style:1: \textbf{parse error}
|
|
igor@402
|
408 \end{codesample4}
|
|
igor@402
|
409 The description of the problem is not always clear (as in this
|
|
igor@402
|
410 case), but even when it is cryptic, it is almost always trivial to
|
|
igor@402
|
411 visually inspect the offending line in the style file and see what
|
|
igor@402
|
412 is wrong.
|
|
igor@402
|
413 \end{itemize}
|
|
igor@402
|
414
|
|
igor@402
|
415 \subsection{Uniquely identifying a repository}
|
|
igor@402
|
416
|
|
igor@402
|
417 If you would like to be able to identify a Mercurial repository
|
|
igor@402
|
418 ``fairly uniquely'' using a short string as an identifier, you can
|
|
igor@402
|
419 use the first revision in the repository.
|
|
igor@402
|
420 \interaction{template.svnstyle.id}
|
|
igor@402
|
421 This is not guaranteed to be unique, but it is nevertheless useful in
|
|
igor@402
|
422 many cases.
|
|
igor@402
|
423 \begin{itemize}
|
|
igor@402
|
424 \item It will not work in a completely empty repository, because such
|
|
igor@402
|
425 a repository does not have a revision~zero.
|
|
igor@402
|
426 \item Neither will it work in the (extremely rare) case where a
|
|
igor@402
|
427 repository is a merge of two or more formerly independent
|
|
igor@402
|
428 repositories, and you still have those repositories around.
|
|
igor@402
|
429 \end{itemize}
|
|
igor@402
|
430 Here are some uses to which you could put this identifier:
|
|
igor@402
|
431 \begin{itemize}
|
|
igor@402
|
432 \item As a key into a table for a database that manages repositories
|
|
igor@402
|
433 on a server.
|
|
igor@402
|
434 \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
|
|
igor@402
|
435 Save this information away when you run an automated build or other
|
|
igor@402
|
436 activity, so that you can ``replay'' the build later if necessary.
|
|
igor@402
|
437 \end{itemize}
|
|
igor@402
|
438
|
|
igor@402
|
439 \subsection{Mimicking Subversion's output}
|
|
igor@402
|
440
|
|
igor@402
|
441 Let's try to emulate the default output format used by another
|
|
igor@402
|
442 revision control tool, Subversion.
|
|
igor@402
|
443 \interaction{template.svnstyle.short}
|
|
igor@402
|
444
|
|
igor@402
|
445 Since Subversion's output style is fairly simple, it is easy to
|
|
igor@402
|
446 copy-and-paste a hunk of its output into a file, and replace the text
|
|
igor@402
|
447 produced above by Subversion with the template values we'd like to see
|
|
igor@402
|
448 expanded.
|
|
igor@402
|
449 \interaction{template.svnstyle.template}
|
|
igor@402
|
450
|
|
igor@402
|
451 There are a few small ways in which this template deviates from the
|
|
igor@402
|
452 output produced by Subversion.
|
|
igor@402
|
453 \begin{itemize}
|
|
igor@402
|
454 \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
|
|
igor@402
|
455 2006}'' in the example output above) in parentheses. Mercurial's
|
|
igor@402
|
456 templating engine does not provide a way to display a date in this
|
|
igor@402
|
457 format without also printing the time and time zone.
|
|
igor@402
|
458 \item We emulate Subversion's printing of ``separator'' lines full of
|
|
igor@402
|
459 ``\texttt{-}'' characters by ending the template with such a line.
|
|
igor@402
|
460 We use the templating engine's \tplkword{header} keyword to print a
|
|
igor@402
|
461 separator line as the first line of output (see below), thus
|
|
igor@402
|
462 achieving similar output to Subversion.
|
|
igor@402
|
463 \item Subversion's output includes a count in the header of the number
|
|
igor@402
|
464 of lines in the commit message. We cannot replicate this in
|
|
igor@402
|
465 Mercurial; the templating engine does not currently provide a filter
|
|
igor@402
|
466 that counts the number of items it is passed.
|
|
igor@402
|
467 \end{itemize}
|
|
igor@402
|
468 It took me no more than a minute or two of work to replace literal
|
|
igor@402
|
469 text from an example of Subversion's output with some keywords and
|
|
igor@402
|
470 filters to give the template above. The style file simply refers to
|
|
igor@402
|
471 the template.
|
|
igor@402
|
472 \interaction{template.svnstyle.style}
|
|
igor@402
|
473
|
|
igor@402
|
474 We could have included the text of the template file directly in the
|
|
igor@402
|
475 style file by enclosing it in quotes and replacing the newlines with
|
|
igor@402
|
476 ``\verb!\n!'' sequences, but it would have made the style file too
|
|
igor@402
|
477 difficult to read. Readability is a good guide when you're trying to
|
|
igor@402
|
478 decide whether some text belongs in a style file, or in a template
|
|
igor@402
|
479 file that the style file points to. If the style file will look too
|
|
igor@402
|
480 big or cluttered if you insert a literal piece of text, drop it into a
|
|
igor@402
|
481 template instead.
|
|
igor@402
|
482
|
|
igor@402
|
483 %%% Local Variables:
|
|
igor@402
|
484 %%% mode: latex
|
|
igor@402
|
485 %%% TeX-master: "00book"
|
|
igor@402
|
486 %%% End:
|
