comparison es/template.tex @ 569:012631b248de

translated some templates chapter paragraphs

559:a1b640641d37

\chapter{Customising the output of Mercurial}
\label{chap:template}

Mercurial provides a powerful mechanism to let you control how it
displays information.  The mechanism is based on templates.  You can
use templates to generate specific output for a single command, or to
customise the entire appearance of the built-in web interface.

\section{Using precanned output styles}
\label{sec:style}

Packaged with Mercurial are some output styles that you can use
immediately.  A style is simply a precanned template that someone
wrote and installed somewhere that Mercurial can find.

Before we take a look at Mercurial's bundled styles, let's review its
normal output.

\interaction{template.simple.normal}

This is somewhat informative, but it takes up a lot of space---five
lines of output per changeset.  The \texttt{compact} style reduces
this to three lines, presented in a sparse manner.

\interaction{template.simple.compact}

The \texttt{changelog} style hints at the expressive power of
Mercurial's templating engine.  This style attempts to follow the GNU
Project's changelog guidelines\cite{web:changelog}.

\interaction{template.simple.changelog}

You will not be shocked to learn that Mercurial's default output style
is named \texttt{default}.

\subsection{Setting a default style}

You can modify the output style that Mercurial will use for every
command by editing your \hgrc\ file, naming the style you would
prefer to use.

\begin{codesample2}
  [ui]
  style = compact
\end{codesample2}

If you write a style of your own, you can use it by either providing
the path to your style file, or copying your style file into a
location where Mercurial can find it (typically the \texttt{templates}
subdirectory of your Mercurial install directory).

\section{Commands that support styles and templates}

All of Mercurial's ``\texttt{log}-like'' commands let you use styles
and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and
\hgcmd{tip}.

As I write this manual, these are so far the only commands that
support styles and templates.  Since these are the most important
commands that need customisable output, there has been little pressure
from the Mercurial user community to add style and template support to
other commands.

\section{The basics of templating}

At its simplest, a Mercurial template is a piece of text.  Some of the
text never changes, while other parts are \emph{expanded}, or replaced
with new text, when necessary.

Before we continue, let's look again at a simple example of
Mercurial's normal output.

\interaction{template.simple.normal}

Now, let's run the same command, but using a template to change its
output.

\interaction{template.simple.simplest}

The example above illustrates the simplest possible template; it's
just a piece of static text, printed once for each changeset.  The
\hgopt{log}{--template} option to the \hgcmd{log} command tells
Mercurial to use the given text as the template when printing each
changeset.

Notice that the template string above ends with the text
``\Verb+\n+''.  This is an \emph{escape sequence}, telling Mercurial
to print a newline at the end of each template item.  If you omit this
newline, Mercurial will run each piece of output together.  See
section~\ref{sec:template:escape} for more details of escape sequences.

A template that prints a fixed string of text all the time isn't very
useful; let's try something a bit more complex.

\interaction{template.simple.simplesub}

As you can see, the string ``\Verb+{desc}+'' in the template has been
replaced in the output with the description of each changeset.  Every
time Mercurial finds text enclosed in curly braces (``\texttt{\{}''
and ``\texttt{\}}''), it will try to replace the braces and text with
the expansion of whatever is inside.  To print a literal curly brace,
you must escape it, as described in section~\ref{sec:template:escape}.

\section{Common template keywords}
\label{sec:template:keyword}

You can start writing simple templates immediately using the keywords
below.

\begin{itemize}
\item[\tplkword{author}] String.  The unmodified author of the changeset.
\item[\tplkword{branches}] String.  The name of the branch on which
  the changeset was committed.  Will be empty if the branch name was
  \texttt{default}.
\item[\tplkword{date}] Date information.  The date when the changeset
  was committed.  This is \emph{not} human-readable; you must pass it
  through a filter that will render it appropriately.  See
  section~\ref{sec:template:filter} for more information on filters.
  The date is expressed as a pair of numbers.  The first number is a
  Unix UTC timestamp (seconds since January 1, 1970); the second is
  the offset of the committer's timezone from UTC, in seconds.
\item[\tplkword{desc}] String.  The text of the changeset description.
\item[\tplkword{files}] List of strings.  All files modified, added, or
  removed by this changeset.
\item[\tplkword{file\_adds}] List of strings.  Files added by this
  changeset.
\item[\tplkword{file\_dels}] List of strings.  Files removed by this
  changeset.
\item[\tplkword{node}] String.  The changeset identification hash, as a
  40-character hexadecimal string.
\item[\tplkword{parents}] List of strings.  The parents of the
  changeset.
\item[\tplkword{rev}] Integer.  The repository-local changeset revision
  number.
\item[\tplkword{tags}] List of strings.  Any tags associated with the
  changeset.
\end{itemize}

A few simple experiments will show us what to expect when we use these
keywords; you can see the results in
figure~\ref{fig:template:keywords}.

\begin{figure}
  \interaction{template.simple.keywords}
  \caption{Template keywords in use}
  \label{fig:template:keywords}
\end{figure}

As we noted above, the date keyword does not produce human-readable
output, so we must treat it specially.  This involves using a
\emph{filter}, about which more in section~\ref{sec:template:filter}.

\interaction{template.simple.datekeyword}

\section{Escape sequences}
\label{sec:template:escape}

Mercurial's templating engine recognises the most commonly used escape
sequences in strings.  When it sees a backslash (``\Verb+\+'')
character, it looks at the following character and substitutes the two
characters with a single replacement, as described below.

\begin{itemize}
\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
  ASCII~134.
\item[\Verb+\textbackslash n+] Newline, ASCII~12.
\item[\Verb+\textbackslash r+] Carriage return, ASCII~15.
\item[\Verb+\textbackslash t+] Tab, ASCII~11.
\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13.
\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173.
\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175.
\end{itemize}

As indicated above, if you want the expansion of a template to contain
a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you
must escape it.

\section{Filtering keywords to change their results}
\label{sec:template:filter}

Some of the results of template expansion are not immediately easy to
use.  Mercurial lets you specify an optional chain of \emph{filters}
to modify the result of expanding a keyword.  You have already seen a
common filter, \tplkwfilt{date}{isodate}, in action above, to make a
date readable.

Below is a list of the most commonly used filters that Mercurial
supports.  While some filters can be applied to any text, others can
only be used in specific circumstances.  The name of each filter is
followed first by an indication of where it can be used, then a
description of its effect.

\begin{itemize}
\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+''
  tag before the end of every line except the last.  For example,
  ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''.
\item[\tplkwfilt{date}{age}] \tplkword{date} keyword.  Render the
  age of the date, relative to the current time.  Yields a string like
  ``\Verb+10 minutes+''.
\item[\tplfilter{basename}] Any text, but most useful for the
  \tplkword{files} keyword and its relatives.  Treat the text as a
  path, and return the basename. For example, ``\Verb+foo/bar/baz+''
  becomes ``\Verb+baz+''.
\item[\tplkwfilt{date}{date}] \tplkword{date} keyword.  Render a date
  in a similar format to the Unix \tplkword{date} command, but with
  timezone included.  Yields a string like
  ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
\item[\tplkwfilt{author}{domain}] Any text, but most useful for the

569:012631b248de

\chapter{Personalizar los mensajes de Mercurial}
\label{chap:template}

Mercurial provee un poderoso mecanismo que permite controlar como
despliega la información.  El mecanismo se basa en plantillas.  Puede
usar plantillas para generar salida específica para una orden
particular o para especificar la visualización completa de la interfaz
web embebida.

\section{Usar estilos que vienen con Mercurial}
\label{sec:style}

Hay ciertos estilos listos que vienen con Mercurial.  Un estilo es
simplemente una plantilla predeterminada que alguien escribió e
instaló en un sitio en el cual Mercurial puede encontrarla.

Antes de dar un vistazo a los estilos que trae Mercurial, revisemos su
salida usual.

\interaction{template.simple.normal}

Es en cierta medida informativa, pero ocupa mucho espacio---cinco
líneas de salida por cada conjunto de cambios.  El estilo
\texttt{compact} lo reduce a tres líneas, presentadas de forma
suscinta.

\interaction{template.simple.compact}

El estilo de la \texttt{bitácora de cambios} vislumbra el poder
expresivo del sistema de plantillas de Mercurial.  Este estilo busca
seguir los estándares de bitácora de cambios del proyecto
GNU\cite{web:changelog}.

\interaction{template.simple.changelog}

No es una sorpresa que el estilo predeterminado de Mercurial se llame
\texttt{default}\ndt{predeterminado}.

\subsection{Especificar un estilo predeterminado}

Puede modificar el estilo de presentación que Mercurial usará para
toda orden vía el fichero \hgrc\, indicando el estilo que prefiere
usar.

\begin{codesample2}
  [ui]
  style = compact
\end{codesample2}

Si escribe un estilo, puede usarlo bien sea proveyendo la ruta a su
fichero de estilo o copiando su fichero de estilo a un lugar en el
cual Mercurial pueda encontrarlo(típicamente el subdirectorio
\texttt{templates} de su directorio de instalación de Mercurial).

\section{Órdenes que soportan estilos y plantillas}

Todas las órdenes de Mercurial``relacionadas con \texttt{log}'' le
permiten usar estilos y plantillas: \hgcmd{incoming}, \hgcmd{log},
\hgcmd{outgoing} y \hgcmd{tip}.

Al momento de la escritura del manual estas son las únicas órdenes que
soportan estilos y plantillas.  Dado que son las órdenes más
importantes que necesitan personalización, no ha habido muchas
solicitudes desde la comunidad de usuarios de Mercurial para añadir
soporte de plantillas y estilos a otras órdenes.

\section{Cuestiones básicas de plantillas}

Una plantilla de Mercurial es sencillamente una pieza de texto.
Cierta porción nunca cambia, otras partes se \emph{expanden}, o
reemplazan con texto nuevo cuando es necesario.

Antes de continuar, veamos de nuevo un ejemplo sencillo de la salida
usual de Mercurial:

\interaction{template.simple.normal}

Ahora, ejecutemos la misma orden, pero usemos una plantilla para
modificar su salida:

\interaction{template.simple.simplest}

El ejemplo anterior ilustra la plantilla más sencilla posible;  es
solamente una porción estática de código que se imprime una vez por
cada conjunto de cambios.  La opción \hgopt{log}{--template} de la
orden \hgcmd{log} indica a Mercurial usar el texto dado como la
plantilla cuando se imprime cada conjunto de cambios.

Observe que la cadena de plantilla anterior termina con el texto
``\Verb+\n+''.  Es una \emph{secuencia de control}, que le indica a
Mercurial imprimira una nueva línea al final de cada objeto de la
plantilla.  Si omite esta nueva línea, Mercurial colocará cada pieza
de salida seguida.  Si desea más detalles acerca de secuencias de
control, vea la sección~\ref{sec:template:escape}.

Una plantilla que imprime una cadena fija de texto siempre no es muy
útil; intentemos algo un poco más complejo.

\interaction{template.simple.simplesub}

Como puede ver, la cadena ``\Verb+{desc}+'' en la plantilla ha sido
reemplazada en la salida con la descricipción de cada conjunto de
cambios.  Cada vez que Mercurial encuentra texto encerrado entre
corchetes(``\texttt{\{}'' y ``\texttt{\}}''), intentará reemplazar los
corchetes y el texto con la expansión de lo que sea está adentro.
Para imprimir un corchete de forma literal, debe escaparlo, como se
describe en la sección~\ref{sec:template:escape}.

\section{Palabras claves más comunes en las plantillas}
\label{sec:template:keyword}

Puede empezar a escribir plantillas sencillas rápidamente con las
palabras claves descritas a continuación:

\begin{itemize}
\item[\tplkword{author}] Cadena.  El autor NO modificado del conjunto
  de cambios.
\item[\tplkword{branches}] Cadena.  El nombre de la rama en la cual se
  consignó el conjunto de cambios.  Será vacía si el nombre de la rama es
  \texttt{default}.
\item[\tplkword{date}] Información de fecha.  La fecha en la cual se
  consignó el conjunto de cambios.  \emph{No} es legible por un
  humano, debe pasarla por un firltro que la desplegará
  apropiadamente.  En la sección~\ref{sec:template:filter} hay más
  detalles acerca de filtros.  La fecha se expresa como un par de
  números.  El primer número corresponde a una marca de tiempo UNIX
  UTC(segundos desde el primero de enero de 1970); la segunda es el
  corrimiento horario de la zona horaria del UTC en la cual se encontraba
  quien hizo la consignación, en segundos.
\item[\tplkword{desc}] Cadena.  La descripción en texto del conjunto
  de cambios.
\item[\tplkword{files}] Lista de cadenas.  Todos los ficheros
  modificados, adicionados o eliminados por este conjunto de cambios.
\item[\tplkword{file\_adds}] Lista de cadenas.  Ficheros adicionados
  por este conjunto de cambios.
\item[\tplkword{file\_dels}] Lista de cadenas.  Ficheros eliminados
  por este conjunto de cambios.
\item[\tplkword{node}] Cadena.  El hash de identificación de este
  conjunto de cambios como una cadena hexadecimal de 40 caracteres.
\item[\tplkword{parents}] Lista de cadenas.  Los ancestros del
  conjunto de cambios.
\item[\tplkword{rev}] Entero.  El número de revisión del repositorio
  local.
\item[\tplkword{tags}] Lista de cadenas.  Todas las etiquetas
  asociadas al conjunto de cambios.
\end{itemize}

Unos experimentos sencillos nos mostrarán qué esperar cuando usamos
estas palabras claves; puede ver los resultados en la
figura~\ref{fig:template:keywords}.

\begin{figure}
  \interaction{template.simple.keywords}
  \caption{Template keywords in use}
  \label{fig:template:keywords}
\end{figure}

Como mencionamos anteriormente, la palabra clave de fecha no produce
salida legible por un humano, debemos tratarla de forma especial.
Esto involucra usar un \emph{filtro}, acerca de lo cual hay más en la
sección~\ref{sec:template:filter}.

\interaction{template.simple.datekeyword}

\section{Secuencias de Control}
\label{sec:template:escape}

El motor de plantillas de Mercurial reconoce las secuencias de control
más comunmente usadas dentro de las cadenas.  Cuando ve un backslash
(``\Verb+\+''), ve el caracter siguiente y sustituye los dos
caracteres con un reemplazo sencillo, como se describe a continuación:

\begin{itemize}
\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'',
  ASCII~134.
\item[\Verb+\textbackslash n+] Nueva línea, ASCII~12.
\item[\Verb+\textbackslash r+] Cambio de línea, ASCII~15.
\item[\Verb+\textbackslash t+] Tab, ASCII~11.
\item[\Verb+\textbackslash v+] Tab Vertical, ASCII~13.
\item[\Verb+\textbackslash \{+] Corchete abierto, ``\Verb+{+'', ASCII~173.
\item[\Verb+\textbackslash \}+] Corchete cerrado, ``\Verb+}+'', ASCII~175.
\end{itemize}

Como se indicó arriba, si desea que la expansión en una plantilla
contenga un caracter literal ``\Verb+\+'', ``\Verb+{+'', o
  ``\Verb+{+'', debe escaparlo.

\section{Uso de filtros con palabras claves}
\label{sec:template:filter}

Algunos de los resultados de la expansión de la plantilla no son
fáciles de usar de inmediato.  Mercurial le permite especificar una
cadena de \emph{filtros} opcionales para modificar el resultado de
expandir una palabra clave.  Ya ha visto el filtro usual
\tplkwfilt{date}{isodate} en acción con anterioridad para hacer
legible la fecha.

A continuación hay una lista de los filtros de Mercurial más
comunmente usados.  Ciertos filtros pueden aplicarse a cualquier
texto, otros pueden usarse únicamente en circunstancias específicas.
El nombre de cada filtro está seguido de la indicación de dónde puede
ser usado y una descripción de su efecto.

\begin{itemize}
\item[\tplfilter{addbreaks}] Cualquier texto. Añade una etiqueta XHTML
  ``\Verb+<br/>+'' antes del final de cada línea excepto en la final.
  Por ejemplo, ``\Verb+foo\nbar+'' se convierte en ``\Verb+foo<br/>\nbar+''.
\item[\tplkwfilt{date}{age}] palabra clave \tplkword{date}.  Muestra
  la edad de la fecha, relativa al tiempo actual. Ofrece una cadena como
  ``\Verb+10 minutes+''.
\item[\tplfilter{basename}] Cualquier texto, pero de utilidad sobre
  todo en palabras claves relativas a \tplkword{ficheros}.  Trata el
  texto como una ruta, retornando el nombre base.  Por ejemplo,
  ``\Verb+foo/bar/baz+'', se convierte en ``\Verb+baz+''.
\item[\tplkwfilt{date}{date}] \tplkword{date} keyword.  Render a date
  in a similar format to the Unix \tplkword{date} command, but with
  timezone included.  Yields a string like
  ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''.
\item[\tplkwfilt{author}{domain}] Any text, but most useful for the