igor@470: \chapter{Personalizar los mensajes de Mercurial}
igor@402: \label{chap:template}
igor@402: 
igor@470: Mercurial provee un poderoso mecanismo que permite controlar como
igor@470: despliega la información.  El mecanismo se basa en plantillas.  Puede
igor@470: usar plantillas para generar salida específica para una orden
igor@470: particular o para especificar la visualización completa de la interfaz
igor@470: web embebida.
igor@470: 
igor@470: \section{Usar estilos que vienen con Mercurial}
igor@402: \label{sec:style}
igor@402: 
igor@470: Hay ciertos estilos listos que vienen con Mercurial.  Un estilo es
igor@470: simplemente una plantilla predeterminada que alguien escribió e
igor@470: instaló en un sitio en el cual Mercurial puede encontrarla.
igor@470: 
igor@470: Antes de dar un vistazo a los estilos que trae Mercurial, revisemos su
igor@470: salida usual.
igor@402: 
igor@402: \interaction{template.simple.normal}
igor@402: 
igor@470: Es en cierta medida informativa, pero ocupa mucho espacio---cinco
igor@470: líneas de salida por cada conjunto de cambios.  El estilo
igor@470: \texttt{compact} lo reduce a tres líneas, presentadas de forma
igor@470: suscinta.
igor@402: 
igor@402: \interaction{template.simple.compact}
igor@402: 
igor@470: El estilo de la \texttt{bitácora de cambios} vislumbra el poder
igor@470: expresivo del sistema de plantillas de Mercurial.  Este estilo busca
igor@470: seguir los estándares de bitácora de cambios del proyecto
igor@470: GNU\cite{web:changelog}.
igor@402: 
igor@402: \interaction{template.simple.changelog}
igor@402: 
igor@470: No es una sorpresa que el estilo predeterminado de Mercurial se llame
igor@470: \texttt{default}\ndt{predeterminado}.
igor@470: 
igor@470: \subsection{Especificar un estilo predeterminado}
igor@470: 
igor@470: Puede modificar el estilo de presentación que Mercurial usará para
igor@470: toda orden vía el fichero \hgrc\, indicando el estilo que prefiere
igor@470: usar.
igor@402: 
igor@402: \begin{codesample2}
igor@402:   [ui]
igor@402:   style = compact
igor@402: \end{codesample2}
igor@402: 
igor@470: Si escribe un estilo, puede usarlo bien sea proveyendo la ruta a su
igor@470: fichero de estilo o copiando su fichero de estilo a un lugar en el
igor@470: cual Mercurial pueda encontrarlo(típicamente el subdirectorio
igor@470: \texttt{templates} de su directorio de instalación de Mercurial).
igor@470: 
igor@470: \section{Órdenes que soportan estilos y plantillas}
igor@470: 
igor@470: Todas las órdenes de Mercurial``relacionadas con \texttt{log}'' le
igor@470: permiten usar estilos y plantillas: \hgcmd{incoming}, \hgcmd{log},
igor@470: \hgcmd{outgoing} y \hgcmd{tip}.
igor@470: 
igor@470: Al momento de la escritura del manual estas son las únicas órdenes que
igor@470: soportan estilos y plantillas.  Dado que son las órdenes más
igor@470: importantes que necesitan personalización, no ha habido muchas
igor@470: solicitudes desde la comunidad de usuarios de Mercurial para añadir
igor@470: soporte de plantillas y estilos a otras órdenes.
igor@470: 
igor@470: \section{Cuestiones básicas de plantillas}
igor@470: 
igor@470: Una plantilla de Mercurial es sencillamente una pieza de texto.
igor@470: Cierta porción nunca cambia, otras partes se \emph{expanden}, o
igor@470: reemplazan con texto nuevo cuando es necesario.
igor@470: 
igor@470: Antes de continuar, veamos de nuevo un ejemplo sencillo de la salida
igor@470: usual de Mercurial:
igor@402: 
igor@402: \interaction{template.simple.normal}
igor@402: 
igor@470: Ahora, ejecutemos la misma orden, pero usemos una plantilla para
igor@470: modificar su salida:
igor@402: 
igor@402: \interaction{template.simple.simplest}
igor@402: 
igor@470: El ejemplo anterior ilustra la plantilla más sencilla posible;  es
igor@470: solamente una porción estática de código que se imprime una vez por
igor@470: cada conjunto de cambios.  La opción \hgopt{log}{--template} de la
igor@470: orden \hgcmd{log} indica a Mercurial usar el texto dado como la
igor@470: plantilla cuando se imprime cada conjunto de cambios.
igor@470: 
igor@470: Observe que la cadena de plantilla anterior termina con el texto
igor@470: ``\Verb+\n+''.  Es una \emph{secuencia de control}, que le indica a
igor@470: Mercurial imprimira una nueva línea al final de cada objeto de la
igor@470: plantilla.  Si omite esta nueva línea, Mercurial colocará cada pieza
igor@470: de salida seguida.  Si desea más detalles acerca de secuencias de
igor@470: control, vea la sección~\ref{sec:template:escape}.
igor@470: 
igor@470: Una plantilla que imprime una cadena fija de texto siempre no es muy
igor@470: útil; intentemos algo un poco más complejo.
igor@402: 
igor@402: \interaction{template.simple.simplesub}
igor@402: 
igor@470: Como puede ver, la cadena ``\Verb+{desc}+'' en la plantilla ha sido
igor@470: reemplazada en la salida con la descricipción de cada conjunto de
igor@470: cambios.  Cada vez que Mercurial encuentra texto encerrado entre
igor@470: corchetes(``\texttt{\{}'' y ``\texttt{\}}''), intentará reemplazar los
igor@470: corchetes y el texto con la expansión de lo que sea está adentro.
igor@470: Para imprimir un corchete de forma literal, debe escaparlo, como se
igor@470: describe en la sección~\ref{sec:template:escape}.
igor@470: 
igor@470: \section{Palabras claves más comunes en las plantillas}
igor@402: \label{sec:template:keyword}
igor@402: 
igor@470: Puede empezar a escribir plantillas sencillas rápidamente con las
igor@470: palabras claves descritas a continuación:
igor@470: 
igor@470: \begin{itemize}
igor@470: \item[\tplkword{author}] Cadena.  El autor NO modificado del conjunto
igor@470:   de cambios.
igor@470: \item[\tplkword{branches}] Cadena.  El nombre de la rama en la cual se
igor@470:   consignó el conjunto de cambios.  Será vacía si el nombre de la rama es
igor@402:   \texttt{default}.
igor@470: \item[\tplkword{date}] Información de fecha.  La fecha en la cual se
igor@470:   consignó el conjunto de cambios.  \emph{No} es legible por un
igor@470:   humano, debe pasarla por un firltro que la desplegará
igor@470:   apropiadamente.  En la sección~\ref{sec:template:filter} hay más
igor@470:   detalles acerca de filtros.  La fecha se expresa como un par de
igor@470:   números.  El primer número corresponde a una marca de tiempo UNIX
igor@470:   UTC(segundos desde el primero de enero de 1970); la segunda es el
igor@470:   corrimiento horario de la zona horaria del UTC en la cual se encontraba
igor@470:   quien hizo la consignación, en segundos.
igor@470: \item[\tplkword{desc}] Cadena.  La descripción en texto del conjunto
igor@470:   de cambios.
igor@470: \item[\tplkword{files}] Lista de cadenas.  Todos los ficheros
igor@470:   modificados, adicionados o eliminados por este conjunto de cambios.
igor@470: \item[\tplkword{file\_adds}] Lista de cadenas.  Ficheros adicionados
igor@470:   por este conjunto de cambios.
igor@470: \item[\tplkword{file\_dels}] Lista de cadenas.  Ficheros eliminados
igor@470:   por este conjunto de cambios.
igor@470: \item[\tplkword{node}] Cadena.  El hash de identificación de este
igor@470:   conjunto de cambios como una cadena hexadecimal de 40 caracteres.
igor@470: \item[\tplkword{parents}] Lista de cadenas.  Los ancestros del
igor@470:   conjunto de cambios.
igor@470: \item[\tplkword{rev}] Entero.  El número de revisión del repositorio
igor@470:   local.
igor@470: \item[\tplkword{tags}] Lista de cadenas.  Todas las etiquetas
igor@470:   asociadas al conjunto de cambios.
igor@470: \end{itemize}
igor@470: 
igor@470: Unos experimentos sencillos nos mostrarán qué esperar cuando usamos
igor@470: estas palabras claves; puede ver los resultados en la
igor@470: figura~\ref{fig:template:keywords}.
igor@402: 
igor@402: \begin{figure}
igor@402:   \interaction{template.simple.keywords}
igor@402:   \caption{Template keywords in use}
igor@402:   \label{fig:template:keywords}
igor@402: \end{figure}
igor@402: 
igor@470: Como mencionamos anteriormente, la palabra clave de fecha no produce
igor@470: salida legible por un humano, debemos tratarla de forma especial.
igor@470: Esto involucra usar un \emph{filtro}, acerca de lo cual hay más en la
igor@470: sección~\ref{sec:template:filter}.
igor@402: 
igor@402: \interaction{template.simple.datekeyword}
igor@402: 
igor@470: \section{Secuencias de Control}
igor@402: \label{sec:template:escape}
igor@402: 
igor@470: El motor de plantillas de Mercurial reconoce las secuencias de control
igor@470: más comunmente usadas dentro de las cadenas.  Cuando ve un backslash
igor@470: (``\Verb+\+''), ve el caracter siguiente y sustituye los dos
igor@470: caracteres con un reemplazo sencillo, como se describe a continuación:
igor@402: 
igor@402: \begin{itemize}
igor@402: \item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
igor@402:   ASCII~134.
igor@470: \item[\Verb+\textbackslash n+] Nueva línea, ASCII~12.
igor@470: \item[\Verb+\textbackslash r+] Cambio de línea, ASCII~15.
igor@402: \item[\Verb+\textbackslash t+] Tab, ASCII~11.
igor@470: \item[\Verb+\textbackslash v+] Tab Vertical, ASCII~13.
igor@470: \item[\Verb+\textbackslash \{+] Corchete abierto, ``\Verb+{+'', ASCII~173.
igor@470: \item[\Verb+\textbackslash \}+] Corchete cerrado, ``\Verb+}+'', ASCII~175.
igor@470: \end{itemize}
igor@470: 
igor@470: Como se indicó arriba, si desea que la expansión en una plantilla
igor@470: contenga un caracter literal ``\Verb+\+'', ``\Verb+{+'', o
igor@470:   ``\Verb+{+'', debe escaparlo.
igor@470: 
igor@470: \section{Uso de filtros con palabras claves}
igor@402: \label{sec:template:filter}
igor@402: 
igor@470: Algunos de los resultados de la expansión de la plantilla no son
igor@470: fáciles de usar de inmediato.  Mercurial le permite especificar una
igor@470: cadena de \emph{filtros} opcionales para modificar el resultado de
igor@470: expandir una palabra clave.  Ya ha visto el filtro usual
igor@470: \tplkwfilt{date}{isodate} en acción con anterioridad para hacer
igor@470: legible la fecha.
igor@470: 
igor@470: A continuación hay una lista de los filtros de Mercurial más
igor@470: comunmente usados.  Ciertos filtros pueden aplicarse a cualquier
igor@470: texto, otros pueden usarse únicamente en circunstancias específicas.
igor@470: El nombre de cada filtro está seguido de la indicación de dónde puede
igor@470: ser usado y una descripción de su efecto.
igor@470: 
igor@470: \begin{itemize}
igor@470: \item[\tplfilter{addbreaks}] Cualquier texto. Añade una etiqueta XHTML
igor@470:   ``\Verb+<br/>+'' antes del final de cada línea excepto en la final.
igor@470:   Por ejemplo, ``\Verb+foo\nbar+'' se convierte en ``\Verb+foo<br/>\nbar+''.
igor@470: \item[\tplkwfilt{date}{age}] palabra clave \tplkword{date}.  Muestra
igor@470:   la edad de la fecha, relativa al tiempo actual. Ofrece una cadena como
igor@402:   ``\Verb+10 minutes+''.
igor@470: \item[\tplfilter{basename}] Cualquier texto, pero de utilidad sobre
igor@470:   todo en palabras claves relativas a \tplkword{ficheros}.  Trata el
igor@470:   texto como una ruta, retornando el nombre base.  Por ejemplo,
igor@470:   ``\Verb+foo/bar/baz+'', se convierte en ``\Verb+baz+''.
igor@402: \item[\tplkwfilt{date}{date}] \tplkword{date} keyword.  Render a date
igor@402:   in a similar format to the Unix \tplkword{date} command, but with
igor@402:   timezone included.  Yields a string like
igor@402:   ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
igor@402: \item[\tplkwfilt{author}{domain}] Any text, but most useful for the
igor@402:   \tplkword{author} keyword.  Finds the first string that looks like
igor@402:   an email address, and extract just the domain component.  For
igor@402:   example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
igor@402:   ``\Verb+serpentine.com+''.
igor@402: \item[\tplkwfilt{author}{email}] Any text, but most useful for the
igor@402:   \tplkword{author} keyword.  Extract the first string that looks like
igor@402:   an email address.  For example,
igor@402:   ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
igor@402:   ``\Verb+bos@serpentine.com+''.
igor@402: \item[\tplfilter{escape}] Any text.  Replace the special XML/XHTML
igor@402:   characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with
igor@402:   XML entities.
igor@402: \item[\tplfilter{fill68}] Any text.  Wrap the text to fit in 68
igor@402:   columns.  This is useful before you pass text through the
igor@402:   \tplfilter{tabindent} filter, and still want it to fit in an
igor@402:   80-column fixed-font window.
igor@402: \item[\tplfilter{fill76}] Any text.  Wrap the text to fit in 76
igor@402:   columns.
igor@402: \item[\tplfilter{firstline}] Any text.  Yield the first line of text,
igor@402:   without any trailing newlines.
igor@402: \item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword.  Render the
igor@402:   date as a pair of readable numbers.  Yields a string like
igor@402:   ``\Verb+1157407993 25200+''.
igor@402: \item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword.  Render the
igor@402:   date as a text string in ISO~8601 format.  Yields a string like
igor@402:   ``\Verb+2006-09-04 15:13:13 -0700+''.
igor@402: \item[\tplfilter{obfuscate}] Any text, but most useful for the
igor@402:   \tplkword{author} keyword.  Yield the input text rendered as a
igor@402:   sequence of XML entities.  This helps to defeat some particularly
igor@402:   stupid screen-scraping email harvesting spambots.
igor@402: \item[\tplkwfilt{author}{person}] Any text, but most useful for the
igor@402:   \tplkword{author} keyword.  Yield the text before an email address.
igor@402:   For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+''
igor@402:   becomes ``\Verb+Bryan O'Sullivan+''.
igor@402: \item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword.  Render a
igor@402:   date using the same format used in email headers.  Yields a string
igor@402:   like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''.
igor@402: \item[\tplkwfilt{node}{short}] Changeset hash.  Yield the short form
igor@402:   of a changeset hash, i.e.~a 12-byte hexadecimal string.
igor@402: \item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword.  Render
igor@402:   the year, month, and day of the date.  Yields a string like
igor@402:   ``\Verb+2006-09-04+''.
igor@402: \item[\tplfilter{strip}] Any text.  Strip all leading and trailing
igor@402:   whitespace from the string.
igor@402: \item[\tplfilter{tabindent}] Any text.  Yield the text, with every line
igor@402:   except the first starting with a tab character.
igor@402: \item[\tplfilter{urlescape}] Any text.  Escape all characters that are
igor@402:   considered ``special'' by URL parsers.  For example, \Verb+foo bar+
igor@402:   becomes \Verb+foo%20bar+.
igor@402: \item[\tplkwfilt{author}{user}] Any text, but most useful for the
igor@402:   \tplkword{author} keyword.  Return the ``user'' portion of an email
igor@402:   address.  For example,
igor@402:   ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes
igor@402:   ``\Verb+bos+''.
igor@402: \end{itemize}
igor@402: 
igor@402: \begin{figure}
igor@402:   \interaction{template.simple.manyfilters}
igor@402:   \caption{Template filters in action}
igor@402:   \label{fig:template:filters}
igor@402: \end{figure}
igor@402: 
igor@402: \begin{note}
igor@402:   If you try to apply a filter to a piece of data that it cannot
igor@402:   process, Mercurial will fail and print a Python exception.  For
igor@402:   example, trying to run the output of the \tplkword{desc} keyword
igor@402:   into the \tplkwfilt{date}{isodate} filter is not a good idea.
igor@402: \end{note}
igor@402: 
igor@402: \subsection{Combining filters}
igor@402: 
igor@402: It is easy to combine filters to yield output in the form you would
igor@402: like.  The following chain of filters tidies up a description, then
igor@402: makes sure that it fits cleanly into 68 columns, then indents it by a
igor@402: further 8~characters (at least on Unix-like systems, where a tab is
igor@402: conventionally 8~characters wide).
igor@402: 
igor@402: \interaction{template.simple.combine}
igor@402: 
igor@402: Note the use of ``\Verb+\t+'' (a tab character) in the template to
igor@402: force the first line to be indented; this is necessary since
igor@402: \tplkword{tabindent} indents all lines \emph{except} the first.
igor@402: 
igor@402: Keep in mind that the order of filters in a chain is significant.  The
igor@402: first filter is applied to the result of the keyword; the second to
igor@402: the result of the first filter; and so on.  For example, using
igor@402: \Verb+fill68|tabindent+ gives very different results from
igor@402: \Verb+tabindent|fill68+.
igor@402: 
igor@402: 
igor@402: \section{From templates to styles}
igor@402: 
igor@402: A command line template provides a quick and simple way to format some
igor@402: output.  Templates can become verbose, though, and it's useful to be
igor@402: able to give a template a name.  A style file is a template with a
igor@402: name, stored in a file.
igor@402: 
igor@402: More than that, using a style file unlocks the power of Mercurial's
igor@402: templating engine in ways that are not possible using the command line
igor@402: \hgopt{log}{--template} option.
igor@402: 
igor@402: \subsection{The simplest of style files}
igor@402: 
igor@402: Our simple style file contains just one line:
igor@402: 
igor@402: \interaction{template.simple.rev}
igor@402: 
igor@402: This tells Mercurial, ``if you're printing a changeset, use the text
igor@402: on the right as the template''.
igor@402: 
igor@402: \subsection{Style file syntax}
igor@402: 
igor@402: The syntax rules for a style file are simple.
igor@402: 
igor@402: \begin{itemize}
igor@402: \item The file is processed one line at a time.
igor@402: 
igor@402: \item Leading and trailing white space are ignored.
igor@402: 
igor@402: \item Empty lines are skipped.
igor@402: 
igor@402: \item If a line starts with either of the characters ``\texttt{\#}'' or
igor@402:   ``\texttt{;}'', the entire line is treated as a comment, and skipped
igor@402:   as if empty.
igor@402: 
igor@402: \item A line starts with a keyword.  This must start with an
igor@402:   alphabetic character or underscore, and can subsequently contain any
igor@402:   alphanumeric character or underscore.  (In regexp notation, a
igor@402:   keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.)
igor@402: 
igor@402: \item The next element must be an ``\texttt{=}'' character, which can
igor@402:   be preceded or followed by an arbitrary amount of white space.
igor@402: 
igor@402: \item If the rest of the line starts and ends with matching quote
igor@402:   characters (either single or double quote), it is treated as a
igor@402:   template body.
igor@402: 
igor@402: \item If the rest of the line \emph{does not} start with a quote
igor@402:   character, it is treated as the name of a file; the contents of this
igor@402:   file will be read and used as a template body.
igor@402: \end{itemize}
igor@402: 
igor@402: \section{Style files by example}
igor@402: 
igor@402: To illustrate how to write a style file, we will construct a few by
igor@402: example.  Rather than provide a complete style file and walk through
igor@402: it, we'll mirror the usual process of developing a style file by
igor@402: starting with something very simple, and walking through a series of
igor@402: successively more complete examples.
igor@402: 
igor@402: \subsection{Identifying mistakes in style files}
igor@402: 
igor@402: If Mercurial encounters a problem in a style file you are working on,
igor@402: it prints a terse error message that, once you figure out what it
igor@402: means, is actually quite useful.
igor@402: 
igor@402: \interaction{template.svnstyle.syntax.input}
igor@402: 
igor@402: Notice that \filename{broken.style} attempts to define a
igor@402: \texttt{changeset} keyword, but forgets to give any content for it.
igor@402: When instructed to use this style file, Mercurial promptly complains.
igor@402: 
igor@402: \interaction{template.svnstyle.syntax.error}
igor@402: 
igor@402: This error message looks intimidating, but it is not too hard to
igor@402: follow.
igor@402: 
igor@402: \begin{itemize}
igor@402: \item The first component is simply Mercurial's way of saying ``I am
igor@402:   giving up''.
igor@402:   \begin{codesample4}
igor@402:     \textbf{abort:} broken.style:1: parse error
igor@402:   \end{codesample4}
igor@402: 
igor@402: \item Next comes the name of the style file that contains the error.
igor@402:   \begin{codesample4}
igor@402:     abort: \textbf{broken.style}:1: parse error
igor@402:   \end{codesample4}
igor@402: 
igor@402: \item Following the file name is the line number where the error was
igor@402:   encountered.
igor@402:   \begin{codesample4}
igor@402:     abort: broken.style:\textbf{1}: parse error
igor@402:   \end{codesample4}
igor@402: 
igor@402: \item Finally, a description of what went wrong.
igor@402:   \begin{codesample4}
igor@402:     abort: broken.style:1: \textbf{parse error}
igor@402:   \end{codesample4}
igor@402:   The description of the problem is not always clear (as in this
igor@402:   case), but even when it is cryptic, it is almost always trivial to
igor@402:   visually inspect the offending line in the style file and see what
igor@402:   is wrong.
igor@402: \end{itemize}
igor@402: 
igor@402: \subsection{Uniquely identifying a repository}
igor@402: 
igor@402: If you would like to be able to identify a Mercurial repository
igor@402: ``fairly uniquely'' using a short string as an identifier, you can
igor@402: use the first revision in the repository.
igor@402: \interaction{template.svnstyle.id} 
igor@402: This is not guaranteed to be unique, but it is nevertheless useful in
igor@402: many cases.
igor@402: \begin{itemize}
igor@402: \item It will not work in a completely empty repository, because such
igor@402:   a repository does not have a revision~zero.
igor@402: \item Neither will it work in the (extremely rare) case where a
igor@402:   repository is a merge of two or more formerly independent
igor@402:   repositories, and you still have those repositories around.
igor@402: \end{itemize}
igor@402: Here are some uses to which you could put this identifier:
igor@402: \begin{itemize}
igor@402: \item As a key into a table for a database that manages repositories
igor@402:   on a server.
igor@402: \item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple.
igor@402:   Save this information away when you run an automated build or other
igor@402:   activity, so that you can ``replay'' the build later if necessary.
igor@402: \end{itemize}
igor@402: 
igor@402: \subsection{Mimicking Subversion's output}
igor@402: 
igor@402: Let's try to emulate the default output format used by another
igor@402: revision control tool, Subversion.
igor@402: \interaction{template.svnstyle.short}
igor@402: 
igor@402: Since Subversion's output style is fairly simple, it is easy to
igor@402: copy-and-paste a hunk of its output into a file, and replace the text
igor@402: produced above by Subversion with the template values we'd like to see
igor@402: expanded.
igor@402: \interaction{template.svnstyle.template}
igor@402: 
igor@402: There are a few small ways in which this template deviates from the
igor@402: output produced by Subversion.
igor@402: \begin{itemize}
igor@402: \item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep
igor@402:     2006}'' in the example output above) in parentheses.  Mercurial's
igor@402:   templating engine does not provide a way to display a date in this
igor@402:   format without also printing the time and time zone.
igor@402: \item We emulate Subversion's printing of ``separator'' lines full of
igor@402:   ``\texttt{-}'' characters by ending the template with such a line.
igor@402:   We use the templating engine's \tplkword{header} keyword to print a
igor@402:   separator line as the first line of output (see below), thus
igor@402:   achieving similar output to Subversion.
igor@402: \item Subversion's output includes a count in the header of the number
igor@402:   of lines in the commit message.  We cannot replicate this in
igor@402:   Mercurial; the templating engine does not currently provide a filter
igor@402:   that counts the number of items it is passed.
igor@402: \end{itemize}
igor@402: It took me no more than a minute or two of work to replace literal
igor@402: text from an example of Subversion's output with some keywords and
igor@402: filters to give the template above.  The style file simply refers to
igor@402: the template.
igor@402: \interaction{template.svnstyle.style}
igor@402: 
igor@402: We could have included the text of the template file directly in the
igor@402: style file by enclosing it in quotes and replacing the newlines with
igor@402: ``\verb!\n!'' sequences, but it would have made the style file too
igor@402: difficult to read.  Readability is a good guide when you're trying to
igor@402: decide whether some text belongs in a style file, or in a template
igor@402: file that the style file points to.  If the style file will look too
igor@402: big or cluttered if you insert a literal piece of text, drop it into a
igor@402: template instead.
igor@402: 
igor@402: %%% Local Variables: 
igor@402: %%% mode: latex
igor@402: %%% TeX-master: "00book"
igor@402: %%% End: