hgbook
annotate es/template.tex @ 520:bbc5db74bd77
changed many "X(" for "X ("
I did this only when inside the main text
I did this only when inside the main text
author | Javier Rojas <jerojasro@devnull.li> |
---|---|
date | Sun Jan 18 22:31:20 2009 -0500 (2009-01-18) |
parents | 9da096de3c52 |
children | 801442e58e6d |
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. |
igor@473 | 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: |