vrsion – a L^{A}TEX Macro for version Numbering of Files^{∗}

Mats Dahlgren

                         (matsd@homenet.se)

1997/02/22

Abstract The vrsion package provides a user-friendly way to introduce file version numbers in L^{A}TEX documents. It remembers the previous version number, also when the .aux-file is corrupted (due to errors in the L^{A}TEX run). This file and the package: Copyright \begin{matrix}c \\ ◯ \end{matrix} 1994-97 by Mats Dahlgren. All rights reserved.

1 Introduction

\version This package provides one command, \version, which puts a version number where it appears. The version number is increased each time L^{A}TEX is run, i.e. it numbers the .dvi-file. If the package is loaded but the command \version is not issued, the present version number is preserved. Numbering can be incremented at three different levels: units, tenths, and hundreds. A change between two of these is obtained by changing the package option. After a change of steplength, the previous version number is incremented with the new steplength. The version number can be

\keepversion held constant by using the command \keepversion; this enables the version number to be printed \stepversion without being increased. (\keepversion can be overridden by the command \stepversion.)

2 Userguide

2.1 Requirements

The file vrsion.sty must be available in the user’s TEXINPUTS directories. It requires L^{A}TEX 2ε of 1995/12/01 (or newer).

2.2 Usage

The package is included by stating

  \usepackage[option]{vrsion}

one in the document preamble. It can take one of the options one, ten, and hundred, and in addi-

ten
hundred
xspace

tion xspace. To produce a version number anywhere in your document you issue the command

\version

\version at the desired place in your L^{A}TEX input file.^{1} The version number will then be incremented each time you run L^{A}TEX on the file. The command \version is robust.^{2} Depending on the option used, the version number will be an integer (no option or option one), a number with one decimal (option ten), or a two-decimal number (option hundred). If the option xspace is specified, the xspace package is loaded and its features are benefited from. (If the xspace package is loaded by a separate \usepackage statement or by another package, its features are used by vrsion.)

∗This document describes vrsion version 1.41, and was last revised on 1997/02/22.

1Notice that the text “version” is not produced by the \version command.

2Thanks to Timothy Robertson (timothyr@cmbr.phys.cmu.edu) for bringing my attention to the problem of \version being fragile.

When changing from one option (of one, ten, or hundred) to another, the previous format of the version number will be changed according to the new option. If a smaller increment is specified, the next increment will simply append one digit 1 to the old version number; e.g. a change from option ten to hundred after version 3.2 will result in version 3.21. If a larger increment is specified, the old version number will be truncated before the increment; e.g. a change from option hundred to ten after version 3.25 will result in version 3.3. You should (normally) not use the command \version more once in a document. The version number is stored in a file with extension ‘vrs’ in the default directory. (The full name of this file is \jobname.vrs.)

If you want your document to contain a version number without having it incremented each

\keepversion time you run L^{A}TEX, you should issue the command \keepversion in the document (preamble). This switches off the incrementation mechanism and prevents the package from writing an updated .vrs-file. The \keepversion command can be cancelled at any later place in the document by

\stepversion issuing the command \stepversion. The action taken by the \version command is determined

by which of these two was last issued.

Typically, you would load the vrsion package with the desired option and use the command \version where you want your document to state its version number. Normally, you would have the \keepversion command in the preamble, but comment it out on the first L^{A}TEX run when you prepare to print a new version and then have the \keepversion in action during the L^{A}TEX runs needed to resolve the references.

When it is desired to repeat the version number several times in a document, issue a \keepversion directly after the first use of \version. This will then produce the same version number at all occurrences; and the version number will be incremented according to the use of \keepversion in the preamble.

If the increase of the version number is to occur at any stage later than the fist occurrence of \version, the occurrence of \version which is to increase the version number should be preceeded by a \stepversion command (and followed by \keepversion to prevent further increments). The author can not think of any reason why this should be desired, but it can be achieved anyway…

2.3 Known Problems

• At the present (1997/02/22), vrsion does not work properly with neither the letter nor the scrlettr document classes.

• The \vrsion package is not working properly with the \include{file} command; use \input{file} instead.

• If the command \version is issued more than once in a document, the version number will be incremented at each occurrence and produce different version numbers at the different occurrences (unless \keepversion is in effect). This may typically be a problem if you use \version in the page header or footer. This is avoided if \keepversion is issued somewhere on the second page.

3 History

The first version of the package was released in late December of 1994. The package was created with useful help and ideas from Johan Fröberg (emgion@physchem.kth.se).

The vrsion package version 1.41 has been tested with L^{A}TEX 2ε of 1996/06/01 running TEX 3.14159 under OpenVMS. Please send bug reports (see below), corrections, additions, suggestions,

etc. to me at matsd@physchem.kth.se.

3.1 Changes from previous versions

In vrsion (version) version 1.0 the macro \@skrivner caused extra space to be inserted in front of the version number. With vrsion version 1.1 and later this is avoided.

In version 1.1 the vrsion package had incompatibility problems with the babel package.^{3} With vrsion version 1.2 this problem is eliminated. Also, the command \version has been made robust.

In version 1.3, some adjustments to changes in the babel package have been made,^{4} if the xspace package is loaded, its features are made use of. Also, some problems with \maketitle issuing extra blank page(s) have been eliminated,^{5} it seems (at least for the article, report, and book classes). Furthermore, some cosmetics in the installation routine have been added.

Version 1.4 eliminated an incompatibility with the koma-script package. The incompatibility was that some features of koma-script’s version of the \maketitle command were lost when vrsion was loaded.^{6} Furthermore, some \typeout statements have been removed and the processing order of some of the macro definitions has been changed.

4 Sending a Bug Report

vrsion is most likely to contain bugs. Reports of bugs in the package are most welcome. When filing a bug report, please take the following actions:

1. Ensure your problem is not due to your inputfile;

2. Ensure your problem is not due to your own package(s) or class(es);

3. Ensure your problem is not covered in the section ”Known Problems” above;

4. Try to locate the problem by writing a minimal L^{A}TEX input file which reproduces the problem.

Include the command

       \setcounter{errorcontextlines}{999}

in your input;

5. Run your file through L^{A}TEX;

6. Send a description of your problem, the input file and the log file via e-mail to:

        matsd@homenet.se.

Enjoy your L^{A}TEX!mats d.

3Thanks to Peter Ryder (ryder@theo.physik.uni-bremen.de) for bringing my attention to this problem.

4Thanks to Cornelius C. Noack (noack@physik.uni-bremen.de) for bringing my attention to the re-appearance of the babel incompatibility.

5Thanks to Ludek Matyska (ludek@muni.cz) for pointing out this problem.

6Thanks to Christofer P. Baron (baron@iml.fgh.de) for bringing my attention to this problem.

5 The Code

For the interested reader(s), here is a short description of the code.

First, the package should identify itself:

 1 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
 2 \ProvidesPackage{vrsion}%
 3 [1997/02/22 version numbering of LaTeX files (v.1.41).]

Some counters and booleans used are to be defined first. Also the user commands \keepversion and \stepversion, which only (re-)set the Keepversion boolean, are defined.

 4 \newcounter{versionnr}
 5 \newcounter{versionnrten}[versionnr]
 6 \newcounter{versionnrhundred}[versionnrten]
 7 \@addtoreset{versionnrhundred}{versionnr}
 8 \newif\ifKeepversion \Keepversionfalse
 9 \newif\ifxspc \xspcfalse
10 \newcommand{\keepversion}{\global\Keepversiontrue}
11 \newcommand{\stepversion}{\global\Keepversionfalse}

Next, the options are declared. The declaration of option one is the default version of the \version macro. If the boolean Keepversion (set by the command \keepversion) is true, no increase of the version number is preformed, nor is anything written to the .vrs-file. The command \@skrivner is responsible for writing the .vrs-file (“skriv ner” is Swedish for “write down”).

12 \DeclareOption{one}{%
13 \DeclareRobustCommand{\version}{%
14 \ifKeepversion \else
15  \stepcounter{versionnr}%
16  \@skrivner
17 \fi
18 \theversionnr%
19 \@ifundefined{xspace}{}{\xspace}%

20 } 21 }

The ten option modifies the \version command to produce a decimal number and steps the integer version number if the decimal part reaches 10.

22 \DeclareOption{ten}{%
23 \DeclareRobustCommand{\version}{%
24  \ifKeepversion \else
25  \stepcounter{versionnrten}%
26  \ifnum\theversionnrten=10\stepcounter{versionnr} \fi
27  \@skrivner
28  \fi
29  \theversionnr .\theversionnrten%
30  \@ifundefined{xspace}{}{\xspace}%

31 } 32 }

The option hundred does the same as ten, but with a two-decimal number.

33 \DeclareOption{hundred}{%
34 \DeclareRobustCommand{\version}{%
35  \ifKeepversion \else
36  \stepcounter{versionnrhundred}%
37  \ifnum\theversionnrhundred=10\stepcounter{versionnrten} \fi
38  \ifnum\theversionnrten=10\stepcounter{versionnr} \fi

39  \@skrivner
40  \fi
41  \theversionnr .\theversionnrten\theversionnrhundred%
42  \@ifundefined{xspace}{}{\xspace}%

43 } 44 }

The xspace option, which only forces the xspace package to be loaded, is quite short in the code:

45 \DeclareOption{xspace}{\global\xspctrue}

All other options which may be specified are to be ignored:

46 \DeclareOption*{\OptionNotUsed}

Now we can process the options, and – if requested – load the xspace package.

47 \ExecuteOptions{one}
48 \ProcessOptions
49 \ifxspc\RequirePackage{xspace}\fi

Now the task is to define the internals. The macro \vrsFile simply holds the name of the .vrs-file to use. The macro \@skrivner writes the version number counters to a file in a format which is easy to deal with in L^{A}TEX, a name-wise change^{7} of the the ordinary \label format. The internal macro \@vrs is used to avoid problems with label change warnings and to avoid trouble with missing version number information in the .aux-file when \keepversion is used. As an aid, the dummy-counter VrsNr is used.

50 \def\vrsFile{\jobname.vrs}
51 \newwrite\@vrs
52 \newcounter{VrsNr}
53 \def\@skrivner{%
54 \setcounter{VrsNr}{\@partaux}%
55 \addtocounter{VrsNr}{1}%
56 \let\@vrs=\theVrsNr%
57 \immediate\openout\@vrs\vrsFile%
58 \immediate\write\@vrs{\relax}%
59 \immediate\write\@vrs{%
60  \string\vrslabel{versionsnummer}{{\theversionnr}{\thepage}}}%
61 \immediate\write\@vrs{%
62  \string\vrslabel{versionsnummertio}{{\theversionnrten}{\thepage}}}%
63 \immediate\write\@vrs{%
64  \string\vrslabel{versionsnummerhundra}{{\theversionnrhundred}{\thepage}}
65 }%
66 \immediate\closeout\@vrs{}%

67 }

babel compatibility is obtained by defining special \label and \ref commands.

68 \@ifundefined{bbl@ref}{\let\vrsref=\ref}{\let\vrsref=\bbl@ref}
69 \@ifundefined{bbl@newlabel}{\let\vrslabel=\newlabel}%
70 {\let\vrslabel=\bbl@newlabel}

If it exists, the file \jobname.vrs should be read, and the counters set accordingly. If this file is missing, the counters should be zero.

71 \IfFileExists{\vrsFile}{\@@input\vrsFile%
72  \setcounter{versionnr}{\vrsref{versionsnummer}}%
73  \setcounter{versionnrten}{\vrsref{versionsnummertio}}%
74  \setcounter{versionnrhundred}{\vrsref{versionsnummerhundra}}%

7This was nessecary to make vrsion compatible with babel.

75 }{%
76  \typeout{No file \vrsFile.}%
77  \setcounter{versionnr}{\z@}%
78  \setcounter{versionnrten}{\z@}%
79  \setcounter{versionnrhundred}{\z@}%

80 }

To prevent \maketitle from creating extra blank pages, some commands from the L^{A}TEX 2ε kernel have to be slightly modified. To make sure we use the desired definitions, the changes are issued in an \AtBeginDocument command. (The changes are that a few \newpage commands have been removed and that a \cleardoublepage has been removed for the book class.) To cope with the incompatibility of the koma-script package, different modified definitions are used. Which is to be used is tested in an \@ifundefined statement.

81 \AtBeginDocument{%
82 \@ifundefined{subject}{%
83 \if@titlepage
84 \renewcommand\maketitle{\begin{titlepage}%
85 \let\footnotesize\small
86 \let\footnoterule\relax
87 \let \footnote \thanks
88 \null\vfil
89 \vskip 60\p@
90 \begin{center}%
91  {\LARGE \@title \par}%
92  \vskip 3em%
93  {\large
94  \lineskip .75em%
95  \begin{tabular}[t]{c}%
96  \@author
97  \end{tabular}\par}%
98  \vskip 1.5em%
99  {\large \@date \par}%
100 \end{center}\par
101 \@thanks
102 \vfil\null
103 \end{titlepage}%
104 \setcounter{footnote}{0}%
105 \global\let\thanks\relax
106 \global\let\maketitle\relax
107 \global\let\@thanks\@empty
108 \global\let\@author\@empty
109 \global\let\@date\@empty
110 \global\let\@title\@empty
111 \global\let\title\relax
112 \global\let\author\relax
113 \global\let\date\relax
114 \global\let\and\relax

115 }

116 \else
117 \renewcommand\maketitle{\par
118 \begingroup
119  \renewcommand\thefootnote{\@fnsymbol\c@footnote}%
120  \def\@makefnmark{\rlap{\@textsuperscript{\normalfont\@thefnmark}}}%
121  \long\def\@makefntext##1{\parindent 1em\noindent

122  \hb@xt@1.8em{%
123  \hss\@textsuperscript{\normalfont\@thefnmark}}##1}%
124  \if@twocolumn
125  \ifnum \col@number=\@ne
126  \@maketitle
127  \else
128  \twocolumn[\@maketitle]%
129  \fi
130  \else
131  \global\@topnum\z@
132  \@maketitle
133  \fi
134  \thispagestyle{plain}\@thanks
135 \endgroup
136 \setcounter{footnote}{0}%
137 \global\let\thanks\relax
138 \global\let\maketitle\relax
139 \global\let\@maketitle\relax
140 \global\let\@thanks\@empty
141 \global\let\@author\@empty
142 \global\let\@date\@empty
143 \global\let\@title\@empty
144 \global\let\title\relax
145 \global\let\author\relax
146 \global\let\date\relax
147 \global\let\and\relax

148 }

149 \def\@maketitle{%
150 \null
151 \vskip 2em%
152 \begin{center}%
153 \let \footnote \thanks
154  {\LARGE \@title \par}%
155  \vskip 1.5em%
156  {\large
157  \lineskip .5em%
158  \begin{tabular}[t]{c}%
159  \@author
160  \end{tabular}\par}%
161  \vskip 1em%
162  {\large \@date}%
163 \end{center}%
164 \par
165 \vskip 1.5em}
166 \fi%
167 \renewenvironment{titlepage}{%
168  \if@twocolumn
169  \@restonecoltrue\onecolumn
170  \else
171  \@restonecolfalse
172  \fi
173  \thispagestyle{empty}%
174  \setcounter{page}\@ne

175 }%

176  {\if@restonecol\twocolumn \else \newpage \fi
177  \if@twoside\else
178  \setcounter{page}\@ne
179  \fi

180 }

181 }{%

So much for the ordinary L^{A}TEX 2ε kernel code. Next follows the code borrowed from the koma-script bundle by Markus Kohm,^{8} also with some modifications.

182 \if@titlepage
183  \newcommand*\maketitle[1][1]{\begin{titlepage}%
184  \setcounter{page}{#1}
185  \let\footnotesize\small
186  \let\footnoterule\relax
187  \let\footnote\thanks
188  \ifx\@extratitle\@empty \else
189  \noindent\@extratitle\next@tpage\thispagestyle{empty}
190  \fi
191  \ifx\@titlehead\@empty \else
192  \noindent\begin{minipage}[t]{\textwidth}
193  \@titlehead
194  \end{minipage}\par
195  \fi
196  \null\vfill
197  \begin{center}
198  \ifx\@subject\@empty \else
199  {\Large \@subject \par}
200  \vskip 3em
201  \fi
202  {\huge {\sectfont \@title \par}}
203  \vskip 3em
204  {\Large \lineskip 0.75em
205  \begin{tabular}[t]{c}
206  \@author
207  \end{tabular}\par}
208  \vskip 1.5em
209  {\Large \@date \par}
210  \vskip \z@ \@plus3fill
211  {\Large \@publishers \par}
212  \vskip 3em
213  \end{center}\par
214  \@thanks
215  \vfill\null
216  \if@twoside\next@tpage
217  \noindent\begin{minipage}[t]{\textwidth}
218  \@uppertitleback
219  \end{minipage}\par
220  \vfill
221  \noindent\begin{minipage}[b]{\textwidth}
222  \@lowertitleback
223  \end{minipage}
224  \fi
225  \ifx\@dedication\@empty \else

8Special thanks to Markus Kohm (Markus Kohm@ka2.maus.de) for letting me incorporate this code.

226  \next@tpage\null\vfill
227  {\centering \Large \@dedication \par}
228  \vskip \z@ \@plus3fill
229  \if@twoside \next@tpage \fi
230  \fi
231  \end{titlepage}
232  \setcounter{footnote}{0}%
233  \global\let\thanks\relax
234  \global\let\maketitle\relax
235  \global\let\@thanks\@empty
236  \global\let\@author\@empty
237  \global\let\@date\@empty
238  \global\let\@title\@empty
239  \global\let\@extratitle\@empty
240  \global\let\@titlehead\@empty
241  \global\let\@subject\@empty
242  \global\let\@publishers\@empty
243  \global\let\@uppertitleback\@empty
244  \global\let\@lowertitleback\@empty
245  \global\let\@dedication\@empty
246  \global\let\author\relax
247  \global\let\title\relax
248  \global\let\extratitle\relax
249  \global\let\titlehead\relax
250  \global\let\subject\relax
251  \global\let\publishers\relax
252  \global\let\uppertitleback\relax
253  \global\let\lowertitleback\relax
254  \global\let\dedication\relax
255  \global\let\date\relax
256  \global\let\and\relax}
257 \else
258  \newcommand*\maketitle[1][1]{\par
259  \begingroup
260  \renewcommand\thefootnote{\@fnsymbol\c@footnote}%
261  \def\@makefnmark{\rlap{\@textsuperscript{\normalfont\@thefnmark}}}%
262  \long\def\@makefntext##1{\parindent 1em\noindent
263  \hb@xt@1.8em{%
264  \hss\@textsuperscript{\normalfont\@thefnmark}}##1}%
265  \if@twocolumn
266  \ifnum \col@number=\@ne
267  \@maketitle
268  \else
269  \twocolumn[\@maketitle]%
270  \fi
271  \else
272  \global\@topnum\z@
273  \@maketitle
274  \fi
275  \thispagestyle{plain}\@thanks
276  \endgroup
277  \setcounter{footnote}{0}%
278  \let\thanks\relax
279  \let\maketitle\relax

280  \let\@maketitle\relax
281  \global\let\@thanks\@empty
282  \global\let\@author\@empty
283  \global\let\@date\@empty
284  \global\let\@title\@empty
285  \global\let\@extratitle\@empty
286  \global\let\@titlehead\@empty
287  \global\let\@subject\@empty
288  \global\let\@publishers\@empty
289  \global\let\@uppertitleback\@empty
290  \global\let\@lowertitleback\@empty
291  \global\let\@dedication\@empty
292  \global\let\author\relax
293  \global\let\title\relax
294  \global\let\extratitle\relax
295  \global\let\titlehead\relax
296  \global\let\subject\relax
297  \global\let\publishers\relax
298  \global\let\uppertitleback\relax
299  \global\let\lowertitleback\relax
300  \global\let\dedication\relax
301  \global\let\date\relax
302  \global\let\and\relax}
303 \fi
304 \def\@maketitle{%
305  \let\footnote\thanks
306  \ifx\@extratitle\@empty \else
307  \noindent\@extratitle \next@tpage \if@twoside \null\next@tpage \fi
308  \fi
309  \ifx\@titlehead\@empty \else
310  \noindent\begin{minipage}[t]{\textwidth}
311  \@titlehead
312  \end{minipage}\par
313  \fi
314  \null
315  \vskip 2em%
316  \begin{center}%
317  \ifx\@subject\@empty \else
318  {\Large \@subject \par}
319  \vskip 1.5em
320  \fi
321  {\huge \@title \par}%
322  \vskip 1.5em%
323  {\Large
324  \lineskip .5em%
325  \begin{tabular}[t]{c}%
326  \@author
327  \end{tabular}\par}%
328  \vskip 1em%
329  {\Large \@date \par}%
330  \vskip \z@ \@plus 1em
331  {\Large \@publishers \par}
332  \ifx\@dedication\@empty \else
333  \vskip 2em

334  {\Large \@dedication \par}
335  \fi
336 \end{center}%
337 \par
338 \vskip 2em}%
339 \renewenvironment{titlepage}{%
340  \if@twocolumn
341  \@restonecoltrue\onecolumn
342  \else
343  \@restonecolfalse
344  \fi
345  \thispagestyle{empty}%
346  \if@compatibility
347  \setcounter{page}{0}
348  \fi}%
349  {\if@restonecol\twocolumn \else \newpage \fi}%

350 }% 351 }

This brings us to the end of vrsion. Hope you’ll enjoy it!

Copyright \begin{matrix}c \\ ◯ \end{matrix} 1996-97 by Mats Dahlgren.