# TeX Macros

This page describes various TeX macros for use with the LaTeX format. The packages can be found in the directory http://home.htp-tel.de/lottermose2/tex/dist; for each file, there exists also an OpenPGP signature (filename suffix .sign). See the comments in a file for documentation on the macros provided by that file.

While the usual convention is to distribute such packages as a pair of *.ins/*.dtx or *.drv/*.doc files, I prefer to offer only one file which can be used directly. Most of the packages, however, also support extracting documentation in printable format with the doc package and processing with docstrip; the initial comments in such files will tell you how to do that. (Effectively, these are *.doc files containing comments describing the *.drv file and how to run docstrip.)

## Digsig: Digital Signature Fields in PDF Files

Portable Document Format (PDF) files may contain signature fields which can be filled in with a digital signature. Signature fields are a special case of PDF form fields.

Although LaTeX's standard hyperref package does contain support for PDF form fields, it does not support signature fields. The package digsig removes this restriction.

Note that this package merely enables you to generate signature fields. It does not provide the software necessary for creating a signature, but Adobe's free Acrobat Reader supports that for general PDF files since version 11.0.7 (May 2014).

## Docversion: Identifying the Version of a Document

Readers of a document often need information which uniquely identifies a particular state (version) of the document as a whole. This may be an edition number, a version number, or just the date when the document was issued. In case of frequently edited documents and when the TeX source files are held in a version control (VC) system, it prevents errors if this information can be deduced from data automatically inserted by the VC system. Although writing TeX macros for such purposes is usually straightforward, the resulting solutions are also mostly VC-system-specific. For people who use several VC systems in parallel (I have at present to work with five), this can be very annoying, particularly when moving files between these systems or when constructing a document from files stored in different systems.

The package docversion defines VC-system-independent interfaces for describing the version of a document and for collecting this information from VC-system-specific macros called for each file using docversion. In particular, the package finds the latest modification time across all such files, even if expressed in different time zones, and also determines whether at least one file is currently in a state between identifiable versions.

You need a supplementary macro package for each VC system you wish to use; as an example, there is an extension available here for the Revision Control System (RCS); it also works for compatible systems like the Concurrent Versions System (CVS). A document generated from a single TeX source file held in any of these systems could use the package as follows:

  ...
\usepackage[RCS]{docversion}
\setfileinfoRCS{$Id: ...$}
...
\setdocversiontimezone{+0000}
\date{\documentdate\ (version \documentversion)}
...
\begin{document}
...


Appropriate values for \documentdate and \documentversion will then be extracted from the argument given to \setfileinfoRCS; after checkin, the value for \documentdate will in this case be expressed in Coordinated Universal Time (UTC, time zone +0000), independent of the time zone chosen for RCS, and \documentversion will resolve to the RCS revision number. In case the file is moved to another VC system, only the \usepackage option and the \setfileinfo... line need to be modified.

## Sourceid: Recording Source File Information in the Output File

When encountering a document generated by TeX, it is sometimes useful to be able to extract from that output file identifying data about the files from which the document was constructed. This information is primarily useful to the author and not particularly interesting to readers of the document, hence such data should not appear in the printed representation. (This functionality is similar to #pragma ident or #ident directives in C or C++ code.)

The sourceid package provides an interface for collecting such data. As I am not aware of a general solution for storing this information in any kind of TeX output file, writing the collected data to a file is done by calling a macro which can be redefined by the user. The default definition implements non-trivial functionality only if the document is processed with pdfTeX.

Although it is not essential, best results will be obtained if you intend to extract the data from the output file with the standard UNIX what command (part of the suite of programs for the Source Code Control System (SCCS)).

If sourceid is used together with docversion, the \setfileinfo... calls of the latter will automatically generate what-conforming calls to sourceid.

Back to this website's entry point