hgbook
changeset 83:b476081a9c04
Much progress in template chapter.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Tue Oct 03 13:03:42 2006 -0700 (2006-10-03) |
parents | 1279bc11dfdf |
children | 43b9793b4e38 |
files | en/Makefile en/examples/run-example en/examples/svn-long.txt en/examples/svn-short.txt en/examples/svn.style en/examples/svn.template en/examples/template.simple en/examples/template.svnstyle en/template.tex |
line diff
1.1 --- a/en/Makefile Mon Oct 02 15:16:47 2006 -0700 1.2 +++ b/en/Makefile Tue Oct 03 13:03:42 2006 -0700 1.3 @@ -29,7 +29,8 @@ 1.4 examples/mq.tarball \ 1.5 examples/mq.tools \ 1.6 examples/mq.tutorial \ 1.7 - examples/template.simple 1.8 + examples/template.simple \ 1.9 + examples/template.svnstyle 1.10 1.11 latex-options = \ 1.12 -interaction batchmode \
2.1 --- a/en/examples/run-example Mon Oct 02 15:16:47 2006 -0700 2.2 +++ b/en/examples/run-example Tue Oct 03 13:03:42 2006 -0700 2.3 @@ -129,6 +129,7 @@ 2.4 rcfile = os.path.join(tmpdir, '.bashrc') 2.5 rcfp = open(rcfile, 'w') 2.6 print >> rcfp, 'PS1="%s"' % self.prompt 2.7 + print >> rcfp, 'PS2="%s"' % self.prompt 2.8 print >> rcfp, 'unset HISTFILE' 2.9 print >> rcfp, 'export EXAMPLE_DIR="%s"' % os.getcwd() 2.10 print >> rcfp, 'export LANG=C'
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 3.2 +++ b/en/examples/svn-long.txt Tue Oct 03 13:03:42 2006 -0700 3.3 @@ -0,0 +1,11 @@ 3.4 +------------------------------------------------------------------------ 3.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines 3.6 +Changed paths: 3.7 + M /gen2/trunk/src/linux-kernel/infiniband/core/cma.c 3.8 + 3.9 +On reporting a route error, also include the status for the error, 3.10 +rather than indicating a status of 0 when an error has occurred. 3.11 + 3.12 +Signed-off-by: Sean Hefty <sean.hefty@intel.com> 3.13 + 3.14 +------------------------------------------------------------------------
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 4.2 +++ b/en/examples/svn-short.txt Tue Oct 03 13:03:42 2006 -0700 4.3 @@ -0,0 +1,9 @@ 4.4 +------------------------------------------------------------------------ 4.5 +r9653 | sean.hefty | 2006-09-27 14:39:55 -0700 (Wed, 27 Sep 2006) | 5 lines 4.6 + 4.7 +On reporting a route error, also include the status for the error, 4.8 +rather than indicating a status of 0 when an error has occurred. 4.9 + 4.10 +Signed-off-by: Sean Hefty <sean.hefty@intel.com> 4.11 + 4.12 +------------------------------------------------------------------------
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 5.2 +++ b/en/examples/svn.style Tue Oct 03 13:03:42 2006 -0700 5.3 @@ -0,0 +1,2 @@ 5.4 +header = '------------------------------------------------------------------------\n\n' 5.5 +changeset = svn.template
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 6.2 +++ b/en/examples/svn.template Tue Oct 03 13:03:42 2006 -0700 6.3 @@ -0,0 +1,5 @@ 6.4 +r{rev} | {author|user} | {date|isodate} ({date|rfc822date}) 6.5 + 6.6 +{desc|strip|fill76} 6.7 + 6.8 +------------------------------------------------------------------------
7.1 --- a/en/examples/template.simple Mon Oct 02 15:16:47 2006 -0700 7.2 +++ b/en/examples/template.simple Tue Oct 03 13:03:42 2006 -0700 7.3 @@ -85,3 +85,8 @@ 7.4 #$ name: combine 7.5 7.6 hg log -r1 --template 'description:\n\t{desc|strip|fill68|tabindent}\n' 7.7 + 7.8 +#$ name: rev 7.9 + 7.10 +echo 'changeset = "rev: {rev}\n"' > rev 7.11 +hg log -l1 --style ./rev
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 8.2 +++ b/en/examples/template.svnstyle Tue Oct 03 13:03:42 2006 -0700 8.3 @@ -0,0 +1,69 @@ 8.4 +#!/bin/bash 8.5 + 8.6 +svn() { 8.7 + cat $EXAMPLE_DIR/svn-short.txt 8.8 +} 8.9 + 8.10 +#$ name: short 8.11 + 8.12 +svn log -r9653 8.13 + 8.14 +#$ name: 8.15 + 8.16 +hg init myrepo 8.17 +cd myrepo 8.18 + 8.19 +echo hello > hello 8.20 +hg commit -Am'added hello' 8.21 + 8.22 +echo hello >> hello 8.23 +echo goodbye > goodbye 8.24 +echo ' added line to end of <<hello>> file.' > ../msg 8.25 +echo '' >> ../msg 8.26 +echo 'in addition, added a file with the helpful name (at least i hope that some might consider it so) of goodbye.' >> ../msg 8.27 + 8.28 +hg commit -Al../msg 8.29 + 8.30 +hg tag mytag 8.31 +hg tag v0.1 8.32 + 8.33 +echo 'changeset = "{node|short}\n"' > svn.style 8.34 + 8.35 +#$ name: id 8.36 + 8.37 +hg log -r0 --template '{node}' 8.38 + 8.39 +#$ name: simplest 8.40 + 8.41 +cat svn.style 8.42 +hg log -r1 --style svn.style 8.43 + 8.44 +#$ name: 8.45 + 8.46 +echo 'changeset =' > broken.style 8.47 + 8.48 +#$ name: syntax.input 8.49 + 8.50 +cat broken.style 8.51 + 8.52 +#$ name: syntax.error 8.53 + 8.54 +hg log -r1 --style broken.style 8.55 + 8.56 +#$ name: 8.57 + 8.58 +cp $EXAMPLE_DIR/svn.style . 8.59 +cp $EXAMPLE_DIR/svn.template . 8.60 + 8.61 +#$ name: template 8.62 + 8.63 +cat svn.template 8.64 + 8.65 +#$ name: style 8.66 + 8.67 +cat svn.style 8.68 + 8.69 +#$ name: result 8.70 + 8.71 +hg log -r1 --style svn.style 8.72 +
9.1 --- a/en/template.tex Mon Oct 02 15:16:47 2006 -0700 9.2 +++ b/en/template.tex Tue Oct 03 13:03:42 2006 -0700 9.3 @@ -11,7 +11,7 @@ 9.4 9.5 Packaged with Mercurial are some output styles that you can use 9.6 immediately. A style is simply a precanned template that someone 9.7 -wrote. 9.8 +wrote and installed somewhere that Mercurial can find. 9.9 9.10 Before we take a look at Mercurial's bundled styles, let's review its 9.11 normal output. 9.12 @@ -33,7 +33,7 @@ 9.13 You will not be shocked to learn that Mercurial's default output style 9.14 is named \texttt{default}. 9.15 9.16 -\subsection{Setting an output style to use} 9.17 +\subsection{Setting a default style} 9.18 9.19 You can modify the output style that Mercurial will use for every 9.20 command by editing your \hgrc\ file, naming the style you would 9.21 @@ -101,7 +101,7 @@ 9.22 the expansion of whatever is inside. To print a literal curly brace, 9.23 you must escape it, as described in section~\ref{sec:template:escape}. 9.24 9.25 -\section{Basic template keywords} 9.26 +\section{Common template keywords} 9.27 \label{sec:template:keyword} 9.28 9.29 You can start writing simple templates immediately using the keywords 9.30 @@ -172,15 +172,21 @@ 9.31 a literal ``\Verb+\+'', ``\Verb+{+'', or ``\Verb+{+'' character, you 9.32 must escape it. 9.33 9.34 -\section{Filtering expanded keywords} 9.35 +\section{Filtering keywords to change their results} 9.36 \label{sec:template:filter} 9.37 9.38 -Some of the results of template expansion are not entirely easy to 9.39 +Some of the results of template expansion are not immediately easy to 9.40 use. Mercurial lets you specify an optional chain of \emph{filters} 9.41 to modify the result of expanding a keyword. You have already seen a 9.42 common filter, \tplkwfilt{date}{isodate}, in action above, to make a 9.43 date readable. 9.44 9.45 +Below is a list of the most commonly used filters that Mercurial 9.46 +supports. While some filters can be applied to any text, others can 9.47 +only be used in specific circumstances. The name of each filter is 9.48 +followed first by an indication of where it can be used, then a 9.49 +description of its effect. 9.50 + 9.51 \begin{itemize} 9.52 \item[\tplfilter{addbreaks}] Any text. Add an XHTML ``\Verb+<br/>+'' 9.53 tag before the end of every line except the last. For example, 9.54 @@ -280,10 +286,186 @@ 9.55 force the first line to be indented; this is necessary since 9.56 \tplkword{tabindent} indents all lines \emph{except} the first. 9.57 9.58 -Keep in mind that the order of filters in a chain is significant. 9.59 -Using \Verb+fill68|tabindent+ gives very different results from 9.60 +Keep in mind that the order of filters in a chain is significant. The 9.61 +first filter is applied to the result of the keyword; the second to 9.62 +the result of the first filter; and so on. For example, using 9.63 +\Verb+fill68|tabindent+ gives very different results from 9.64 \Verb+tabindent|fill68+. 9.65 9.66 + 9.67 +\section{From templates to styles} 9.68 + 9.69 +A command line template provides a quick and simple way to format some 9.70 +output. Templates can become verbose, though, and it's useful to be 9.71 +able to give a template a name. A style file is a template with a 9.72 +name, stored in a file. 9.73 + 9.74 +More than that, using a style file unlocks the power of Mercurial's 9.75 +templating engine in ways that are not possible using the command line 9.76 +\hgopt{log}{--template} option. 9.77 + 9.78 +\subsection{The simplest of style files} 9.79 + 9.80 +Our simple style file contains just one line: 9.81 + 9.82 +\interaction{template.simple.rev} 9.83 + 9.84 +This tells Mercurial, ``if you're printing a changeset, use the text 9.85 +on the right as the template''. 9.86 + 9.87 +\subsection{Style file syntax} 9.88 + 9.89 +The syntax rules for a style file are simple. 9.90 + 9.91 +\begin{itemize} 9.92 +\item The file is processed one line at a time. 9.93 + 9.94 +\item Leading and trailing white space are ignored. 9.95 + 9.96 +\item Empty lines are skipped. 9.97 + 9.98 +\item If a line starts with either of the characters ``\texttt{\#}'' or 9.99 + ``\texttt{;}'', the entire line is treated as a comment, and skipped 9.100 + as if empty. 9.101 + 9.102 +\item A line starts with a keyword. This must start with an 9.103 + alphabetic character or underscore, and can subsequently contain any 9.104 + alphanumeric character or underscore. (In regexp notation, a 9.105 + keyword must match \Verb+[A-Za-z_][A-Za-z0-9_]*+.) 9.106 + 9.107 +\item The next element must be an ``\texttt{=}'' character, which can 9.108 + be preceded or followed by an arbitrary amount of white space. 9.109 + 9.110 +\item If the rest of the line starts and ends with matching quote 9.111 + characters (either single or double quote), it is treated as a 9.112 + template body. 9.113 + 9.114 +\item If the rest of the line \emph{does not} start with a quote 9.115 + character, it is treated as the name of a file; the contents of this 9.116 + file will be read and used as a template body. 9.117 +\end{itemize} 9.118 + 9.119 +\section{Style files by example} 9.120 + 9.121 +To illustrate how to write a style file, we will construct a few by 9.122 +example. Rather than provide a complete style file and walk through 9.123 +it, we'll mirror the usual process of developing a style file by 9.124 +starting with something very simple, and walking through a series of 9.125 +successively more complete examples. 9.126 + 9.127 +\subsection{Identifying mistakes in style files} 9.128 + 9.129 +If Mercurial encounters a problem in a style file you are working on, 9.130 +it prints a terse error message that, once you figure out what it 9.131 +means, is actually quite useful. 9.132 + 9.133 +\interaction{template.svnstyle.syntax.input} 9.134 + 9.135 +Notice that \filename{broken.style} attempts to define a 9.136 +\texttt{changeset} keyword, but forgets to give any content for it. 9.137 +When instructed to use this style file, Mercurial promptly complains. 9.138 + 9.139 +\interaction{template.svnstyle.syntax.error} 9.140 + 9.141 +This error message looks intimidating, but it is not too hard to 9.142 +follow. 9.143 + 9.144 +\begin{itemize} 9.145 +\item The first component is simply Mercurial's way of saying ``I am 9.146 + giving up''. 9.147 + \begin{codesample4} 9.148 + \textbf{abort:} broken.style:1: parse error 9.149 + \end{codesample4} 9.150 + 9.151 +\item Next comes the name of the style file that contains the error. 9.152 + \begin{codesample4} 9.153 + abort: \textbf{broken.style}:1: parse error 9.154 + \end{codesample4} 9.155 + 9.156 +\item Following the file name is the line number where the error was 9.157 + encountered. 9.158 + \begin{codesample4} 9.159 + abort: broken.style:\textbf{1}: parse error 9.160 + \end{codesample4} 9.161 + 9.162 +\item Finally, a description of what went wrong. 9.163 + \begin{codesample4} 9.164 + abort: broken.style:1: \textbf{parse error} 9.165 + \end{codesample4} 9.166 + The description of the problem is not always clear (as in this 9.167 + case), but even when it is cryptic, it is almost always trivial to 9.168 + visually inspect the offending line in the style file and see what 9.169 + is wrong. 9.170 +\end{itemize} 9.171 + 9.172 +\subsection{Uniquely identifying a repository} 9.173 + 9.174 +If you would like to be able to identify a Mercurial repository 9.175 +``fairly uniquely'' using a short string as an identifier, you can 9.176 +use the first revision in the repository. 9.177 +\interaction{template.svnstyle.id} 9.178 +This is not guaranteed to be unique, but it is nevertheless useful in 9.179 +many cases. 9.180 +\begin{itemize} 9.181 +\item It will not work in a completely empty repository, because such 9.182 + a repository does not have a revision~zero. 9.183 +\item Neither will it work in the (extremely rare) case where a 9.184 + repository is a merge of two or more formerly independent 9.185 + repositories, and you still have those repositories around. 9.186 +\end{itemize} 9.187 +Here are some uses to which you could put this identifier: 9.188 +\begin{itemize} 9.189 +\item As a key into a table for a database that manages repositories 9.190 + on a server. 9.191 +\item As half of a \{\emph{repository~ID}, \emph{revision~ID}\} tuple. 9.192 + Save this information away when you run an automated build or other 9.193 + activity, so that you can ``replay'' the build later if necessary. 9.194 +\end{itemize} 9.195 + 9.196 +\subsection{Mimicking Subversion's output} 9.197 + 9.198 +Let's try to emulate the default output format used by another 9.199 +revision control tool, Subversion. 9.200 +\interaction{template.svnstyle.short} 9.201 + 9.202 +Since Subversion's output style is fairly simple, it is easy to 9.203 +copy-and-paste a hunk of its output into a file, and replace the text 9.204 +produced above by Subversion with the template values we'd like to see 9.205 +expanded. 9.206 +\interaction{template.svnstyle.template} 9.207 + 9.208 +There are a few small ways in which this template deviates from the 9.209 +output produced by Subversion. 9.210 +\begin{itemize} 9.211 +\item Subversion prints a ``readable'' date (the ``\texttt{Wed, 27 Sep 9.212 + 2006}'' in the example output above) in parentheses. Mercurial's 9.213 + templating engine does not provide a way to display a date in this 9.214 + format without also printing the time and time zone. 9.215 +\item We emulate Subversion's printing of ``separator'' lines full of 9.216 + ``\texttt{-}'' characters by ending the template with such a line. 9.217 + We use the templating engine's \tplkword{header} keyword to print a 9.218 + separator line as the first line of output (see below), thus 9.219 + achieving similar output to Subversion. 9.220 +\item Subversion's output includes a count in the header of the number 9.221 + of lines in the commit message. We cannot replicate this in 9.222 + Mercurial; the templating engine does not currently provide a filter 9.223 + that counts the number of items it is passed. 9.224 +\end{itemize} 9.225 +It took me no more than a minute or two of work to replace literal 9.226 +text from an example of Subversion's output with some keywords and 9.227 +filters to give the template above. The style file simply refers to 9.228 +the template. 9.229 +\interaction{template.svnstyle.style} 9.230 + 9.231 +We could have included the text of the template file directly in the 9.232 +style file by enclosing it in quotes and replacing the newlines with 9.233 +``\texttt{\\n}'' sequences, but it would have made the style file too 9.234 +difficult to read. Readability is a good guide when you're trying to 9.235 +decide whether some text belongs in a style file, or in a template 9.236 +file that the style file points to. If the style file will look too 9.237 +big or cluttered if you insert a literal piece of text, drop it into a 9.238 +template instead. 9.239 + 9.240 %%% Local Variables: 9.241 %%% mode: latex 9.242 %%% TeX-master: "00book"