| 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
|
|
jerojasro@520
|
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
|
|
jerojasro@520
|
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
|
|
jerojasro@520
|
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@473
|
215 \item[\tplkwfilt{date}{date}] \tplkword{date} palabra clave. Mostrar
|
|
igor@473
|
216 la fecha en un formato similar a la orden \tplkword{date} de
|
|
igor@473
|
217 in a similar format to the Unix, pero con la zona horaria incluída.
|
|
igor@473
|
218 Una cadena como ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
|
|
igor@473
|
219 \item[\tplkwfilt{author}{domain}] Cualquier texto, pero de mayor
|
|
igor@473
|
220 utilidad para la palabra clave \tplkword{author}. Encuentra la
|
|
igor@473
|
221 primera cadena que luce como una dirección de correo electrónico, y
|
|
igor@473
|
222 extrae solamente el componente del dominio. Por ejemplo, de
|
|
igor@473
|
223 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' se extrae
|
|
igor@402
|
224 ``\Verb+serpentine.com+''.
|
|
igor@473
|
225 \item[\tplkwfilt{author}{email}] Cualquier texto, pero de mayor
|
|
igor@473
|
226 utilidad para la palabra clave \tplkword{author}. Extrae la primera
|
|
igor@473
|
227 cadena que luce como una dirección de correo. Por ejemplo, de
|
|
igor@473
|
228 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' extrae
|
|
igor@402
|
229 ``\Verb+bos@serpentine.com+''.
|
|
igor@473
|
230 \item[\tplfilter{escape}] Cualquier texto. Reemplaza los caracteres
|
|
igor@473
|
231 especiales de XML/XHTML: ``\Verb+&+'', ``\Verb+<+'' y ``\Verb+>+''
|
|
igor@473
|
232 con las entidades XML.
|
|
jerojasro@525
|
233 \item[\tplfilter{fill68}] Cualquier texto. Lograr que el texto ocupe
|
|
igor@473
|
234 las primeras 68 columnas. Es útil emplearlo antes de pasar el texto
|
|
igor@473
|
235 por el filtro \tplfilter{tabindent}, y queremos que aún quepa en una
|
|
igor@473
|
236 ventana de fuente fija y 80 columnas.
|
|
igor@473
|
237 \item[\tplfilter{fill76}] Cualquier texto. Lograr que el texto quepa
|
|
igor@473
|
238 en 76 columnas.
|
|
igor@473
|
239 \item[\tplfilter{firstline}] Cualquier texto. Mostrar la primera
|
|
igor@473
|
240 línea de texto sin saltos de línea.
|
|
igor@473
|
241 \item[\tplkwfilt{date}{hgdate}] \tplkword{date} palabra clave.
|
|
igor@473
|
242 Mostrar la fecha como un par de números legibles. Muestra una
|
|
igor@473
|
243 cadena como ``\Verb+1157407993 25200+''.
|
|
igor@473
|
244 \item[\tplkwfilt{date}{isodate}] \tplkword{date} palabra clave.
|
|
igor@473
|
245 Mostrar la fecha como una cadena de texto en el formato. Muestra
|
|
igor@473
|
246 una cadena como ``\Verb+2006-09-04 15:13:13 -0700+''.
|
|
igor@473
|
247 \item[\tplfilter{obfuscate}] Cualquier texto, pero de mayor utilidad
|
|
igor@473
|
248 para la palabra clave \tplkword{author}. Muestra el campo de texto
|
|
igor@473
|
249 como una secuencia de entidades XML. Esto ayuda a eliminar ciertos
|
|
igor@473
|
250 robots estúpidos de adquisición de correo.
|
|
igor@473
|
251 \item[\tplkwfilt{author}{person}] Cualquier texto, útil sobre todo
|
|
igor@473
|
252 para la palabra clave \tplkword{author}. Muestra el texto que hay
|
|
igor@473
|
253 antes de la dirección de correo electrónico. Por ejemplo,
|
|
igor@473
|
254 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' mostraría
|
|
igor@473
|
255 ``\Verb+Bryan O'Sullivan+''.
|
|
igor@473
|
256 \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} palabra clave.
|
|
igor@473
|
257 Muestra una fecha con el mismo formato que se usa en los encabezados
|
|
igor@473
|
258 de correo. Mostraría una cadena como
|
|
igor@473
|
259 ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
|
|
igor@473
|
260 \item[\tplkwfilt{node}{short}] Hash del conjunto de cambios. Muestra
|
|
igor@473
|
261 la forma corta de un hash de conjunto de cambios,
|
|
igor@473
|
262 of a changeset hash, p.e.~una cadena hexadecimal de 12 bytes.
|
|
igor@473
|
263 \item[\tplkwfilt{date}{shortdate}] \tplkword{date} palabra clave.
|
|
igor@473
|
264 Mostrar año, mes y día de una fecha. Muestrauna cadena como
|
|
igor@402
|
265 ``\Verb+2006-09-04+''.
|
|
igor@473
|
266 \item[\tplfilter{strip}] Cualquier texto. Elimina todos los espacios
|
|
igor@473
|
267 en blanco al principio y al final de la cadena.
|
|
igor@473
|
268 \item[\tplfilter{tabindent}] Cualquier texto. Muestra el texto con
|
|
igor@473
|
269 todas las líneas excepto la primera que comience con el caracter tab.
|
|
igor@473
|
270 \item[\tplfilter{urlescape}] Cualquier texto. Escapa todos los
|
|
igor@473
|
271 caracteres que se consideren como ``especiales'' por los parsers de
|
|
igor@473
|
272 URL. Por ejemplo, \Verb+foo bar+ se convierte en \Verb+foo%20bar+.
|
|
igor@473
|
273 \item[\tplkwfilt{author}{user}] Cualquier texto, útil sobre todo para
|
|
igor@473
|
274 la palabra clave \tplkword{author}. Retorna el ``usuario'' de una
|
|
igor@473
|
275 dirección de correo. Por ejemplo,
|
|
igor@473
|
276 ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' se convierte en
|
|
igor@402
|
277 ``\Verb+bos+''.
|
|
igor@402
|
278 \end{itemize}
|
|
igor@402
|
279
|
|
igor@402
|
280 \begin{figure}
|
|
igor@402
|
281 \interaction{template.simple.manyfilters}
|
|
igor@473
|
282 \caption{Filtros de plantilla en acción}
|
|
igor@402
|
283 \label{fig:template:filters}
|
|
igor@402
|
284 \end{figure}
|
|
igor@402
|
285
|
|
igor@402
|
286 \begin{note}
|
|
igor@473
|
287 Si trata de aplicar un filtro a una porción de datos que no puede
|
|
igor@473
|
288 procesarse, Mercurial fallará e imprimirá una excepción de Python.
|
|
igor@473
|
289 Por ejemplo, el tratar de usar la salida de la palabra clave
|
|
igor@473
|
290 \tplkword{desc} con el filtro \tplkwfilt{date}{isodate} no resultará
|
|
igor@473
|
291 algo útil.
|
|
igor@402
|
292 \end{note}
|
|
igor@402
|
293
|
|
igor@473
|
294 \subsection{Combinar filtros}
|
|
igor@473
|
295
|
|
igor@473
|
296 Combinar filtros es para generar una salida en la forma como usted lo
|
|
igor@473
|
297 desea es muy sencillo. La cadena de filtros siguientes arman una
|
|
igor@473
|
298 descripción, después aseguran que cabe limpiamente en 68 columnas, y
|
|
igor@473
|
299 las indenta con 8~caracteres (por lo menos en sistemas tipo Unix, en
|
|
igor@473
|
300 los que el tab por convención se extiende en 8~caracteres).
|
|
igor@402
|
301
|
|
igor@402
|
302 \interaction{template.simple.combine}
|
|
igor@402
|
303
|
|
igor@473
|
304 Observe el uso de ``\Verb+\t+'' (un caracter tab) en la plantilla para
|
|
igor@473
|
305 forzar que la primera línea se indente; esto es necesario para lograr
|
|
igor@473
|
306 que la primera línea luzca indentada; es necesario debido a que
|
|
igor@473
|
307 \tplkword{tabindent} indenta todas las líneas \emph{excepto} la primera.
|
|
igor@473
|
308
|
|
igor@473
|
309 Tenga en cuenta que el orden de los filtros importa. El primer filtro
|
|
igor@473
|
310 se aplica primero al resultado de la palabra clave; el segundo al
|
|
igor@473
|
311 resultado de la aplicación del primer filtro y así sucesivamente. Por
|
|
igor@473
|
312 ejemplo, usar \Verb+fill68|tabindent+ es muy distinto al resultado de
|
|
igor@473
|
313 usar \Verb+tabindent|fill68+.
|
|
igor@473
|
314
|
|
igor@473
|
315
|
|
igor@473
|
316 \section{De plantillas a estilos}
|
|
igor@473
|
317
|
|
igor@473
|
318 Una plantilla provee una forma rápida y sencilla para dar formato a
|
|
igor@473
|
319 una salida. Las plantillas pueden volvers verbosas, y es útil poder
|
|
igor@473
|
320 darle un nombre a una plantilla. Un fichero de estilo es una
|
|
igor@473
|
321 plantilla con un nombre, almacenado en un fichero.
|
|
igor@473
|
322
|
|
igor@473
|
323 Más aún, al usar un fichero de estilo se dispara el poder del motor de
|
|
igor@473
|
324 plantillas en un nivel imposible de alcanzar usando las opción
|
|
igor@473
|
325 \hgopt{log}{--template} desde la línea de órdenes.
|
|
igor@473
|
326
|
|
igor@473
|
327
|
|
igor@473
|
328 \subsection{Los ficheros de estilo más sencillos}
|
|
igor@473
|
329
|
|
igor@473
|
330 Nuestro fichero sencillo de estilo contiene una sola línea:
|
|
igor@402
|
331
|
|
igor@402
|
332 \interaction{template.simple.rev}
|
|
igor@402
|
333
|
|
igor@473
|
334 Se le indica a Mercurial, ``si está imprimiendo un conjunto de
|
|
igor@473
|
335 cambios, use el texto de la derecha como la plantilla''.
|
|
igor@473
|
336
|
|
igor@473
|
337 \subsection{Sintaxis de ficheros de estilo}
|
|
igor@473
|
338
|
|
igor@473
|
339 Las reglas de sintaxis para un fichero de estilo son sencillas:
|
|
igor@473
|
340
|
|
igor@473
|
341 \begin{itemize}
|
|
igor@473
|
342 \item El fichero se procesa línea por línea.
|
|
igor@473
|
343
|
|
igor@473
|
344 \item Se ignoran el espacio en blanco circundante.
|
|
igor@473
|
345
|
|
igor@473
|
346 \item Se omiten las líneas en blanco.
|
|
igor@473
|
347
|
|
igor@473
|
348 \item Si una línea comienza con los caracteres ``\texttt{\#}'' o
|
|
igor@473
|
349 ``\texttt{;}'', la línea completa se trata como un comentario, y se
|
|
igor@473
|
350 omite como si fuera vacía.
|
|
igor@473
|
351
|
|
igor@473
|
352 \item Una línea comienza con una palabra clave. Esta debe comenzar
|
|
igor@473
|
353 con una caracter alfabético o una raya al piso, y puede contener
|
|
igor@473
|
354 subsecuentemente cualquier caracter alfanumérico o una raya al
|
|
igor@473
|
355 piso. (En notación de expresiones regulares debe coincidir con
|
|
igor@473
|
356 \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
|
|
igor@473
|
357
|
|
igor@473
|
358 \item El próximo elemento debe ser un caracter ``\texttt{=}'', que
|
|
igor@473
|
359 puede estar precedido o seguido por una cantidad arbitraria de
|
|
igor@473
|
360 espacio.
|
|
igor@473
|
361
|
|
igor@473
|
362 \item Si el resto de la línea comienza y termina con caracteres
|
|
jerojasro@520
|
363 encerrados entre caracteres de comillas (bien sea sencillas o
|
|
igor@473
|
364 dobles), se trata como cuerpo de la plantilla.
|
|
igor@473
|
365
|
|
igor@473
|
366 \item Si el resto de la línea \emph{no} comienza con una comilla, se
|
|
igor@473
|
367 trata como el nombre de un fichero; los contenidos de este fichero
|
|
igor@473
|
368 se leerán y se usarán como cuerpo de la plantilla.
|
|
igor@473
|
369 \end{itemize}
|
|
igor@473
|
370
|
|
igor@473
|
371 \section{Ejemplos de ficheros de estilos}
|
|
igor@473
|
372
|
|
igor@473
|
373 Para ilustrar la creación de un fichero de estilo, construiremos
|
|
igor@473
|
374 algunos ejemplos. En lugar de ofrecer un fichero completo de estilo y
|
|
igor@473
|
375 analizarlo, replicaremos el proceso usual de desarrollo de un fichero
|
|
igor@473
|
376 de estilo comenzando con algo muy sencillo, y avanzando por una serie
|
|
igor@473
|
377 de ejemplos sucesivos más completos.
|
|
igor@473
|
378
|
|
igor@473
|
379 \subsection{Identificar equivocaciones en ficheros de estilo}
|
|
igor@473
|
380
|
|
igor@473
|
381 Si Mercurial encuentra un problema en un fichero de estilo en el cual
|
|
igor@473
|
382 usted está trabajando, imprime un mensaje de error suscinto, cuando
|
|
igor@473
|
383 usted identifique lo que significa, resulta muy útil.
|
|
igor@402
|
384
|
|
igor@402
|
385 \interaction{template.svnstyle.syntax.input}
|
|
igor@402
|
386
|
|
igor@473
|
387 Tenga en cuenta que \filename{broken.style} trata de definir la
|
|
igor@473
|
388 palabra clave \texttt{changeset}, pero omite dar un contenido para esta.
|
|
igor@473
|
389 Cuando se le indica a Mercurial que use este fichero de estilo, se
|
|
igor@473
|
390 queja inmediatamente.
|
|
igor@402
|
391
|
|
igor@402
|
392 \interaction{template.svnstyle.syntax.error}
|
|
igor@402
|
393
|
|
igor@473
|
394 Este mensaje de error luce intimidante, pero no es muy difícil de
|
|
igor@473
|
395 seguir:
|
|
igor@473
|
396
|
|
igor@473
|
397 \begin{itemize}
|
|
igor@473
|
398 \item El primer componente es la forma como Mercurial dice ``me rindo''.
|
|
igor@402
|
399 \begin{codesample4}
|
|
igor@402
|
400 \textbf{abort:} broken.style:1: parse error
|
|
igor@402
|
401 \end{codesample4}
|
|
igor@402
|
402
|
|
igor@473
|
403 \item A continuación viene el nombre del fichero que contiene el error.
|
|
igor@402
|
404 \begin{codesample4}
|
|
igor@402
|
405 abort: \textbf{broken.style}:1: parse error
|
|
igor@402
|
406 \end{codesample4}
|
|
igor@402
|
407
|
|
igor@473
|
408 \item Siguendo el nombre del fichero viene el número de línea en la
|
|
igor@473
|
409 que se encontró el error.
|
|
igor@402
|
410 \begin{codesample4}
|
|
igor@402
|
411 abort: broken.style:\textbf{1}: parse error
|
|
igor@402
|
412 \end{codesample4}
|
|
igor@402
|
413
|
|
igor@473
|
414 \item Finalmente, la descripción de lo que falló.
|
|
igor@402
|
415 \begin{codesample4}
|
|
igor@402
|
416 abort: broken.style:1: \textbf{parse error}
|
|
igor@402
|
417 \end{codesample4}
|
|
jerojasro@520
|
418 La descripción del problema no siempre es clara (como en este caso),
|
|
igor@473
|
419 pero aunque sea críptica, casi siempre es trivial la inspección
|
|
igor@473
|
420 visual de la línea en el fichero de estilo y encontrar lo que está
|
|
igor@473
|
421 mal.
|
|
igor@473
|
422 \end{itemize}
|
|
igor@473
|
423
|
|
igor@473
|
424 \subsection{Identificar de forma única un repositorio}
|
|
igor@473
|
425
|
|
igor@473
|
426 Si desea identificar un repositorio de Mercurial ``de forma única''
|
|
igor@473
|
427 con una cadena corta como identificador, puede usar la primera
|
|
igor@473
|
428 revisión en el repositorio.
|
|
igor@402
|
429 \interaction{template.svnstyle.id}
|
|
igor@473
|
430 No es garantía de unicidad, pero no es útill en ciertos casos:
|
|
igor@402
|
431 many cases.
|
|
igor@402
|
432 \begin{itemize}
|
|
igor@473
|
433 \item No funcionará en un repositorio completamente vacío, porque un
|
|
igor@473
|
434 repositorio así no tiene una revisión~zero.
|
|
jerojasro@520
|
435 \item Tampoco funcionará en caso (muy raro) cuando el repositorio sea
|
|
igor@473
|
436 una fusión de dos repositorios independientes y tiene los dos
|
|
igor@473
|
437 directorios por ahí.
|
|
igor@473
|
438 \end{itemize}
|
|
igor@473
|
439 Hay ciertos casos en los cuales podría colocar el identificador:
|
|
igor@473
|
440 \begin{itemize}
|
|
igor@473
|
441 \item Como una llave en la tabla de una base de datos que administra
|
|
igor@473
|
442 repositorios en un servidor.
|
|
igor@473
|
443 \item Como una parte del par \{\emph{ID~repositorio}, \emph{ID~revisión}\}.
|
|
igor@473
|
444 Almacene esta información de forma independiente cuando ejecute
|
|
igor@473
|
445 construcciones automatizadas u otras actividades, de forma que pueda
|
|
igor@473
|
446 ``reconstruir'' posteriormente en caso de ser necesario.
|
|
igor@473
|
447 \end{itemize}
|
|
igor@473
|
448
|
|
igor@473
|
449 \subsection{Mostrando salida parecida a Subversion}
|
|
igor@473
|
450
|
|
igor@473
|
451 Intentemos emular la salida usual que usa otro sistema de control de
|
|
igor@473
|
452 revisiones, Subversion.
|
|
igor@402
|
453 \interaction{template.svnstyle.short}
|
|
igor@402
|
454
|
|
igor@473
|
455 Dado que la salida de Subversion es sencilla, es fácil copiar y pegar
|
|
igor@473
|
456 una porción de su salida en un fichero, y reemplazar el texto
|
|
igor@473
|
457 producido previamente por Subversion con valores base que quisiéramos
|
|
igor@473
|
458 ver expandidos.
|
|
igor@402
|
459 \interaction{template.svnstyle.template}
|
|
igor@402
|
460
|
|
igor@473
|
461 Esta plantilla difiere en algunos detalles de la salida producida por
|
|
igor@473
|
462 Subversion:
|
|
igor@473
|
463 \begin{itemize}
|
|
igor@473
|
464 \item Subversion imprime una fecha ``legible'' (el ``\texttt{Wed, 27 Sep
|
|
igor@473
|
465 2006}'' en el ejemplo de salida anterior) en paréntesis. El motor
|
|
igor@473
|
466 de plantillas de Mercurial no ofrece una forma sencilla de desplegar
|
|
igor@473
|
467 una fecha en este formato sin imprimir también la hora y la zona horaria.
|
|
igor@473
|
468 \item Emulamos las líneas de ``separación'' de subversion con caracteres
|
|
igor@473
|
469 ``\texttt{-}'' en una línea. Usamos la palabra clave
|
|
igor@473
|
470 \tplkword{header} del motor de plantillas para imprimir una línea de
|
|
jerojasro@520
|
471 separación como la primera línea de salida (ver más abajo), para
|
|
igor@473
|
472 lograr una salida similara a la de Subversion.
|
|
igor@473
|
473 \item La salida de subversion incluye un conteo en el encabezado del
|
|
igor@473
|
474 número de líneas en el mensaje de consinación. No podemos
|
|
igor@473
|
475 replicarlo en Mercurial; el motor de plantilla no ofrece en la
|
|
igor@473
|
476 actualidad un filtro que cuente la cantidad de objetos que se le
|
|
igor@473
|
477 pasen.
|
|
igor@473
|
478 \end{itemize}
|
|
igor@473
|
479 No me tomó más de un minuto o dos de trabajo para reemplazar texto
|
|
igor@473
|
480 literal de un ejemplo de salida de la salida de Subversion con ciertas
|
|
igor@473
|
481 palabras claves y filtros para ofrecer la plantilla anterior. El
|
|
igor@473
|
482 fichero de estilo se refiere sencillamente a la plantilla.
|
|
igor@402
|
483 \interaction{template.svnstyle.style}
|
|
igor@402
|
484
|
|
igor@473
|
485 Podríamos haber incluído el texto del fichero plantilla directamente
|
|
igor@473
|
486 en el fichero de estilo encerrando entre comillas y reemplazando las
|
|
igor@473
|
487 nuevas líneas con secuencias ``\verb!\n!'', pero haría muy difícil de
|
|
jerojasro@516
|
488 leer el fichero de estilos. La facilidad para leer es importante
|
|
igor@473
|
489 cuando está decidiendo si un texto pertenece a un fichero de estilo o
|
|
igor@473
|
490 a un fichero de plantilla incluído en el estilo. Si el fichero de
|
|
igor@473
|
491 estilo luce muy grande o complicado, si inserta una pieza de texto
|
|
igor@473
|
492 literal, mejor colóquelo en una plantilla.
|
|
igor@402
|
493
|
|
igor@402
|
494 %%% Local Variables:
|
|
igor@402
|
495 %%% mode: latex
|
|
igor@402
|
496 %%% TeX-master: "00book"
|
|
igor@402
|
497 %%% End:
|
