L^{A}TEX Macro for version Numbering of Files

Mats Dahlgren

                       (matsd@physchem.kth.se)

1995/05/31

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-95 by Mats Dahlgren. All rights reserved.

NOTICE!

This package was called version in the first release. The name has been changed to minimize the risk of confusion with the L^{A}TEX 2.09 package version by Stephen Bellantoni. My sincere apologizes to him and the L^{A}TEX community. The command names have not been changed.

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.)

1.1 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 has been tested with L^{A}TEX 2ε of 1994/12/01 patch level 3 running TEX 3.1415 under OpenVMS. Please send bug reports (see below), corrections, additions, suggestions,

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

1.2 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. With vrsion version 1.2 this problem is eliminated. (Thanks to Peter Ryder (ryder@theo.physik.uni-bremen.de) for bringing my attention to this problem.) Also, the command \version has been made robust.

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 1994/12/01 (or newer).

2.2 Usage

The package is included by stating

  \usepackage[option]{vrsion}

in the document preamble. It can take any of the options one, ten, and hundred. To produce

\version a version number anywhere in your document you issue the command \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). When changing from one option 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 \stepcounter 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…

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.

3 Known Problems

• 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.

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@physchem.kth.se.

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

5 The Code

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

First, the package should identify itself:

\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\ProvidesPackage{vrsion}%
[1995/05/31 version numbering of LaTeX files (v. 1.2).]
\typeout{The `vrsion' package included.  (c) 1994-95 by Mats Dahlgren.}

Next, the options are declared. The declaration of option one is a bit superfluous, but supplied for symmetry reasons. All it does is telling the user she/he is using the default option.

\DeclareOption{one}{%
\typeout{Option `one' is default for `vrsion'.}
}

The ten option modifies the \version command to produce a decimal number and steps the integer version number if the decimal part reaches 10. 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”).

  \DeclareOption{ten}{%
    \DeclareRobustCommand{\version}{%
      \ifKeepversion \else
        \stepcounter{versionnrten}%
        \ifnum\theversionnrten=10\stepcounter{versionnr} \fi
        \@skrivner
      \fi
      \theversionnr .\theversionnrten
    }
  }

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

  \DeclareOption{hundred}{%
    \DeclareRobustCommand{\version}{%
      \ifKeepversion \else
        \stepcounter{versionnrhundred}%
        \ifnum\theversionnrhundred=10\stepcounter{versionnrten} \fi
        \ifnum\theversionnrten=10\stepcounter{versionnr} \fi
        \@skrivner
      \fi
      \theversionnr .\theversionnrten\theversionnrhundred
    }
  }

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

  \DeclareOption*{\typeout{The option `\CurrentOption '\space
    is not used by `vrsion'.}\OptionNotUsed}

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

  \newcounter{versionnr}
  \newcounter{versionnrten}[versionnr]
  \newcounter{versionnrhundred}[versionnrten]
  \@addtoreset{versionnrhundred}{versionnr}
  \newif\ifKeepversion \Keepversionfalse
  \newcommand{\keepversion}{\global\Keepversiontrue}
  \newcommand{\stepversion}{\global\Keepversionfalse}

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^{3} 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.

  \def\vrsFile{\jobname.vrs}
  \newwrite\@vrs
  \newcounter{VrsNr}

3This was nessecary to make vrsion compatible with babel.

\def\@skrivner{%
\setcounter{VrsNr}{\@partaux}%
\addtocounter{VrsNr}{1}%
\let\@vrs=\theVrsNr%
\immediate\openout\@vrs\vrsFile%
\immediate\write\@vrs{\relax}%
\immediate\write\@vrs{%
  \string\vrslabel{versionsnummer}{{\theversionnr}{\thepage}}}%
\immediate\write\@vrs{%
  \string\vrslabel{versionsnummertio}{{\theversionnrten}{\thepage}}}%
\immediate\write\@vrs{%
  \string\vrslabel{versionsnummerhundra}{{\theversionnrhundred}{\thepage}}}%
\immediate\closeout\@vrs{}%
}

Here comes the default version of the \version macro:

\DeclareRobustCommand{\version}{%
\ifKeepversion \else
  \stepcounter{versionnr}%
  \@skrivner
\fi
\theversionnr
}

To be able to smoothly read the .vrs-file and set the counters to zero the first time, a special ‘\input’ macro is built. This is then called on at the beginning of the document in the \AtBeginDocument command. Before that, the babel incompatibility is fixed by defining special \label and \ref commands, which always are the original L^{A}TEX commands.

\@ifundefined{LTX@ref}{\let\vrsref=\ref}{\let\vrsref=\LTX@ref}
\@ifundefined{LTX@newlabel}{\let\vrslabel=\newlabel}%
{\let\vrslabel=\LTX@newlabel}
\def\@inp@t#1{\openin1 #1 \ifeof1
  \typeout  {No file #1.}
  \setcounter{versionnr}{\z@}
  \setcounter{versionnrten}{\z@}
  \setcounter{versionnrhundred}{\z@}
\else\closein1 \relax\@@input #1
  \setcounter{versionnr}{\vrsref{versionsnummer}}
  \setcounter{versionnrten}{\vrsref{versionsnummertio}}
  \setcounter{versionnrhundred}{\vrsref{versionsnummerhundra}}
\fi
}
\AtBeginDocument{%
\@inp@t{\vrsFile}
}

And, finally, lets adjust the \version command according to the specified option.

\ProcessOptions