summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/svn/svn.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/svn/svn.dtx')
-rw-r--r--macros/latex/contrib/svn/svn.dtx499
1 files changed, 499 insertions, 0 deletions
diff --git a/macros/latex/contrib/svn/svn.dtx b/macros/latex/contrib/svn/svn.dtx
new file mode 100644
index 0000000000..3d237b1a5b
--- /dev/null
+++ b/macros/latex/contrib/svn/svn.dtx
@@ -0,0 +1,499 @@
+% \iffalse meta-comment
+% $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
+% Copyright (C) 2003-7 by Richard Lewis <rpil2+svn.sty@rtf.org.uk>
+%
+% This file may be distributed and/or modified under the conditions
+% of the LaTeX Project Public License, either version 1.3 of this
+% license or (at your option) any later version. The latest version
+% of this license is in:
+%
+% http://www.latex-project.org/lppl.txt
+%
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2003/06/01 or later.
+%
+% This work has the LPPL maintenance status `maintained', and the
+% Current Maintainer of this work is Richard Lewis <rpil2+svn.sty@rtf.org.uk>.
+%
+% This work consists of all files listed in the `Contents' section of
+% the README file.
+%
+% \fi
+%
+% \iffalse
+%<*package>
+%\NeedsTeXFormat{LaTeX2e}
+%\def\svn@Id $Id: #1 #2 #3-#4-#5 #6$%
+% {\def\svn@date{#3/#4/#5}%
+% \def\svn@revision{#2}}
+%
+%\svn@Id $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
+%\edef\next{%
+% \noexpand\ProvidesPackage{svn}[\svn@date\space r\svn@revision\space
+% Typeset subversion keywords.]}
+%\next
+%</package>
+%
+%<*driver>
+\documentclass{ltxdoc}
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8x]{inputenc}
+ \usepackage[british]{babel}
+ \usepackage{lmodern} % ensures we use Type 1 fonts, comment this out to get Type 3 fonts
+ \usepackage{svn}
+ \EnableCrossrefs
+ \CodelineIndex
+%\OnlyDescription
+%\RecordChanges
+ \begin{document}
+ \DocInput{svn.dtx}
+ \end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{106}
+%
+% \CharacterTable
+% {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
+% 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
+% Digits \0\1\2\3\4\5\6\7\8\9
+% Exclamation \! Double quote \" Hash (number) \#
+% Dollar \$ Percent \% Ampersand \&
+% Acute accent \' Left paren \( Right paren \)
+% Asterisk \* Plus \+ Comma \,
+% Minus \- Point \. Solidus \/
+% Colon \: Semicolon \; Less than \<
+% Equals \= Greater than \> Question mark \?
+% Commercial at \@ Left bracket \[ Backslash \\
+% Right bracket \] Circumflex \^ Underscore \_
+% Grave accent \` Left brace \{ Vertical bar \|
+% Right brace \} Tilde \~}
+%
+% \GetFileInfo{svn.sty}
+% \DoNotIndex{\NeedsTeXFormat,\ProvidesPackage,\next}
+% \DoNotIndex{\newcommand,\def,\edef,\gdef,\global,\let}
+% \DoNotIndex{\noexpand,\expandafter,\csname,\endcsname}
+% \DoNotIndex{\protect}
+% \DoNotIndex{\if,\ifx,\else,\fi,\begingroup,\endgroup}
+% \DoNotIndex{\space,\@empty,\@ifundefined,\@nameuse}
+%
+%
+% \let\prog\textsf
+% \let\format\texttt
+% \def\shell#1{`\texttt{#1}'}
+% \let\package\textsf
+% \let\email\texttt
+% \let\url\texttt
+% \def\param#1{\texttt{\##1}}
+% \def\Subversion{\prog{Subversion}}
+% \def\CVS{\prog{CVS}}
+% \def\RCS{\prog{RCS}}
+%
+% \title{The \package{svn} package\thanks{This document
+% corresponds to \package{svn}~\fileversion, dated \filedate.}}
+% \author{Richard Lewis \\ \email{rpil2+svn.sty@rtf.org.uk}}
+%
+% \def\convertfiledate/#1/#2/#3/{%
+% \def\convertedfiledate{\begingroup\day#3 \month#2 \year#1 \today\endgroup}
+% }
+% \expandafter\convertfiledate\expandafter/\filedate/
+% \date{\convertedfiledate}
+% \maketitle
+%
+% \section{Introduction}
+% \Subversion\ is a replacement for \CVS\ and \RCS. It is similar to
+% \CVS\ but with some improvements (e.g., it understands
+% renaming and deletion of version controlled files---see
+% \url{http://subversion.tigris.org/} for more information). As with
+% \CVS\ and \RCS, a file registered with \Subversion\ may
+% contain keywords (such as |$Date$| or |$Revision$|) that
+% \Subversion\ will replace with status information about the file
+% (such as the date the file was last committed, or the revision at
+% which it last changed).\footnote{Unlike \RCS\ and \CVS, the
+% expansion of such keywords is customisable, and not enabled by
+% default: use \shell{svn propset svn:keywords "Date Id" myfile.tex}
+% to tell \Subversion\ to expand the keywords
+% \texttt{\string$Date\string$} and \texttt{\string$Id\string$} in
+% \shell{myfile.tex}.}
+%
+% For typesetting the contents of \RCS\ and \CVS\ keywords
+% there is the \package{rcs} package\footnote{Written by Joachim
+% Schrod with minor modification by Jeffrey Goldberg}; although highly
+% recommended, that package does not cope with the format of
+% \Subversion's |$Date$| keyword, so I wrote the \package{svn} package
+% to do just that.
+%
+% \section{Usage}
+% \subsection{Quick Example}
+% The main use for this package is to get the date the file was last
+% committed into the output of |\maketitle|. The solution is simple:
+%
+% \begin{verbatim}
+% \documentclass{article}
+% \usepackage{svn}
+% \SVNdate $Date$
+% \title{Hope this works}
+%
+% \begin{document}
+% \maketitle
+% \end{document}
+% \end{verbatim}
+%
+% \subsection{More General Usage}
+% As usual, load the \package{svn} package with |\usepackage{svn}|.
+%
+% The main command is |\SVN $|\meta{Keyword}|$| (which mimics
+% `|\RCS $|\meta{Keyword}|$|' from the \package{rcs} package).
+% By default the following happens:
+% \begin{itemize}
+% \item If you say |\SVN $Keyword: stuff $| (i.e,
+% |$Keyword$| has been expanded to `|stuff|') then:
+% \begin{itemize}
+% \item If |$Keyword$| is |$Date$| or |$\LastChangedDate$|, then
+% |stuff| is parsed and |\SVNDate| is defined to be the date, and
+% |\SVNTime| the time, that the file was checked in. |\SVNRawDate|
+% is defined to be the whole string `|stuff|'.
+% \item Otherwise a command |\SVNKeyword| is defined to be
+% `|stuff|'.
+% \end{itemize}
+% \item If you say |\SVN $Keyword$| (i.e., |$Keyword$| was
+% not expanded---perhaps it doesn't appear in the \url{svn:keywords}
+% property, or perhaps the file has not been checked in since the
+% line was added), then:
+% \begin{itemize}
+% \item If |$Keyword$| is |$Date$| (or |$\LastChangedDate$|),
+% |\SVNDate| is defined to be |\today|, and |\SVNTime| and
+% |\SVNRawDate| are set to |\SVNempty| (which is empty by default,
+% and may be changed with |\renewcommand|).
+% \item Otherwise |\SVNKeyword| is defined to be |\SVNempty|.
+% \end{itemize}
+% \end{itemize}
+% In principle you may use |\SVN| anywhere, but you may find problems
+% if some package has made characters appearing in keywords active
+% (e.g., \package{babel} with the |french| option---|\SVN| still works
+% in the preamble though).
+%
+% \subsection{\texttt{\string\SVNdate}}
+% Since you probably want to have the date of check-in the output of
+% |\maketitle|, we provide the construct `|\SVNdate $Date$|' to do
+% just that (note the difference between this and |\SVNDate|: the
+% latter expands to the check-in time (or |\today|)). This is exactly
+% the same as saying `|\SVN $Date$ \date{\SVNDate}|', but saves some
+% typing.
+%
+%
+% \subsection{Advanced Usage and Customisation}
+% The default behaviour described above can be modified to do all
+% kinds of fancy things with all kinds of fancy keywords. When you
+% say |\SVN $keYwoRd: stuff$|, if the command |\SVN@keYwoRd@expanded|
+% exists\footnote{As ever, `exists' means ``defined and not equal to
+% `\texttt{\string\relax}'''} then it will be executed with two arguments:
+% `|\SVN@keYwoRd@expanded{keYwoRd}{stuff : }|' (note the trailing
+% `\verb*| : |'). If |\SVN@keYwoRd@expanded| does not exist then
+% |\SVN@generic@expanded| is run (again with arguments
+% `|{keYwoRd}{stuff : }|), which defines |\SVNkeYwoRD| to be |stuff|.
+%
+% If instead we had an unexpanded keyword (e.g., `|\SVN $keYwoRd$|')
+% then \package{svn} will try and run
+% |\SVNkeYwoRd@unexpanded{keYwoRd}{}|, falling back to
+% |\SVN@generic@unexpanded{keYwoRd}{}| if
+% |\SVN@keYwoRd@unexpanded| does not exist.
+% |\SVN@generic@unexpanded{keYwoRd}{}| will define |\SVNkeYwoRd| to be
+% |\SVNempty|, which is initially just |\relax|, but may be redefined
+% (just use |\renewcommand|).
+%
+% So if you want some fancy behaviour for some fancy new keyword, you
+% just need to define |\SVN@|\meta{Keyword}|@expanded| and
+% |\SVN@|\meta{Keyword}|@unexpanded| to do what you want. Both variants
+% should take two arguments which are \marg{KeywordName}\marg{expansion}.
+% |\SVN@|\meta{Keyword}|@unexpanded| will be called with
+% \meta{expansion} empty, and |\SVN@|\meta{Keyword}|@expanded| will
+% be called with \meta{expansion} as the keyword expansion text plus a
+% trailing `\verb*| : |' (which can be removed using the predefined
+% |\svn@set| command---see the following example).
+%
+% As a simple example, |\SVN $Rev$| will define a
+% |\SVNRev| command. Subversion treats |$LastChangedRevision$| as
+% an alias for |$Rev$|, so if you wanted both
+% |\SVN $Rev$| and |\SVN $LastChangedRevision$| to define both
+% |\SVNLastChangedRevision| and |\SVNRev| then you
+% could put the following in your preamble:
+% \begin{verbatim}
+% \makeatletter
+% %%These first two are run when \SVN sees a `Rev' keyword.
+% \def\SVN@Rev@unexpanded#1#2{%
+% \let\SVNRev\SVNempty
+% \let\SVNLastChangedRevision\SVNRev
+% }
+% %%The `@expanded' receives the keyword name as #1 and the
+% %%keyword expansion (with trailing ` : ') as #2.
+% \def\SVN@Rev@expanded#1#2{%
+% \svn@set\SVNRev$#2$%
+% \let\SVNLastChangedRevision\SVNRev
+% }
+% %%These next two lines make \SVN treat `LastChangedRevision'
+% %%exactly the same as `Rev'
+% \let\SVN@LastChangedRevision@unexpanded\SVN@Rev@unexpanded
+% \let\SVN@LastChangedRevision@expanded\SVN@Rev@expanded
+% \makeatother
+% \end{verbatim}
+% \subsection{Known Issues}
+% If you use \package{babel} you will get the date produced by the
+% |\SVNDate| command in the correct style for the current language,
+% and if you change the language the text produced by |\SVNDate| may
+% change. This may be undesirable, and the naïve solution is to say
+% |\edef\SVNDateText{\SVNDate}| before the language change. However,
+% with the code stolen from the \package{rcs}, inside an |\edef|,
+% |\SVNDate| expands to |\today| whatever the check-in date. To work
+% around this, |\SVNDate| has been designed to generate an error
+% inside an |\edef|.
+%
+% One way to store the check-in date in a language-independent way is
+% the following, which defines |\fixatedSVNDate| to be the german
+% version of the check-in date, but note that
+% |\edef\foo{\fixatedSVNDate}\foo| will still give |\today|'s date
+% (and no error).
+% \begin{verbatim}
+% \def\fixateSVNDate{%
+% \def\foo{\today}
+% \ifx\SVNDate\foo
+% \let\fixatedSVNDate\today
+% \else
+% \expandafter\fixateSVNDateExpanded\SVNDate
+% \fi
+% }
+%
+% \def\fixateSVNDateExpanded\begingroup#1\day#2\today\endgroup{%
+% \let\fixedtoday\today
+% \def\fixatedSVNDate{\begingroup\day#2\fixedtoday\endgroup}%
+% }
+%
+% %% To fix the Date format, use \fixateSVNDate:
+% \SVN $Date: 3999-07-30 14:58:54 +0100 (Thu, 30 Jul 3999) $
+% german: \selectlanguage{german}\fixateSVNDate\SVNDate\\
+% english : \selectlanguage{english} \SVNDate\\
+% We still have access to german format: \fixatedSVNDate
+% \end{verbatim}
+%
+% \subsection{Avoiding Unwanted Keyword Expansion}
+% Although nothing to do with this package, the following may be
+% useful.
+%
+% Sometimes your document contains strings of the form `|$...$|' which,
+% although looking like keywords, should not be expanded by
+% \Subversion. There are several ways to stop this expansion.
+%
+% Firstly, \Subversion\ only expands the keywords you tell it to,
+% so if you say \shell{svn propset svn:keywords "Id" myfile.tex}
+% (and then commit), |$Date$| will not be expanded anywhere. This
+% leaves the case where you want to use something like
+% |\SVNdate $Date$| at the top, but also use |$Date$| somewhere else.
+% \begin{description}
+% \item[In-line maths:] If you are using |$Date$| because it is the
+% product of the variables $D$, $a$, $t$ and $e$, then you could use
+% |\(Date\)| or replace the dollars with |^^24|: `|^^24Date^^24|'.
+% \item[Verbatim:] If you want the string |$Date$|
+% to appear verbatim in your \format{dvi}, then you could use
+% |\texttt{\string$Date\string$}| (or use |\verb| around the |$|, but
+% that will break in footnotes)
+% \end{description}
+%
+% \StopEventually{\PrintIndex}
+%
+% \section{Implementation}
+% \subsection{General Admin Stuff}
+% \begin{macro}{\svn@date}
+% \begin{macro}{\svn@revision}
+% First we do the usual |\ProvidesPackage| stuff. Of course,
+% \url{svn.dtx} is itself under \Subversion, and we want to get the
+% package date and version from the \texttt{\string$Id\string$}
+% keyword.
+% \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}
+\def\next $Id: #1 #2 #3-#4-#5 #6${%
+ \def\svn@date{#3/#4/#5}%
+ \def\svn@revision{#2}%
+}
+\next $Id: svn.dtx 43 2007-09-25 19:20:04Z repos $
+\edef\next{%
+ \noexpand\ProvidesPackage{svn}[\svn@date\space r\svn@revision\space
+ Typeset Subversion keywords.]%
+}
+\next
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%\subsection{The generic \texttt{\string\SVN} command}
+% \begin{macro}{\SVN}
+% |\SVN| is the main construct (see above for
+% usage). The single argument should be of the form
+% |$|\meta{Keyword}|$| or
+% |$|\meta{Keyword}:\meta{space}\meta{value}\meta{space}|$|, where \meta{Keyword}
+% and \meta{value} must be non-empty as well as brace- and
+% |\if|--|\fi|- balanced. \meta{space} is a single space (if more are
+% present they will be subsumed into \meta{value}).
+% If |$empty$|, |$generic$|, |$RawDate$|, or |$Time$| ever become
+% keywords, or if keywords containing |@| ever exist then we may have
+% problems.
+% \begin{macrocode}
+\def\SVN $#1${\svn@$#1: $}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SVNempty}
+% If \meta{Keyword} is unexpanded then |\SVNKeyword| is |\let| to
+% |\SVNempty|, which is initially empty.
+% \begin{macrocode}
+\newcommand{\SVNempty}{}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\svn@}
+% \begin{macro}{\svn@tmp}
+% |\snv@| does the work for |\SVN|. It takes two arguments, the first
+% is the \meta{Keyword}'s name, the second is empty (in which case
+% \meta{Keyword} was unexpanded) or \meta{value}, the expansion of
+% \meta{keyword}.
+% \begin{macrocode}
+\def\svn@$#1: #2${%
+ \def\svn@tmp{#2}%
+% \end{macrocode}
+% \begin{macro}{\svn@suffix}
+% If \param2 is empty, then the keyword was unexpanded and
+% |\svn@suffix| is set to |@unexpanded|, otherwise we had an expanded
+% keyword so |\svn@suffix| is set to |@expanded|.
+% \begin{macrocode}
+ \ifx\svn@tmp\@empty
+ \def\svn@suffix{@unexpanded}%
+ \else
+ \def\svn@suffix{@expanded}%
+ \fi
+% \end{macrocode}
+% If |\SVN@|\param1\meta{suffix} is defined
+% then run it with arguments `\param1\param2', else
+% run |\SVN@generic@|\meta{suffix} (again with argument
+% \param1\param2---by default this defines `|\SVN|\meta{\param1}' to
+% be \param2, or |\SVNempty| in the unexpanded case).
+% \begin{macrocode}
+ \@ifundefined{SVN@#1\svn@suffix}%
+ {\@nameuse{SVN@generic\svn@suffix}{#1}{#2}}%
+ {\@nameuse{SVN@#1\svn@suffix}{#1}{#2}}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \subsection{Dealing with general \texttt{\string$Keyword\string$}s}
+% \begin{macro}{\SVN@generic@expanded}
+% When we see |\SVN $KeyWord: <stuff> $|, and no
+% |\SVN@KeyWord@expanded| command exists, we use
+% |\SVN@generic@expanded{KeyWord}{<stuff>}|
+% to define |\SVNKeyWord| to be |<stuff>|.
+% \begin{macrocode}
+\def\SVN@generic@expanded#1#2{%
+ \expandafter\svn@set\csname SVN#1\endcsname$#2$%
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\SVN@generic@unexpanded}
+% When we see |\SVN $KeyWord$| and no
+% |\SVN@KeyWord@unexpanded| command exists, we use
+% |\SVN@generic@unexpanded{KeyWord}|
+% to define |\SVNKeyWord| to be |\SVNempty|.
+% \begin{macrocode}
+\def\SVN@generic@unexpanded#1#2{%
+ \expandafter\global\expandafter\let\csname SVN#1\endcsname\SVNempty
+}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\svn@set}
+% |\svn@set#1$#2$| defines the command in \param{1} to be \param{2}
+% without the trailing `\verb*| : |' that the call to |\svn@| added.
+% \begin{macrocode}
+\def\svn@set#1$#2 : ${\gdef#1{#2}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Dealing with the \texttt{\string$Date\string$} keyword}
+% \begin{macro}{\SVN@Date@unexpanded}
+% \begin{macro}{\SVN@LastChangedDate@unexpanded}
+% When we see a |\SVN $Date$| (or |\SVN $LastChangedDate$|), we
+% define |\SVNDate| and |\SVNTime| to be the current date and
+% time. The argument \param1 will be the name of the keyword
+% actually used (i.e., |Date| or |LastChangedDate|), and \param2 will be
+% empty since \param1 was not expanded.
+% Note that we don't say |\let\SVNDate\today| as we want \package{babel} to
+% be able to influence the formatting of |\SVNDate|.
+% \begin{macrocode}
+\def\SVN@Date@unexpanded#1#2{%
+ \gdef\SVNDate{\today}%
+ \global\let\SVNTime\SVNempty
+ \global\let\SVNRawDate\SVNempty
+}
+\let\SVN@LastChangedDate@unexpanded\SVN@Date@unexpanded
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\SVN@Date@expanded}
+% \begin{macro}{\SVN@LastChangedDate@expanded}
+% When we see |\SVN $Date: <date> <time> ... $|,
+% we set |\SVNRawDate| to the whole `|<date> <time> ...|' string, and
+% put the date and time of check-in into |\SVNDate| and
+% |\SVNTime|.
+% \begin{macrocode}
+\def\SVN@Date@expanded#1#2{%
+ \svn@set\SVNRawDate$#2$%
+ \svn@parse@date$#2$%
+}
+\let\SVN@LastChangedDate@expanded\SVN@Date@expanded
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\svn@parse@date}
+% \begin{macro}{\SVNDate}
+% \begin{macro}{\SVNTime}
+% |\svn@parse@date| is what actually puts the date of check-in (or
+% |\today|) into |\SVNDate|. The idea for this is copied from the
+% \package{rcs} package.
+%
+% We use the |$|'s to remove the leading space and then, inside a group,
+% we change the current date and then call |\today|---this way if
+% \package{babel} is used, we'll get |\SVNdate| in the correct
+% language format. Since the |\day| commands are not
+% expandable but |\today| is, we add a |\def| to give an error
+% inside an |\edef| (see also the ``Known Issues'' section).
+% \begin{macrocode}
+\def\svn@parse@date$#1-#2-#3 #4:#5:#6 #7${%
+ \gdef\SVNDate{%
+ \begingroup
+ \def\svn@tmp{\PackageError{svn}{\SVNDate should not
+ be used in an \protect\edef}{See the svn.sty documentation for a
+ work-around.}}%
+ \day#3 \month#2 \year#1
+ \today
+ \endgroup}%
+% \end{macrocode}
+% We could add `GMT' to |\SVNTime|. Or not bother.
+% \begin{macrocode}
+ \gdef\SVNTime{#4:#5:#6}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\SVNdate}
+% |\SVNdate $Date$| puts the check-in date into the output of |\maketitle|.
+% \begin{macrocode}
+\def\SVNdate $#1${\SVN $#1$\date{\SVNDate}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \Finale
+\endinput