hgbook
view es/template.tex @ 764:42ffc394c34e
Typo.
| author | Giulio@puck |
|---|---|
| date | Fri Jul 24 18:08:04 2009 +0200 (2009-07-24) |
| parents | bbc5db74bd77 |
| children |
line source
1 \chapter{Personalizar los mensajes de Mercurial}
2 \label{chap:template}
4 Mercurial provee un poderoso mecanismo que permite controlar como
5 despliega la información. El mecanismo se basa en plantillas. Puede
6 usar plantillas para generar salida específica para una orden
7 particular o para especificar la visualización completa de la interfaz
8 web embebida.
10 \section{Usar estilos que vienen con Mercurial}
11 \label{sec:style}
13 Hay ciertos estilos listos que vienen con Mercurial. Un estilo es
14 simplemente una plantilla predeterminada que alguien escribió e
15 instaló en un sitio en el cual Mercurial puede encontrarla.
17 Antes de dar un vistazo a los estilos que trae Mercurial, revisemos su
18 salida usual.
20 \interaction{template.simple.normal}
22 Es en cierta medida informativa, pero ocupa mucho espacio---cinco
23 líneas de salida por cada conjunto de cambios. El estilo
24 \texttt{compact} lo reduce a tres líneas, presentadas de forma
25 suscinta.
27 \interaction{template.simple.compact}
29 El estilo de la \texttt{bitácora de cambios} vislumbra el poder
30 expresivo del sistema de plantillas de Mercurial. Este estilo busca
31 seguir los estándares de bitácora de cambios del proyecto
32 GNU\cite{web:changelog}.
34 \interaction{template.simple.changelog}
36 No es una sorpresa que el estilo predeterminado de Mercurial se llame
37 \texttt{default}\ndt{predeterminado}.
39 \subsection{Especificar un estilo predeterminado}
41 Puede modificar el estilo de presentación que Mercurial usará para
42 toda orden vía el fichero \hgrc\, indicando el estilo que prefiere
43 usar.
45 \begin{codesample2}
46 [ui]
47 style = compact
48 \end{codesample2}
50 Si escribe un estilo, puede usarlo bien sea proveyendo la ruta a su
51 fichero de estilo o copiando su fichero de estilo a un lugar en el
52 cual Mercurial pueda encontrarlo (típicamente el subdirectorio
53 \texttt{templates} de su directorio de instalación de Mercurial).
55 \section{Órdenes que soportan estilos y plantillas}
57 Todas las órdenes de Mercurial``relacionadas con \texttt{log}'' le
58 permiten usar estilos y plantillas: \hgcmd{incoming}, \hgcmd{log},
59 \hgcmd{outgoing} y \hgcmd{tip}.
61 Al momento de la escritura del manual estas son las únicas órdenes que
62 soportan estilos y plantillas. Dado que son las órdenes más
63 importantes que necesitan personalización, no ha habido muchas
64 solicitudes desde la comunidad de usuarios de Mercurial para añadir
65 soporte de plantillas y estilos a otras órdenes.
67 \section{Cuestiones básicas de plantillas}
69 Una plantilla de Mercurial es sencillamente una pieza de texto.
70 Cierta porción nunca cambia, otras partes se \emph{expanden}, o
71 reemplazan con texto nuevo cuando es necesario.
73 Antes de continuar, veamos de nuevo un ejemplo sencillo de la salida
74 usual de Mercurial:
76 \interaction{template.simple.normal}
78 Ahora, ejecutemos la misma orden, pero usemos una plantilla para
79 modificar su salida:
81 \interaction{template.simple.simplest}
83 El ejemplo anterior ilustra la plantilla más sencilla posible; es
84 solamente una porción estática de código que se imprime una vez por
85 cada conjunto de cambios. La opción \hgopt{log}{--template} de la
86 orden \hgcmd{log} indica a Mercurial usar el texto dado como la
87 plantilla cuando se imprime cada conjunto de cambios.
89 Observe que la cadena de plantilla anterior termina con el texto
90 ``\Verb+\n+''. Es una \emph{secuencia de control}, que le indica a
91 Mercurial imprimira una nueva línea al final de cada objeto de la
92 plantilla. Si omite esta nueva línea, Mercurial colocará cada pieza
93 de salida seguida. Si desea más detalles acerca de secuencias de
94 control, vea la sección~\ref{sec:template:escape}.
96 Una plantilla que imprime una cadena fija de texto siempre no es muy
97 útil; intentemos algo un poco más complejo.
99 \interaction{template.simple.simplesub}
101 Como puede ver, la cadena ``\Verb+{desc}+'' en la plantilla ha sido
102 reemplazada en la salida con la descricipción de cada conjunto de
103 cambios. Cada vez que Mercurial encuentra texto encerrado entre
104 corchetes (``\texttt{\{}'' y ``\texttt{\}}''), intentará reemplazar los
105 corchetes y el texto con la expansión de lo que sea está adentro.
106 Para imprimir un corchete de forma literal, debe escaparlo, como se
107 describe en la sección~\ref{sec:template:escape}.
109 \section{Palabras claves más comunes en las plantillas}
110 \label{sec:template:keyword}
112 Puede empezar a escribir plantillas sencillas rápidamente con las
113 palabras claves descritas a continuación:
115 \begin{itemize}
116 \item[\tplkword{author}] Cadena. El autor NO modificado del conjunto
117 de cambios.
118 \item[\tplkword{branches}] Cadena. El nombre de la rama en la cual se
119 consignó el conjunto de cambios. Será vacía si el nombre de la rama es
120 \texttt{default}.
121 \item[\tplkword{date}] Información de fecha. La fecha en la cual se
122 consignó el conjunto de cambios. \emph{No} es legible por un
123 humano, debe pasarla por un firltro que la desplegará
124 apropiadamente. En la sección~\ref{sec:template:filter} hay más
125 detalles acerca de filtros. La fecha se expresa como un par de
126 números. El primer número corresponde a una marca de tiempo UNIX
127 UTC (segundos desde el primero de enero de 1970); la segunda es el
128 corrimiento horario de la zona horaria del UTC en la cual se encontraba
129 quien hizo la consignación, en segundos.
130 \item[\tplkword{desc}] Cadena. La descripción en texto del conjunto
131 de cambios.
132 \item[\tplkword{files}] Lista de cadenas. Todos los ficheros
133 modificados, adicionados o eliminados por este conjunto de cambios.
134 \item[\tplkword{file\_adds}] Lista de cadenas. Ficheros adicionados
135 por este conjunto de cambios.
136 \item[\tplkword{file\_dels}] Lista de cadenas. Ficheros eliminados
137 por este conjunto de cambios.
138 \item[\tplkword{node}] Cadena. El hash de identificación de este
139 conjunto de cambios como una cadena hexadecimal de 40 caracteres.
140 \item[\tplkword{parents}] Lista de cadenas. Los ancestros del
141 conjunto de cambios.
142 \item[\tplkword{rev}] Entero. El número de revisión del repositorio
143 local.
144 \item[\tplkword{tags}] Lista de cadenas. Todas las etiquetas
145 asociadas al conjunto de cambios.
146 \end{itemize}
148 Unos experimentos sencillos nos mostrarán qué esperar cuando usamos
149 estas palabras claves; puede ver los resultados en la
150 figura~\ref{fig:template:keywords}.
152 \begin{figure}
153 \interaction{template.simple.keywords}
154 \caption{Template keywords in use}
155 \label{fig:template:keywords}
156 \end{figure}
158 Como mencionamos anteriormente, la palabra clave de fecha no produce
159 salida legible por un humano, debemos tratarla de forma especial.
160 Esto involucra usar un \emph{filtro}, acerca de lo cual hay más en la
161 sección~\ref{sec:template:filter}.
163 \interaction{template.simple.datekeyword}
165 \section{Secuencias de Control}
166 \label{sec:template:escape}
168 El motor de plantillas de Mercurial reconoce las secuencias de control
169 más comunmente usadas dentro de las cadenas. Cuando ve un backslash
170 (``\Verb+\+''), ve el caracter siguiente y sustituye los dos
171 caracteres con un reemplazo sencillo, como se describe a continuación:
173 \begin{itemize}
174 \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
175 ASCII~134.
176 \item[\Verb+\textbackslash n+] Nueva línea, ASCII~12.
177 \item[\Verb+\textbackslash r+] Cambio de línea, ASCII~15.
178 \item[\Verb+\textbackslash t+] Tab, ASCII~11.
179 \item[\Verb+\textbackslash v+] Tab Vertical, ASCII~13.
180 \item[\Verb+\textbackslash \{+] Corchete abierto, ``\Verb+{+'', ASCII~173.
181 \item[\Verb+\textbackslash \}+] Corchete cerrado, ``\Verb+}+'', ASCII~175.
182 \end{itemize}
184 Como se indicó arriba, si desea que la expansión en una plantilla
185 contenga un caracter literal ``\Verb+\+'', ``\Verb+{+'', o
186 ``\Verb+{+'', debe escaparlo.
188 \section{Uso de filtros con palabras claves}
189 \label{sec:template:filter}
191 Algunos de los resultados de la expansión de la plantilla no son
192 fáciles de usar de inmediato. Mercurial le permite especificar una
193 cadena de \emph{filtros} opcionales para modificar el resultado de
194 expandir una palabra clave. Ya ha visto el filtro usual
195 \tplkwfilt{date}{isodate} en acción con anterioridad para hacer
196 legible la fecha.
198 A continuación hay una lista de los filtros de Mercurial más
199 comunmente usados. Ciertos filtros pueden aplicarse a cualquier
200 texto, otros pueden usarse únicamente en circunstancias específicas.
201 El nombre de cada filtro está seguido de la indicación de dónde puede
202 ser usado y una descripción de su efecto.
204 \begin{itemize}
205 \item[\tplfilter{addbreaks}] Cualquier texto. Añade una etiqueta XHTML
206 ``\Verb+<br/>+'' antes del final de cada línea excepto en la final.
207 Por ejemplo, ``\Verb+foo\nbar+'' se convierte en ``\Verb+foo<br/>\nbar+''.
208 \item[\tplkwfilt{date}{age}] palabra clave \tplkword{date}. Muestra
209 la edad de la fecha, relativa al tiempo actual. Ofrece una cadena como
210 ``\Verb+10 minutes+''.
211 \item[\tplfilter{basename}] Cualquier texto, pero de utilidad sobre
212 todo en palabras claves relativas a \tplkword{ficheros}. Trata el
213 texto como una ruta, retornando el nombre base. Por ejemplo,
214 ``\Verb+foo/bar/baz+'', se convierte en ``\Verb+baz+''.
215 \item[\tplkwfilt{date}{date}] \tplkword{date} palabra clave. Mostrar
216 la fecha en un formato similar a la orden \tplkword{date} de
217 in a similar format to the Unix, pero con la zona horaria incluída.
218 Una cadena como ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
219 \item[\tplkwfilt{author}{domain}] Cualquier texto, pero de mayor
220 utilidad para la palabra clave \tplkword{author}. Encuentra la
221 primera cadena que luce como una dirección de correo electrónico, y
222 extrae solamente el componente del dominio. Por ejemplo, de
223 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' se extrae
224 ``\Verb+serpentine.com+''.
225 \item[\tplkwfilt{author}{email}] Cualquier texto, pero de mayor
226 utilidad para la palabra clave \tplkword{author}. Extrae la primera
227 cadena que luce como una dirección de correo. Por ejemplo, de
228 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' extrae
229 ``\Verb+bos@serpentine.com+''.
230 \item[\tplfilter{escape}] Cualquier texto. Reemplaza los caracteres
231 especiales de XML/XHTML: ``\Verb+&+'', ``\Verb+<+'' y ``\Verb+>+''
232 con las entidades XML.
233 \item[\tplfilter{fill68}] Cualquier texto. Lograr que el texto ocupe
234 las primeras 68 columnas. Es útil emplearlo antes de pasar el texto
235 por el filtro \tplfilter{tabindent}, y queremos que aún quepa en una
236 ventana de fuente fija y 80 columnas.
237 \item[\tplfilter{fill76}] Cualquier texto. Lograr que el texto quepa
238 en 76 columnas.
239 \item[\tplfilter{firstline}] Cualquier texto. Mostrar la primera
240 línea de texto sin saltos de línea.
241 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} palabra clave.
242 Mostrar la fecha como un par de números legibles. Muestra una
243 cadena como ``\Verb+1157407993 25200+''.
244 \item[\tplkwfilt{date}{isodate}] \tplkword{date} palabra clave.
245 Mostrar la fecha como una cadena de texto en el formato. Muestra
246 una cadena como ``\Verb+2006-09-04 15:13:13 -0700+''.
247 \item[\tplfilter{obfuscate}] Cualquier texto, pero de mayor utilidad
248 para la palabra clave \tplkword{author}. Muestra el campo de texto
249 como una secuencia de entidades XML. Esto ayuda a eliminar ciertos
250 robots estúpidos de adquisición de correo.
251 \item[\tplkwfilt{author}{person}] Cualquier texto, útil sobre todo
252 para la palabra clave \tplkword{author}. Muestra el texto que hay
253 antes de la dirección de correo electrónico. Por ejemplo,
254 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' mostraría
255 ``\Verb+Bryan O'Sullivan+''.
256 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} palabra clave.
257 Muestra una fecha con el mismo formato que se usa en los encabezados
258 de correo. Mostraría una cadena como
259 ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
260 \item[\tplkwfilt{node}{short}] Hash del conjunto de cambios. Muestra
261 la forma corta de un hash de conjunto de cambios,
262 of a changeset hash, p.e.~una cadena hexadecimal de 12 bytes.
263 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} palabra clave.
264 Mostrar año, mes y día de una fecha. Muestrauna cadena como
265 ``\Verb+2006-09-04+''.
266 \item[\tplfilter{strip}] Cualquier texto. Elimina todos los espacios
267 en blanco al principio y al final de la cadena.
268 \item[\tplfilter{tabindent}] Cualquier texto. Muestra el texto con
269 todas las líneas excepto la primera que comience con el caracter tab.
270 \item[\tplfilter{urlescape}] Cualquier texto. Escapa todos los
271 caracteres que se consideren como ``especiales'' por los parsers de
272 URL. Por ejemplo, \Verb+foo bar+ se convierte en \Verb+foo%20bar+.
273 \item[\tplkwfilt{author}{user}] Cualquier texto, útil sobre todo para
274 la palabra clave \tplkword{author}. Retorna el ``usuario'' de una
275 dirección de correo. Por ejemplo,
276 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' se convierte en
277 ``\Verb+bos+''.
278 \end{itemize}
280 \begin{figure}
281 \interaction{template.simple.manyfilters}
282 \caption{Filtros de plantilla en acción}
283 \label{fig:template:filters}
284 \end{figure}
286 \begin{note}
287 Si trata de aplicar un filtro a una porción de datos que no puede
288 procesarse, Mercurial fallará e imprimirá una excepción de Python.
289 Por ejemplo, el tratar de usar la salida de la palabra clave
290 \tplkword{desc} con el filtro \tplkwfilt{date}{isodate} no resultará
291 algo útil.
292 \end{note}
294 \subsection{Combinar filtros}
296 Combinar filtros es para generar una salida en la forma como usted lo
297 desea es muy sencillo. La cadena de filtros siguientes arman una
298 descripción, después aseguran que cabe limpiamente en 68 columnas, y
299 las indenta con 8~caracteres (por lo menos en sistemas tipo Unix, en
300 los que el tab por convención se extiende en 8~caracteres).
302 \interaction{template.simple.combine}
304 Observe el uso de ``\Verb+\t+'' (un caracter tab) en la plantilla para
305 forzar que la primera línea se indente; esto es necesario para lograr
306 que la primera línea luzca indentada; es necesario debido a que
307 \tplkword{tabindent} indenta todas las líneas \emph{excepto} la primera.
309 Tenga en cuenta que el orden de los filtros importa. El primer filtro
310 se aplica primero al resultado de la palabra clave; el segundo al
311 resultado de la aplicación del primer filtro y así sucesivamente. Por
312 ejemplo, usar \Verb+fill68|tabindent+ es muy distinto al resultado de
313 usar \Verb+tabindent|fill68+.
316 \section{De plantillas a estilos}
318 Una plantilla provee una forma rápida y sencilla para dar formato a
319 una salida. Las plantillas pueden volvers verbosas, y es útil poder
320 darle un nombre a una plantilla. Un fichero de estilo es una
321 plantilla con un nombre, almacenado en un fichero.
323 Más aún, al usar un fichero de estilo se dispara el poder del motor de
324 plantillas en un nivel imposible de alcanzar usando las opción
325 \hgopt{log}{--template} desde la línea de órdenes.
328 \subsection{Los ficheros de estilo más sencillos}
330 Nuestro fichero sencillo de estilo contiene una sola línea:
332 \interaction{template.simple.rev}
334 Se le indica a Mercurial, ``si está imprimiendo un conjunto de
335 cambios, use el texto de la derecha como la plantilla''.
337 \subsection{Sintaxis de ficheros de estilo}
339 Las reglas de sintaxis para un fichero de estilo son sencillas:
341 \begin{itemize}
342 \item El fichero se procesa línea por línea.
344 \item Se ignoran el espacio en blanco circundante.
346 \item Se omiten las líneas en blanco.
348 \item Si una línea comienza con los caracteres ``\texttt{\#}'' o
349 ``\texttt{;}'', la línea completa se trata como un comentario, y se
350 omite como si fuera vacía.
352 \item Una línea comienza con una palabra clave. Esta debe comenzar
353 con una caracter alfabético o una raya al piso, y puede contener
354 subsecuentemente cualquier caracter alfanumérico o una raya al
355 piso. (En notación de expresiones regulares debe coincidir con
356 \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
358 \item El próximo elemento debe ser un caracter ``\texttt{=}'', que
359 puede estar precedido o seguido por una cantidad arbitraria de
360 espacio.
362 \item Si el resto de la línea comienza y termina con caracteres
363 encerrados entre caracteres de comillas (bien sea sencillas o
364 dobles), se trata como cuerpo de la plantilla.
366 \item Si el resto de la línea \emph{no} comienza con una comilla, se
367 trata como el nombre de un fichero; los contenidos de este fichero
368 se leerán y se usarán como cuerpo de la plantilla.
369 \end{itemize}
371 \section{Ejemplos de ficheros de estilos}
373 Para ilustrar la creación de un fichero de estilo, construiremos
374 algunos ejemplos. En lugar de ofrecer un fichero completo de estilo y
375 analizarlo, replicaremos el proceso usual de desarrollo de un fichero
376 de estilo comenzando con algo muy sencillo, y avanzando por una serie
377 de ejemplos sucesivos más completos.
379 \subsection{Identificar equivocaciones en ficheros de estilo}
381 Si Mercurial encuentra un problema en un fichero de estilo en el cual
382 usted está trabajando, imprime un mensaje de error suscinto, cuando
383 usted identifique lo que significa, resulta muy útil.
385 \interaction{template.svnstyle.syntax.input}
387 Tenga en cuenta que \filename{broken.style} trata de definir la
388 palabra clave \texttt{changeset}, pero omite dar un contenido para esta.
389 Cuando se le indica a Mercurial que use este fichero de estilo, se
390 queja inmediatamente.
392 \interaction{template.svnstyle.syntax.error}
394 Este mensaje de error luce intimidante, pero no es muy difícil de
395 seguir:
397 \begin{itemize}
398 \item El primer componente es la forma como Mercurial dice ``me rindo''.
399 \begin{codesample4}
400 \textbf{abort:} broken.style:1: parse error
401 \end{codesample4}
403 \item A continuación viene el nombre del fichero que contiene el error.
404 \begin{codesample4}
405 abort: \textbf{broken.style}:1: parse error
406 \end{codesample4}
408 \item Siguendo el nombre del fichero viene el número de línea en la
409 que se encontró el error.
410 \begin{codesample4}
411 abort: broken.style:\textbf{1}: parse error
412 \end{codesample4}
414 \item Finalmente, la descripción de lo que falló.
415 \begin{codesample4}
416 abort: broken.style:1: \textbf{parse error}
417 \end{codesample4}
418 La descripción del problema no siempre es clara (como en este caso),
419 pero aunque sea críptica, casi siempre es trivial la inspección
420 visual de la línea en el fichero de estilo y encontrar lo que está
421 mal.
422 \end{itemize}
424 \subsection{Identificar de forma única un repositorio}
426 Si desea identificar un repositorio de Mercurial ``de forma única''
427 con una cadena corta como identificador, puede usar la primera
428 revisión en el repositorio.
429 \interaction{template.svnstyle.id}
430 No es garantía de unicidad, pero no es útill en ciertos casos:
431 many cases.
432 \begin{itemize}
433 \item No funcionará en un repositorio completamente vacío, porque un
434 repositorio así no tiene una revisión~zero.
435 \item Tampoco funcionará en caso (muy raro) cuando el repositorio sea
436 una fusión de dos repositorios independientes y tiene los dos
437 directorios por ahí.
438 \end{itemize}
439 Hay ciertos casos en los cuales podría colocar el identificador:
440 \begin{itemize}
441 \item Como una llave en la tabla de una base de datos que administra
442 repositorios en un servidor.
443 \item Como una parte del par \{\emph{ID~repositorio}, \emph{ID~revisión}\}.
444 Almacene esta información de forma independiente cuando ejecute
445 construcciones automatizadas u otras actividades, de forma que pueda
446 ``reconstruir'' posteriormente en caso de ser necesario.
447 \end{itemize}
449 \subsection{Mostrando salida parecida a Subversion}
451 Intentemos emular la salida usual que usa otro sistema de control de
452 revisiones, Subversion.
453 \interaction{template.svnstyle.short}
455 Dado que la salida de Subversion es sencilla, es fácil copiar y pegar
456 una porción de su salida en un fichero, y reemplazar el texto
457 producido previamente por Subversion con valores base que quisiéramos
458 ver expandidos.
459 \interaction{template.svnstyle.template}
461 Esta plantilla difiere en algunos detalles de la salida producida por
462 Subversion:
463 \begin{itemize}
464 \item Subversion imprime una fecha ``legible'' (el ``\texttt{Wed, 27 Sep
465 2006}'' en el ejemplo de salida anterior) en paréntesis. El motor
466 de plantillas de Mercurial no ofrece una forma sencilla de desplegar
467 una fecha en este formato sin imprimir también la hora y la zona horaria.
468 \item Emulamos las líneas de ``separación'' de subversion con caracteres
469 ``\texttt{-}'' en una línea. Usamos la palabra clave
470 \tplkword{header} del motor de plantillas para imprimir una línea de
471 separación como la primera línea de salida (ver más abajo), para
472 lograr una salida similara a la de Subversion.
473 \item La salida de subversion incluye un conteo en el encabezado del
474 número de líneas en el mensaje de consinación. No podemos
475 replicarlo en Mercurial; el motor de plantilla no ofrece en la
476 actualidad un filtro que cuente la cantidad de objetos que se le
477 pasen.
478 \end{itemize}
479 No me tomó más de un minuto o dos de trabajo para reemplazar texto
480 literal de un ejemplo de salida de la salida de Subversion con ciertas
481 palabras claves y filtros para ofrecer la plantilla anterior. El
482 fichero de estilo se refiere sencillamente a la plantilla.
483 \interaction{template.svnstyle.style}
485 Podríamos haber incluído el texto del fichero plantilla directamente
486 en el fichero de estilo encerrando entre comillas y reemplazando las
487 nuevas líneas con secuencias ``\verb!\n!'', pero haría muy difícil de
488 leer el fichero de estilos. La facilidad para leer es importante
489 cuando está decidiendo si un texto pertenece a un fichero de estilo o
490 a un fichero de plantilla incluído en el estilo. Si el fichero de
491 estilo luce muy grande o complicado, si inserta una pieza de texto
492 literal, mejor colóquelo en una plantilla.
494 %%% Local Variables:
495 %%% mode: latex
496 %%% TeX-master: "00book"
497 %%% End: