hgbook
changeset 80:ea951cfb5cd9
Much template-related content.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Wed Sep 06 23:36:47 2006 -0700 (2006-09-06) |
parents | 53427f786a0f |
children | 324dd9a8f0df |
files | .hgignore en/99book.bib en/99defs.tex en/Makefile en/examples/template.simple en/template.tex |
line diff
1.1 --- a/.hgignore Mon Sep 04 14:31:17 2006 -0700 1.2 +++ b/.hgignore Wed Sep 06 23:36:47 2006 -0700 1.3 @@ -5,6 +5,7 @@ 1.4 1.5 beta/*.tex 1.6 build_id.tex 1.7 +*.4[ct][ct] 1.8 *.aux 1.9 *.bbl 1.10 *.bib
2.1 --- a/en/99book.bib Mon Sep 04 14:31:17 2006 -0700 2.2 +++ b/en/99book.bib Wed Sep 06 23:36:47 2006 -0700 2.3 @@ -49,3 +49,9 @@ 2.4 title = {MySQL for Python}, 2.5 note = {\url{http://sourceforge.net/projects/mysql-python}}, 2.6 } 2.7 + 2.8 +@Misc{web:changelog, 2.9 + autor = {Richard Stallman, GNU Project volunteers}, 2.10 + title = {GNU Coding Standards---Change Logs}, 2.11 + note = {\url{http://www.gnu.org/prep/standards/html_node/Change-Logs.html}}, 2.12 +}
3.1 --- a/en/99defs.tex Mon Sep 04 14:31:17 2006 -0700 3.2 +++ b/en/99defs.tex Wed Sep 06 23:36:47 2006 -0700 3.3 @@ -29,6 +29,16 @@ 3.4 % Mercurial command, with arguments. 3.5 \newcommand{\hgcmdargs}[2]{\index{\texttt{#1} command}``\texttt{hg #1 #2}''} 3.6 3.7 +\newcommand{\tplkword}[1]{\index{\texttt{#1} template keyword}\index{template keywords!\texttt{#1}}\texttt{#1}} 3.8 + 3.9 +\newcommand{\tplkwfilt}[2]{\index{\texttt{#1} template keyword!\texttt{#2} 3.10 + filter}\index{template filters!\texttt{#2}}\index{\texttt{#2} 3.11 + template filter}\texttt{#2}} 3.12 + 3.13 +\newcommand{\tplfilter}[1]{\index{template 3.14 + filters!\texttt{#1}}\index{\texttt{#1} template 3.15 + filter}\texttt{#1}} 3.16 + 3.17 % Shell/system command. 3.18 \newcommand{\command}[1]{\index{\texttt{#1} command}\texttt{#1}} 3.19
4.1 --- a/en/Makefile Mon Sep 04 14:31:17 2006 -0700 4.2 +++ b/en/Makefile Wed Sep 06 23:36:47 2006 -0700 4.3 @@ -28,7 +28,8 @@ 4.4 examples/mq.id \ 4.5 examples/mq.tarball \ 4.6 examples/mq.tools \ 4.7 - examples/mq.tutorial 4.8 + examples/mq.tutorial \ 4.9 + examples/template.simple 4.10 4.11 latex-options = \ 4.12 -interaction batchmode \
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/examples/template.simple Wed Sep 06 23:36:47 2006 -0700 5.3 @@ -0,0 +1,87 @@ 5.4 +#!/bin/bash 5.5 + 5.6 +hg init myrepo 5.7 +cd myrepo 5.8 +echo hello > hello 5.9 +hg commit -Am'added hello' 5.10 + 5.11 +echo hello >> hello 5.12 +echo goodbye > goodbye 5.13 +echo ' added line to end of <<hello>> file.' > ../msg 5.14 +echo '' >> ../msg 5.15 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg 5.16 + 5.17 +hg commit -Al../msg 5.18 + 5.19 +hg tag mytag 5.20 +hg tag v0.1 5.21 + 5.22 +#$ name: normal 5.23 + 5.24 +hg log -r1 5.25 + 5.26 +#$ name: compact 5.27 + 5.28 +hg log --style compact 5.29 + 5.30 +#$ name: changelog 5.31 + 5.32 +hg log --style changelog 5.33 + 5.34 +#$ name: simplest 5.35 + 5.36 +hg log -r1 --template 'i saw a changeset\n' 5.37 + 5.38 +#$ name: simplesub 5.39 + 5.40 +hg log --template 'i saw a changeset: {desc}\n' 5.41 + 5.42 +#$ name: keywords 5.43 + 5.44 +hg log -r1 --template 'author: {author}\n' 5.45 +hg log -r1 --template 'desc:\n{desc}\n' 5.46 +hg log -r1 --template 'files: {files}\n' 5.47 +hg log -r1 --template 'file_adds: {file_adds}\n' 5.48 +hg log -r1 --template 'file_dels: {file_dels}\n' 5.49 +hg log -r1 --template 'node: {node}\n' 5.50 +hg log -r1 --template 'parents: {parents}\n' 5.51 +hg log -r1 --template 'rev: {rev}\n' 5.52 +hg log -r1 --template 'tags: {tags}\n' 5.53 + 5.54 +#$ name: datekeyword 5.55 + 5.56 +hg log -r1 --template 'date: {date}\n' 5.57 +hg log -r1 --template 'date: {date|isodate}\n' 5.58 + 5.59 +#$ name: manyfilters 5.60 + 5.61 +hg log -r1 --template '{author}\n' 5.62 +hg log -r1 --template '{author|domain}\n' 5.63 +hg log -r1 --template '{author|email}\n' 5.64 +hg log -r1 --template '{author|obfuscate}\n' | cut -c-76 5.65 +hg log -r1 --template '{author|person}\n' 5.66 +hg log -r1 --template '{author|user}\n' 5.67 + 5.68 +hg log -r1 --template 'looks almost right, but actually garbage: {date}\n' 5.69 +hg log -r1 --template '{date|age}\n' 5.70 +hg log -r1 --template '{date|date}\n' 5.71 +hg log -r1 --template '{date|hgdate}\n' 5.72 +hg log -r1 --template '{date|isodate}\n' 5.73 +hg log -r1 --template '{date|rfc822date}\n' 5.74 +hg log -r1 --template '{date|shortdate}\n' 5.75 + 5.76 +hg log -r1 --template '{desc}\n' | cut -c-76 5.77 +hg log -r1 --template '{desc|addbreaks}\n' | cut -c-76 5.78 +hg log -r1 --template '{desc|escape}\n' | cut -c-76 5.79 +hg log -r1 --template '{desc|fill68}\n' 5.80 +hg log -r1 --template '{desc|fill76}\n' 5.81 +hg log -r1 --template '{desc|firstline}\n' 5.82 +hg log -r1 --template '{desc|strip}\n' | cut -c-76 5.83 +hg log -r1 --template '{desc|tabindent}\n' | expand | cut -c-76 5.84 + 5.85 +hg log -r1 --template '{node}\n' 5.86 +hg log -r1 --template '{node|short}\n' 5.87 + 5.88 +#$ name: combine 5.89 + 5.90 +hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n'
6.1 --- a/en/template.tex Mon Sep 04 14:31:17 2006 -0700 6.2 +++ b/en/template.tex Wed Sep 06 23:36:47 2006 -0700 6.3 @@ -1,5 +1,288 @@ 6.4 -\chapter{Using templates to customise output} 6.5 -\label{chap:templates} 6.6 +\chapter{Customising the output of Mercurial} 6.7 +\label{chap:template} 6.8 + 6.9 +Mercurial provides a powerful mechanism to let you control how it 6.10 +displays information. The mechanism is based on templates. You can 6.11 +use templates to generate specific output for a single command, or to 6.12 +customise the entire appearance of the built-in web interface. 6.13 + 6.14 +\section{Using precanned output styles} 6.15 +\label{sec:style} 6.16 + 6.17 +Packaged with Mercurial are some output styles that you can use 6.18 +immediately. A style is simply a precanned template that someone 6.19 +wrote. 6.20 + 6.21 +Before we take a look at Mercurial's bundled styles, let's review its 6.22 +normal output. 6.23 + 6.24 +\interaction{template.simple.normal} 6.25 + 6.26 +This is somewhat informative, but it takes up a lot of space---five 6.27 +lines of output per changeset. The \texttt{compact} style reduces 6.28 +this to three lines, presented in a sparse manner. 6.29 + 6.30 +\interaction{template.simple.compact} 6.31 + 6.32 +The \texttt{changelog} style hints at the expressive power of 6.33 +Mercurial's templating engine. This style attempts to follow the GNU 6.34 +Project's changelog guidelines\cite{web:changelog}. 6.35 + 6.36 +\interaction{template.simple.changelog} 6.37 + 6.38 +You will not be shocked to learn that Mercurial's default output style 6.39 +is named \texttt{default}. 6.40 + 6.41 +\subsection{Setting an output style to use} 6.42 + 6.43 +You can modify the output style that Mercurial will use for every 6.44 +command by editing your \hgrc\ file, naming the style you would 6.45 +prefer to use. 6.46 + 6.47 +\begin{codesample2} 6.48 + [ui] 6.49 + style = compact 6.50 +\end{codesample2} 6.51 + 6.52 +If you write a style of your own, you can use it by either providing 6.53 +the path to your style file, or copying your style file into a 6.54 +location where Mercurial can find it (typically the \texttt{templates} 6.55 +subdirectory of your Mercurial install directory). 6.56 + 6.57 +\section{Commands that support styles and templates} 6.58 + 6.59 +All of Mercurial's ``\texttt{log}-like'' commands let you use styles 6.60 +and templates: \hgcmd{incoming}, \hgcmd{log}, \hgcmd{outgoing}, and 6.61 +\hgcmd{tip}. 6.62 + 6.63 +As I write this manual, these are so far the only commands that 6.64 +support styles and templates. Since these are the most important 6.65 +commands that need customisable output, there has been little pressure 6.66 +from the Mercurial user community to add style and template support to 6.67 +other commands. 6.68 + 6.69 +\section{The basics of templating} 6.70 + 6.71 +At its simplest, a Mercurial template is a piece of text. Some of the 6.72 +text never changes, while other parts are \emph{expanded}, or replaced 6.73 +with new text, when necessary. 6.74 + 6.75 +Before we continue, let's look again at a simple example of 6.76 +Mercurial's normal output. 6.77 + 6.78 +\interaction{template.simple.normal} 6.79 + 6.80 +Now, let's run the same command, but using a template to change its 6.81 +output. 6.82 + 6.83 +\interaction{template.simple.simplest} 6.84 + 6.85 +The example above illustrates the simplest possible template; it's 6.86 +just a piece of static text, printed once for each changeset. The 6.87 +\hgopt{log}{--template} option to the \hgcmd{log} command tells 6.88 +Mercurial to use the given text as the template when printing each 6.89 +changeset. 6.90 + 6.91 +Notice that the template string above ends with the text 6.92 +``\Verb+\n+''. This is an \emph{escape sequence}, telling Mercurial 6.93 +to print a newline at the end of each template item. If you omit this 6.94 +newline, Mercurial will run each piece of output together. See 6.95 +section~\ref{sec:template:escape} for more details of escape sequences. 6.96 + 6.97 +A template that prints a fixed string of text all the time isn't very 6.98 +useful; let's try something a bit more complex. 6.99 + 6.100 +\interaction{template.simple.simplesub} 6.101 + 6.102 +As you can see, the string ``\Verb+{desc}+'' in the template has been 6.103 +replaced in the output with the description of each changeset. Every 6.104 +time Mercurial finds text enclosed in curly braces (``\texttt{\{}'' 6.105 +and ``\texttt{\}}''), it will try to replace the braces and text with 6.106 +the expansion of whatever is inside. To print a literal curly brace, 6.107 +you must escape it, as described in section~\ref{sec:template:escape}. 6.108 + 6.109 +\section{Basic template keywords} 6.110 +\label{sec:template:keyword} 6.111 + 6.112 +You can start writing simple templates immediately using the keywords 6.113 +below. 6.114 + 6.115 +\begin{itemize} 6.116 +\item[\tplkword{author}] String. The unmodified author of the changeset. 6.117 +\item[\tplkword{date}] Date information. The date when the changeset 6.118 + was committed. This is \emph{not} human-readable; you must pass it 6.119 + through a filter that will render it appropriately. See 6.120 + section~\ref{sec:template:filter} for more information on filters. 6.121 + The date is expressed as a pair of numbers. The first number is a 6.122 + Unix UTC timestamp (seconds since January 1, 1970); the second is 6.123 + the offset of the committer's timezone from UTC, in seconds. 6.124 +\item[\tplkword{desc}] String. The text of the changeset description. 6.125 +\item[\tplkword{files}] List of strings. All files modified, added, or 6.126 + removed by this changeset. 6.127 +\item[\tplkword{file\_adds}] List of strings. Files added by this 6.128 + changeset. 6.129 +\item[\tplkword{file\_dels}] List of strings. Files removed by this 6.130 + changeset. 6.131 +\item[\tplkword{node}] String. The changeset identification hash, as a 6.132 + 40-character hexadecimal string. 6.133 +\item[\tplkword{parents}] List of strings. The parents of the 6.134 + changeset. 6.135 +\item[\tplkword{rev}] Integer. The repository-local changeset revision 6.136 + number. 6.137 +\item[\tplkword{tags}] List of strings. Any tags associated with the 6.138 + changeset. 6.139 +\end{itemize} 6.140 + 6.141 +A few simple experiments will show us what to expect when we use these 6.142 +keywords; you can see the results in 6.143 +figure~\ref{fig:template:keywords}. 6.144 + 6.145 +\begin{figure} 6.146 + \interaction{template.simple.keywords} 6.147 + \caption{Template keywords in use} 6.148 + \label{fig:template:keywords} 6.149 +\end{figure} 6.150 + 6.151 +As we noted above, the date keyword does not produce human-readable 6.152 +output, so we must treat it specially. This involves using a 6.153 +\emph{filter}, about which more in section~\ref{sec:template:filter}. 6.154 + 6.155 +\interaction{template.simple.datekeyword} 6.156 + 6.157 +\section{Escape sequences} 6.158 +\label{sec:template:escape} 6.159 + 6.160 +Mercurial's templating engine recognises the most commonly used escape 6.161 +sequences in strings. When it sees a backslash (``\Verb+\+'') 6.162 +character, it looks at the following character and substitutes the two 6.163 +characters with a single replacement, as described below. 6.164 + 6.165 +\begin{itemize} 6.166 +\item[\Verb+\textbackslash\textbackslash+] Backslash, ``\Verb+\+'', 6.167 + ASCII~134. 6.168 +\item[\Verb+\textbackslash n+] Newline, ASCII~12. 6.169 +\item[\Verb+\textbackslash r+] Carriage return, ASCII~15. 6.170 +\item[\Verb+\textbackslash t+] Tab, ASCII~11. 6.171 +\item[\Verb+\textbackslash v+] Vertical tab, ASCII~13. 6.172 +\item[\Verb+\textbackslash \{+] Open curly brace, ``\Verb+{+'', ASCII~173. 6.173 +\item[\Verb+\textbackslash \}+] Close curly brace, ``\Verb+}+'', ASCII~175. 6.174 +\end{itemize} 6.175 + 6.176 +As indicated above, if you want the expansion of a template to contain 6.177 +a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you 6.178 +must escape it. 6.179 + 6.180 +\section{Filtering expanded keywords} 6.181 +\label{sec:template:filter} 6.182 + 6.183 +Some of the results of template expansion are not entirely easy to 6.184 +use. Mercurial lets you specify an optional chain of \emph{filters} 6.185 +to modify the result of expanding a keyword. You have already seen a 6.186 +common filter, \tplkwfilt{date}{isodate}, in action above, to make a 6.187 +date readable. 6.188 + 6.189 +\begin{itemize} 6.190 +\item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+'' 6.191 + tag before the end of every line except the last. For example, 6.192 + ``\Verb+foo\nbar+'' becomes ``\Verb+foo<br/>\nbar+''. 6.193 +\item[\tplkwfilt{date}{age}] \tplkword{date} keyword. Render the 6.194 + age of the date, relative to the current time. Yields a string like 6.195 + ``\Verb+10 minutes+''. 6.196 +\item[\tplfilter{basename}] Any text, but most useful for the 6.197 + \tplkword{files} keyword and its relatives. Treat the text as a 6.198 + path, and return the basename. For example, ``\Verb+foo/bar/baz+'' 6.199 + becomes ``\Verb+baz+''. 6.200 +\item[\tplkwfilt{date}{date}] \tplkword{date} keyword. Render a date 6.201 + in a similar format to the Unix \tplkword{date} command, but with 6.202 + timezone included. Yields a string like 6.203 + ``\Verb+Mon Sep 04 15:13:13 2006 -0700+''. 6.204 +\item[\tplkwfilt{author}{domain}] Any text, but most useful for the 6.205 + \tplkword{author} keyword. Finds the first string that looks like 6.206 + an email address, and extract just the domain component. For 6.207 + example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 6.208 + ``\Verb+serpentine.com+''. 6.209 +\item[\tplkwfilt{author}{email}] Any text, but most useful for the 6.210 + \tplkword{author} keyword. Extract the first string that looks like 6.211 + an email address. For example, 6.212 + ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 6.213 + ``\Verb+bos@serpentine.com+''. 6.214 +\item[\tplfilter{escape}] Any text. Replace the special XML/XHTML 6.215 + characters ``\Verb+&+'', ``\Verb+<+'' and ``\Verb+>+'' with 6.216 + XML entities. 6.217 +\item[\tplfilter{fill68}] Any text. Wrap the text to fit in 68 6.218 + columns. This is useful before you pass text through the 6.219 + \tplfilter{tabindent} filter, and still want it to fit in an 6.220 + 80-column fixed-font window. 6.221 +\item[\tplfilter{fill76}] Any text. Wrap the text to fit in 76 6.222 + columns. 6.223 +\item[\tplfilter{firstline}] Any text. Yield the first line of text, 6.224 + without any trailing newlines. 6.225 +\item[\tplkwfilt{date}{hgdate}] \tplkword{date} keyword. Render the 6.226 + date as a pair of readable numbers. Yields a string like 6.227 + ``\Verb+1157407993 25200+''. 6.228 +\item[\tplkwfilt{date}{isodate}] \tplkword{date} keyword. Render the 6.229 + date as a text string in ISO~8601 format. Yields a string like 6.230 + ``\Verb+2006-09-04 15:13:13 -0700+''. 6.231 +\item[\tplfilter{obfuscate}] Any text, but most useful for the 6.232 + \tplkword{author} keyword. Yield the input text rendered as a 6.233 + sequence of XML entities. This helps to defeat some particularly 6.234 + stupid screen-scraping email harvesting spambots. 6.235 +\item[\tplkwfilt{author}{person}] Any text, but most useful for the 6.236 + \tplkword{author} keyword. Yield the text before an email address. 6.237 + For example, ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' 6.238 + becomes ``\Verb+Bryan O'Sullivan+''. 6.239 +\item[\tplkwfilt{date}{rfc822date}] \tplkword{date} keyword. Render a 6.240 + date using the same format used in email headers. Yields a string 6.241 + like ``\Verb+Mon, 04 Sep 2006 15:13:13 -0700+''. 6.242 +\item[\tplkwfilt{node}{short}] Changeset hash. Yield the short form 6.243 + of a changeset hash, i.e.~a 12-byte hexadecimal string. 6.244 +\item[\tplkwfilt{date}{shortdate}] \tplkword{date} keyword. Render 6.245 + the year, month, and day of the date. Yields a string like 6.246 + ``\Verb+2006-09-04+''. 6.247 +\item[\tplfilter{strip}] Any text. Strip all leading and trailing 6.248 + whitespace from the string. 6.249 +\item[\tplfilter{tabindent}] Any text. Yield the text, with every line 6.250 + except the first starting with a tab character. 6.251 +\item[\tplfilter{urlescape}] Any text. Escape all characters that are 6.252 + considered ``special'' by URL parsers. For example, \Verb+foo bar+ 6.253 + becomes \Verb+foo%20bar+. 6.254 +\item[\tplkwfilt{author}{user}] Any text, but most useful for the 6.255 + \tplkword{author} keyword. Return the ``user'' portion of an email 6.256 + address. For example, 6.257 + ``\Verb+Bryan O'Sullivan <bos@serpentine.com>+'' becomes 6.258 + ``\Verb+bos+''. 6.259 +\end{itemize} 6.260 + 6.261 +\begin{figure} 6.262 + \interaction{template.simple.manyfilters} 6.263 + \caption{Template filters in action} 6.264 + \label{fig:template:filters} 6.265 +\end{figure} 6.266 + 6.267 +\begin{note} 6.268 + If you try to apply a filter to a piece of data that it cannot 6.269 + process, Mercurial will fail and print a Python exception. For 6.270 + example, trying to run the output of the \tplkword{desc} keyword 6.271 + into the \tplkwfilt{date}{isodate} filter is not a good idea. 6.272 +\end{note} 6.273 + 6.274 +\subsection{Combining filters} 6.275 + 6.276 +It is easy to combine filters to yield output in the form you would 6.277 +like. The following chain of filters tidies up a description, then 6.278 +makes sure that it fits cleanly into 68 columns, then indents it by a 6.279 +further 8~characters (at least on Unix-like systems, where a tab is 6.280 +conventionally 8~characters wide). 6.281 + 6.282 +\interaction{template.simple.combine} 6.283 + 6.284 +Note the use of ``\Verb+\t+'' (a tab character) in the template to 6.285 +force the first line to be indented; this is necessary since 6.286 +\tplkword{tabindent} indents all lines \emph{except} the first. 6.287 + 6.288 +Keep in mind that the order of filters in a chain is significant. 6.289 +Using \Verb+fill68|tabindent+ gives very different results from 6.290 +\Verb+tabindent|fill68+. 6.291 6.292 %%% Local Variables: 6.293 %%% mode: latex