Debian Codegraph @

texmf-dist/source/latex/svn/svn.dtx

raw
1 % \iffalse meta-comment
2 % $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
3 % Copyright (C) 2003-7 by Richard Lewis <[email protected]>
4 %
5 % This file may be distributed and/or modified under the conditions
6 % of the LaTeX Project Public License, either version 1.3 of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in:
9 %
10 % http://www.latex-project.org/lppl.txt
11 %
12 % and version 1.3 or later is part of all distributions of LaTeX
13 % version 2003/06/01 or later.
14 %
15 % This work has the LPPL maintenance status `maintained', and the
16 % Current Maintainer of this work is Richard Lewis <[email protected]>.
17 %
18 % This work consists of all files listed in the `Contents' section of
19 % the README file.
20 %
21 % \fi
22 %
23 % \iffalse
24 %<*package>
25 %\NeedsTeXFormat{LaTeX2e}
26 %\def\svn@Id $Id: #1 #2 #3-#4-#5 #6$%
27 % {\def\svn@date{#3/#4/#5}%
28 % \def\svn@revision{#2}}
29 %
30 %\svn@Id $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
31 %\edef\next{%
32 % \noexpand\ProvidesPackage{svn}[\svn@date\space r\svn@revision\space
33 % Typeset subversion keywords.]}
34 %\next
35 %</package>
36 %
37 %<*driver>
38 \documentclass{ltxdoc}
39 \usepackage[T1]{fontenc}
40 \usepackage[utf8x]{inputenc}
41 \usepackage[british]{babel}
42 \usepackage{lmodern} % ensures we use Type 1 fonts, comment this out to get Type 3 fonts
43 \usepackage{svn}
44 \EnableCrossrefs
45 \CodelineIndex
46 %\OnlyDescription
47 %\RecordChanges
48 \begin{document}
49 \DocInput{svn.dtx}
50 \end{document}
51 %</driver>
52 % \fi
53 %
54 % \CheckSum{106}
55 %
56 % \CharacterTable
57 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
58 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
59 % Digits \0\1\2\3\4\5\6\7\8\9
60 % Exclamation \! Double quote \" Hash (number) \#
61 % Dollar \$ Percent \% Ampersand \&
62 % Acute accent \' Left paren \( Right paren \)
63 % Asterisk \* Plus \+ Comma \,
64 % Minus \- Point \. Solidus \/
65 % Colon \: Semicolon \; Less than \<
66 % Equals \= Greater than \> Question mark \?
67 % Commercial at \@ Left bracket \[ Backslash \\
68 % Right bracket \] Circumflex \^ Underscore \_
69 % Grave accent \` Left brace \{ Vertical bar \|
70 % Right brace \} Tilde \~}
71 %
72 % \GetFileInfo{svn.sty}
73 % \DoNotIndex{\NeedsTeXFormat,\ProvidesPackage,\next}
74 % \DoNotIndex{\newcommand,\def,\edef,\gdef,\global,\let}
75 % \DoNotIndex{\noexpand,\expandafter,\csname,\endcsname}
76 % \DoNotIndex{\protect}
77 % \DoNotIndex{\if,\ifx,\else,\fi,\begingroup,\endgroup}
78 % \DoNotIndex{\space,\@empty,\@ifundefined,\@nameuse}
79 %
80 %
81 % \let\prog\textsf
82 % \let\format\texttt
83 % \def\shell#1{`\texttt{#1}'}
84 % \let\package\textsf
85 % \let\email\texttt
86 % \let\url\texttt
87 % \def\param#1{\texttt{\##1}}
88 % \def\Subversion{\prog{Subversion}}
89 % \def\CVS{\prog{CVS}}
90 % \def\RCS{\prog{RCS}}
91 %
92 % \title{The \package{svn} package\thanks{This document
93 % corresponds to \package{svn}~\fileversion, dated \filedate.}}
94 % \author{Richard Lewis \\ \email{[email protected]}}
95 %
96 % \def\convertfiledate/#1/#2/#3/{%
97 % \def\convertedfiledate{\begingroup\day#3 \month#2 \year#1 \today\endgroup}
98 % }
99 % \expandafter\convertfiledate\expandafter/\filedate/
100 % \date{\convertedfiledate}
101 % \maketitle
102 %
103 % \section{Introduction}
104 % \Subversion\ is a replacement for \CVS\ and \RCS. It is similar to
105 % \CVS\ but with some improvements (e.g., it understands
106 % renaming and deletion of version controlled files---see
107 % \url{http://subversion.tigris.org/} for more information). As with
108 % \CVS\ and \RCS, a file registered with \Subversion\ may
109 % contain keywords (such as |$Date$| or |$Revision$|) that
110 % \Subversion\ will replace with status information about the file
111 % (such as the date the file was last committed, or the revision at
112 % which it last changed).\footnote{Unlike \RCS\ and \CVS, the
113 % expansion of such keywords is customisable, and not enabled by
114 % default: use \shell{svn propset svn:keywords "Date Id" myfile.tex}
115 % to tell \Subversion\ to expand the keywords
116 % \texttt{\string$Date\string$} and \texttt{\string$Id\string$} in
117 % \shell{myfile.tex}.}
118 %
119 % For typesetting the contents of \RCS\ and \CVS\ keywords
120 % there is the \package{rcs} package\footnote{Written by Joachim
121 % Schrod with minor modification by Jeffrey Goldberg}; although highly
122 % recommended, that package does not cope with the format of
123 % \Subversion's |$Date$| keyword, so I wrote the \package{svn} package
124 % to do just that.
125 %
126 % \section{Usage}
127 % \subsection{Quick Example}
128 % The main use for this package is to get the date the file was last
129 % committed into the output of |\maketitle|. The solution is simple:
130 %
131 % \begin{verbatim}
132 % \documentclass{article}
133 % \usepackage{svn}
134 % \SVNdate $Date$
135 % \title{Hope this works}
136 %
137 % \begin{document}
138 % \maketitle
139 % \end{document}
140 % \end{verbatim}
141 %
142 % \subsection{More General Usage}
143 % As usual, load the \package{svn} package with |\usepackage{svn}|.
144 %
145 % The main command is |\SVN $|\meta{Keyword}|$| (which mimics
146 % `|\RCS $|\meta{Keyword}|$|' from the \package{rcs} package).
147 % By default the following happens:
148 % \begin{itemize}
149 % \item If you say |\SVN $Keyword: stuff $| (i.e,
150 % |$Keyword$| has been expanded to `|stuff|') then:
151 % \begin{itemize}
152 % \item If |$Keyword$| is |$Date$| or |$\LastChangedDate$|, then
153 % |stuff| is parsed and |\SVNDate| is defined to be the date, and
154 % |\SVNTime| the time, that the file was checked in. |\SVNRawDate|
155 % is defined to be the whole string `|stuff|'.
156 % \item Otherwise a command |\SVNKeyword| is defined to be
157 % `|stuff|'.
158 % \end{itemize}
159 % \item If you say |\SVN $Keyword$| (i.e., |$Keyword$| was
160 % not expanded---perhaps it doesn't appear in the \url{svn:keywords}
161 % property, or perhaps the file has not been checked in since the
162 % line was added), then:
163 % \begin{itemize}
164 % \item If |$Keyword$| is |$Date$| (or |$\LastChangedDate$|),
165 % |\SVNDate| is defined to be |\today|, and |\SVNTime| and
166 % |\SVNRawDate| are set to |\SVNempty| (which is empty by default,
167 % and may be changed with |\renewcommand|).
168 % \item Otherwise |\SVNKeyword| is defined to be |\SVNempty|.
169 % \end{itemize}
170 % \end{itemize}
171 % In principle you may use |\SVN| anywhere, but you may find problems
172 % if some package has made characters appearing in keywords active
173 % (e.g., \package{babel} with the |french| option---|\SVN| still works
174 % in the preamble though).
175 %
176 % \subsection{\texttt{\string\SVNdate}}
177 % Since you probably want to have the date of check-in the output of
178 % |\maketitle|, we provide the construct `|\SVNdate $Date$|' to do
179 % just that (note the difference between this and |\SVNDate|: the
180 % latter expands to the check-in time (or |\today|)). This is exactly
181 % the same as saying `|\SVN $Date$ \date{\SVNDate}|', but saves some
182 % typing.
183 %
184 %
185 % \subsection{Advanced Usage and Customisation}
186 % The default behaviour described above can be modified to do all
187 % kinds of fancy things with all kinds of fancy keywords. When you
188 % say |\SVN $keYwoRd: stuff$|, if the command |\SVN@keYwoRd@expanded|
189 % exists\footnote{As ever, `exists' means ``defined and not equal to
190 % `\texttt{\string\relax}'''} then it will be executed with two arguments:
191 % `|\SVN@keYwoRd@expanded{keYwoRd}{stuff : }|' (note the trailing
192 % `\verb*| : |'). If |\SVN@keYwoRd@expanded| does not exist then
193 % |\SVN@generic@expanded| is run (again with arguments
194 % `|{keYwoRd}{stuff : }|), which defines |\SVNkeYwoRD| to be |stuff|.
195 %
196 % If instead we had an unexpanded keyword (e.g., `|\SVN $keYwoRd$|')
197 % then \package{svn} will try and run
198 % |\SVNkeYwoRd@unexpanded{keYwoRd}{}|, falling back to
199 % |\SVN@generic@unexpanded{keYwoRd}{}| if
200 % |\SVN@keYwoRd@unexpanded| does not exist.
201 % |\SVN@generic@unexpanded{keYwoRd}{}| will define |\SVNkeYwoRd| to be
202 % |\SVNempty|, which is initially just |\relax|, but may be redefined
203 % (just use |\renewcommand|).
204 %
205 % So if you want some fancy behaviour for some fancy new keyword, you
206 % just need to define |\SVN@|\meta{Keyword}|@expanded| and
207 % |\SVN@|\meta{Keyword}|@unexpanded| to do what you want. Both variants
208 % should take two arguments which are \marg{KeywordName}\marg{expansion}.
209 % |\SVN@|\meta{Keyword}|@unexpanded| will be called with
210 % \meta{expansion} empty, and |\SVN@|\meta{Keyword}|@expanded| will
211 % be called with \meta{expansion} as the keyword expansion text plus a
212 % trailing `\verb*| : |' (which can be removed using the predefined
213 % |\svn@set| command---see the following example).
214 %
215 % As a simple example, |\SVN $Rev$| will define a
216 % |\SVNRev| command. Subversion treats |$LastChangedRevision$| as
217 % an alias for |$Rev$|, so if you wanted both
218 % |\SVN $Rev$| and |\SVN $LastChangedRevision$| to define both
219 % |\SVNLastChangedRevision| and |\SVNRev| then you
220 % could put the following in your preamble:
221 % \begin{verbatim}
222 % \makeatletter
223 % %%These first two are run when \SVN sees a `Rev' keyword.
224 % \def\SVN@Rev@unexpanded#1#2{%
225 % \let\SVNRev\SVNempty
226 % \let\SVNLastChangedRevision\SVNRev
227 % }
228 % %%The `@expanded' receives the keyword name as #1 and the
229 % %%keyword expansion (with trailing ` : ') as #2.
230 % \def\SVN@Rev@expanded#1#2{%
231 % \svn@set\SVNRev$#2$%
232 % \let\SVNLastChangedRevision\SVNRev
233 % }
234 % %%These next two lines make \SVN treat `LastChangedRevision'
235 % %%exactly the same as `Rev'
236 % \let\SVN@LastChangedRevision@unexpanded\SVN@Rev@unexpanded
237 % \let\SVN@LastChangedRevision@expanded\SVN@Rev@expanded
238 % \makeatother
239 % \end{verbatim}
240 % \subsection{Known Issues}
241 % If you use \package{babel} you will get the date produced by the
242 % |\SVNDate| command in the correct style for the current language,
243 % and if you change the language the text produced by |\SVNDate| may
244 % change. This may be undesirable, and the naïve solution is to say
245 % |\edef\SVNDateText{\SVNDate}| before the language change. However,
246 % with the code stolen from the \package{rcs}, inside an |\edef|,
247 % |\SVNDate| expands to |\today| whatever the check-in date. To work
248 % around this, |\SVNDate| has been designed to generate an error
249 % inside an |\edef|.
250 %
251 % One way to store the check-in date in a language-independent way is
252 % the following, which defines |\fixatedSVNDate| to be the german
253 % version of the check-in date, but note that
254 % |\edef\foo{\fixatedSVNDate}\foo| will still give |\today|'s date
255 % (and no error).
256 % \begin{verbatim}
257 % \def\fixateSVNDate{%
258 % \def\foo{\today}
259 % \ifx\SVNDate\foo
260 % \let\fixatedSVNDate\today
261 % \else
262 % \expandafter\fixateSVNDateExpanded\SVNDate
263 % \fi
264 % }
265 %
266 % \def\fixateSVNDateExpanded\begingroup#1\day#2\today\endgroup{%
267 % \let\fixedtoday\today
268 % \def\fixatedSVNDate{\begingroup\day#2\fixedtoday\endgroup}%
269 % }
270 %
271 % %% To fix the Date format, use \fixateSVNDate:
272 % \SVN $Date: 3999-07-30 14:58:54 +0100 (Thu, 30 Jul 3999) $
273 % german: \selectlanguage{german}\fixateSVNDate\SVNDate\\
274 % english : \selectlanguage{english} \SVNDate\\
275 % We still have access to german format: \fixatedSVNDate
276 % \end{verbatim}
277 %
278 % \subsection{Avoiding Unwanted Keyword Expansion}
279 % Although nothing to do with this package, the following may be
280 % useful.
281 %
282 % Sometimes your document contains strings of the form `|$...$|' which,
283 % although looking like keywords, should not be expanded by
284 % \Subversion. There are several ways to stop this expansion.
285 %
286 % Firstly, \Subversion\ only expands the keywords you tell it to,
287 % so if you say \shell{svn propset svn:keywords "Id" myfile.tex}
288 % (and then commit), |$Date$| will not be expanded anywhere. This
289 % leaves the case where you want to use something like
290 % |\SVNdate $Date$| at the top, but also use |$Date$| somewhere else.
291 % \begin{description}
292 % \item[In-line maths:] If you are using |$Date$| because it is the
293 % product of the variables $D$, $a$, $t$ and $e$, then you could use
294 % |\(Date\)| or replace the dollars with |^^24|: `|^^24Date^^24|'.
295 % \item[Verbatim:] If you want the string |$Date$|
296 % to appear verbatim in your \format{dvi}, then you could use
297 % |\texttt{\string$Date\string$}| (or use |\verb| around the |$|, but
298 % that will break in footnotes)
299 % \end{description}
300 %
301 % \StopEventually{\PrintIndex}
302 %
303 % \section{Implementation}
304 % \subsection{General Admin Stuff}
305 % \begin{macro}{\svn@date}
306 % \begin{macro}{\svn@revision}
307 % First we do the usual |\ProvidesPackage| stuff. Of course,
308 % \url{svn.dtx} is itself under \Subversion, and we want to get the
309 % package date and version from the \texttt{\string$Id\string$}
310 % keyword.
311 % \begin{macrocode}
312 \NeedsTeXFormat{LaTeX2e}
313 \def\next $Id: #1 #2 #3-#4-#5 #6${%
314 \def\svn@date{#3/#4/#5}%
315 \def\svn@revision{#2}%
316 }
317 \next $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
318 \edef\next{%
319 \noexpand\ProvidesPackage{svn}[\svn@date\space r\svn@revision\space
320 Typeset Subversion keywords.]%
321 }
322 \next
323 % \end{macrocode}
324 % \end{macro}
325 % \end{macro}
326 %
327 %\subsection{The generic \texttt{\string\SVN} command}
328 % \begin{macro}{\SVN}
329 % |\SVN| is the main construct (see above for
330 % usage). The single argument should be of the form
331 % |$|\meta{Keyword}|$| or
332 % |$|\meta{Keyword}:\meta{space}\meta{value}\meta{space}|$|, where \meta{Keyword}
333 % and \meta{value} must be non-empty as well as brace- and
334 % |\if|--|\fi|- balanced. \meta{space} is a single space (if more are
335 % present they will be subsumed into \meta{value}).
336 % If |$empty$|, |$generic$|, |$RawDate$|, or |$Time$| ever become
337 % keywords, or if keywords containing |@| ever exist then we may have
338 % problems.
339 % \begin{macrocode}
340 \def\SVN $#1${\svn@$#1: $}
341 % \end{macrocode}
342 % \end{macro}
343 %
344 % \begin{macro}{\SVNempty}
345 % If \meta{Keyword} is unexpanded then |\SVNKeyword| is |\let| to
346 % |\SVNempty|, which is initially empty.
347 % \begin{macrocode}
348 \newcommand{\SVNempty}{}
349 % \end{macrocode}
350 % \end{macro}
351 %
352 % \begin{macro}{\svn@}
353 % \begin{macro}{\svn@tmp}
354 % |\snv@| does the work for |\SVN|. It takes two arguments, the first
355 % is the \meta{Keyword}'s name, the second is empty (in which case
356 % \meta{Keyword} was unexpanded) or \meta{value}, the expansion of
357 % \meta{keyword}.
358 % \begin{macrocode}
359 \def\svn@$#1: #2${%
360 \def\svn@tmp{#2}%
361 % \end{macrocode}
362 % \begin{macro}{\svn@suffix}
363 % If \param2 is empty, then the keyword was unexpanded and
364 % |\svn@suffix| is set to |@unexpanded|, otherwise we had an expanded
365 % keyword so |\svn@suffix| is set to |@expanded|.
366 % \begin{macrocode}
367 \ifx\svn@tmp\@empty
368 \def\svn@suffix{@unexpanded}%
369 \else
370 \def\svn@suffix{@expanded}%
371 \fi
372 % \end{macrocode}
373 % If |\SVN@|\param1\meta{suffix} is defined
374 % then run it with arguments `\param1\param2', else
375 % run |\SVN@generic@|\meta{suffix} (again with argument
376 % \param1\param2---by default this defines `|\SVN|\meta{\param1}' to
377 % be \param2, or |\SVNempty| in the unexpanded case).
378 % \begin{macrocode}
379 \@ifundefined{SVN@#1\svn@suffix}%
380 {\@nameuse{SVN@generic\svn@suffix}{#1}{#2}}%
381 {\@nameuse{SVN@#1\svn@suffix}{#1}{#2}}%
382 }
383 % \end{macrocode}
384 % \end{macro}
385 % \end{macro}
386 % \end{macro}
387 %
388 % \subsection{Dealing with general \texttt{\string$Keyword\string$}s}
389 % \begin{macro}{\SVN@generic@expanded}
390 % When we see |\SVN $KeyWord: <stuff> $|, and no
391 % |\SVN@KeyWord@expanded| command exists, we use
392 % |\SVN@generic@expanded{KeyWord}{<stuff>}|
393 % to define |\SVNKeyWord| to be |<stuff>|.
394 % \begin{macrocode}
395 \def\SVN@generic@expanded#1#2{%
396 \expandafter\svn@set\csname SVN#1\endcsname$#2$%
397 }
398 % \end{macrocode}
399 % \end{macro}
400 %
401 % \begin{macro}{\SVN@generic@unexpanded}
402 % When we see |\SVN $KeyWord$| and no
403 % |\SVN@KeyWord@unexpanded| command exists, we use
404 % |\SVN@generic@unexpanded{KeyWord}|
405 % to define |\SVNKeyWord| to be |\SVNempty|.
406 % \begin{macrocode}
407 \def\SVN@generic@unexpanded#1#2{%
408 \expandafter\global\expandafter\let\csname SVN#1\endcsname\SVNempty
409 }
410 % \end{macrocode}
411 % \end{macro}
412 %
413 % \begin{macro}{\svn@set}
414 % |\svn@set#1$#2$| defines the command in \param{1} to be \param{2}
415 % without the trailing `\verb*| : |' that the call to |\svn@| added.
416 % \begin{macrocode}
417 \def\svn@set#1$#2 : ${\gdef#1{#2}}
418 % \end{macrocode}
419 % \end{macro}
420 %
421 % \subsection{Dealing with the \texttt{\string$Date\string$} keyword}
422 % \begin{macro}{\SVN@Date@unexpanded}
423 % \begin{macro}{\SVN@LastChangedDate@unexpanded}
424 % When we see a |\SVN $Date$| (or |\SVN $LastChangedDate$|), we
425 % define |\SVNDate| and |\SVNTime| to be the current date and
426 % time. The argument \param1 will be the name of the keyword
427 % actually used (i.e., |Date| or |LastChangedDate|), and \param2 will be
428 % empty since \param1 was not expanded.
429 % Note that we don't say |\let\SVNDate\today| as we want \package{babel} to
430 % be able to influence the formatting of |\SVNDate|.
431 % \begin{macrocode}
432 \def\SVN@Date@unexpanded#1#2{%
433 \gdef\SVNDate{\today}%
434 \global\let\SVNTime\SVNempty
435 \global\let\SVNRawDate\SVNempty
436 }
437 \let\SVN@LastChangedDate@unexpanded\SVN@Date@unexpanded
438 % \end{macrocode}
439 % \end{macro}
440 % \end{macro}
441 %
442 % \begin{macro}{\SVN@Date@expanded}
443 % \begin{macro}{\SVN@LastChangedDate@expanded}
444 % When we see |\SVN $Date: <date> <time> ... $|,
445 % we set |\SVNRawDate| to the whole `|<date> <time> ...|' string, and
446 % put the date and time of check-in into |\SVNDate| and
447 % |\SVNTime|.
448 % \begin{macrocode}
449 \def\SVN@Date@expanded#1#2{%
450 \svn@set\SVNRawDate$#2$%
451 \svn@parse@date$#2$%
452 }
453 \let\SVN@LastChangedDate@expanded\SVN@Date@expanded
454 % \end{macrocode}
455 % \end{macro}
456 % \end{macro}
457 % \begin{macro}{\svn@parse@date}
458 % \begin{macro}{\SVNDate}
459 % \begin{macro}{\SVNTime}
460 % |\svn@parse@date| is what actually puts the date of check-in (or
461 % |\today|) into |\SVNDate|. The idea for this is copied from the
462 % \package{rcs} package.
463 %
464 % We use the |$|'s to remove the leading space and then, inside a group,
465 % we change the current date and then call |\today|---this way if
466 % \package{babel} is used, we'll get |\SVNdate| in the correct
467 % language format. Since the |\day| commands are not
468 % expandable but |\today| is, we add a |\def| to give an error
469 % inside an |\edef| (see also the ``Known Issues'' section).
470 % \begin{macrocode}
471 \def\svn@parse@date$#1-#2-#3 #4:#5:#6 #7${%
472 \gdef\SVNDate{%
473 \begingroup
474 \def\svn@tmp{\PackageError{svn}{\SVNDate should not
475 be used in an \protect\edef}{See the svn.sty documentation for a
476 work-around.}}%
477 \day#3 \month#2 \year#1
478 \today
479 \endgroup}%
480 % \end{macrocode}
481 % We could add `GMT' to |\SVNTime|. Or not bother.
482 % \begin{macrocode}
483 \gdef\SVNTime{#4:#5:#6}%
484 }
485 % \end{macrocode}
486 % \end{macro}
487 % \end{macro}
488 % \end{macro}
489 %
490 % \begin{macro}{\SVNdate}
491 % |\SVNdate $Date$| puts the check-in date into the output of |\maketitle|.
492 % \begin{macrocode}
493 \def\SVNdate $#1${\SVN $#1$\date{\SVNDate}}
494 % \end{macrocode}
495 % \end{macro}
496 %
497 %
498 % \Finale
499 \endinput