Chapter 14. LaTeX Package Documentation Tools

In this chapter we describe the doc system, a method to document LaTeX macros and environments. A large proportion of the LaTeX code available is documented using its conventions and support tools. The underlying principle is that LaTeX code and comments are mixed in the same file and that the documentation or the stripped package file(s) are obtained from the latter in a standard way. In this chapter we explain the structure that these files should have, and show how, together with the program DOCSTRIP, you can build self-installing procedures for distributing your LaTeX package(s) and generating the associated documentation. This chapter will also help you understand the code written by others, install it with ease, and produce the documentation for it (not necessarily in that order).

We end the chapter with a few words about how version control works and how RCS/CVS information can be extracted with LaTeX. Applying version control methods can be useful for any larger documentation project.

Subsequently, authors of LaTeX packages started to realize the importance of documenting their LaTeX code. Many now distribute their LaTeX macros using the framework defined with the doc package (by Frank Mittelbach) and its associated DOCSTRIP utility (originally by Frank Mittelbach with later contributions by Johannes Braams, Denys Duchier, Marcin Woliński, and Mark Wooding). We should mention at this point that there exists an experimental reimplementation with new features and a cleaner and streamlined interface written by Lars Hellström. It is currently distributed as xdoc2, indicating that this is a frozen (and therefore usable) snapshot of work in progress; the final version will be called xdoc.

Both systems allow LaTeX code and documentation to be held in one and the same TeX source file. The obvious advantage is that a sequence of complex TeX instructions becomes easier to understand with the help of comments inside the file. In addition, updates are more straightforward because only a single source file needs to be changed.

The doc package provides a set of commands and establishes some conventions that allow specially prepared sources files to contain both code and its documentation intermixed with each other.

To produce the documentation you need a driver (file) that loads the doc package and then interprets the source file. To produce a ready-to-run version of your code you need to first process the source package with DOCSTRIP (see Section 14.2). This step is usually implicitly done by providing an .ins file that is run through LaTeX.

In its simplest form the driver for the documentation is an external file. However, these days the driver is more commonly made part of the source file, so that all you have to do to produce the documentation is to run the source file through LaTeX. The possibilities are discussed in detail in Section 14.1.4.

The most important commands and concepts are discussed in the next sections. Table 14.1 on page 820 gives an overview of all doc user commands. Further details on any of them can be found in the documented source doc.dtx of the doc package, which can also serve as a prime (though somewhat aged) example of the doc system. You may additionally want to refer to the tutorial “How to Package Your LaTeX Package” by Scott Pakin, which describes various aspects of the doc package and DOCSTRIP. This tutorial is available on CTAN at http://www.ctan.org/tex-archive/info/dtxtut.

Depending on how the code parts are structured it is possible to use such a file directly with LaTeX, although these days this is seldom done. Instead, DOCSTRIP is typically used to produce the production files. If the former approach is taken LaTeX bypasses the documentation parts at high speed and pastes the macro definitions together, even if they are split into several code parts.

On the other hand, if you want to produce the documentation of the macros, then the code parts should be typeset verbatim. This is achieved by surrounding these parts by the macrocode environment.

It is mandatory that you put exactly four spaces between the % character and end{macrocode}. The reason being that when LaTeX is processing the macrocode environment, it is actually looking for that particular string and not for the command end with the argument macrocode.

Inside a code part all TeX commands are allowed. Even the percent sign can be used to suppress unwanted spaces at the ends of lines.

If you prefer, instead of the macrocode environment, you can use the macrocode* environment. It produces the same results except that spaces are displayed as ⊔ characters when the documentation is printed.

The DescribeMacro command takes one argument, which will be shown in the margin and produces a special index entry, for example,

A similar macro, DescribeEnv, can be used to indicate that at this point a LaTeX environment is being explained.

To describe the definition of a new macro, you use the macro environment. It takes one argument: the name of the new macro. This argument is also used to print the name in the margin and to produce an index entry. Actually, the index entries for usage and for definition are different, which allows for easy reference. Here is an example taken from the sources of the doc package itself:

Another environment, with the unimaginative name environment, documents the code of environments. It works like the macro environment but expects the name of an environment as its argument.

When you have to quote a lot of material verbatim, such as command names, it is awkward to always have to type verb+... +. Therefore, the doc package provides an abbreviation mechanism that allows you to pick a character c, which you plan to use only very rarely inside your document, to delimit your verbatim text (the character " is often chosen, but if that character is already used for another purpose, such as for generating umlauts, then you may prefer “|”). Then, after including the command MakeShortVerb{c}, the sequence c textc becomes the equivalent of verbctext c.

The variant form MakeShortVerb* does the same but uses verb*. If you later want to use c with its original meaning, just type DeleteShortVerb {c}. You can repeat this sequence using c as a shorthand for verb and reverting to its original meaning as many times as needed.¹ Note that such short forms for verb, just like verb itself, cannot appear in the argument of another command, but the characters may be used freely inside verbatim and macrocode environments.

¹ This feature has also been made available as a stand-alone package, shortvrb; it was discussed in Section 3.4. See Example 3-4-2 on page 152.

You can divide your documented package file into two parts, the first typically containing a general description and the second giving a detailed description of the implementation of the macros. When generating the document the user will be able to suppress this latter part if you place the command StopEventually at the division point between the two parts.

The StopEventually macro takes one argument in which you put all the information that you want to see printed if the user decides to stop typesetting the document at that point (for example, a bibliography, which is usually printed at the end of the document). When the driver file contains an OnlyDescription declaration, LaTeX will process the argument of StopEventually and then stop reading the file.¹ Otherwise, the StopEventually macro saves its argument in a macro called Finale, which can later be used to get things back (usually at the very end). This scheme makes changes in two places unnecessary.²

¹ The slightly strange command name is due to a misunderstanding by the package author: the German word for “perhaps” is “eventuell” and when he found out it had been in use for years.

² The default is to typeset the whole document. This default can also be explicitly set by using the AlsoImplementation macro.

To document the change history, the changes command can be placed within the description part of the changed code.

The information in the changes command may be used to produce an auxiliary file (LaTeX’s glossary mechanism is used for this purpose), which can be printed after suitable formatting. To cause the change information to be written, include RecordChanges in the driver file. To read and print the sorted change history, put the PrintChanges command at a suitable point, typically after the PrintIndex command in the driver.

To generate the sorted file containing the changes, you should run the raw glossary file through MakeIndex using an adequate style (like gglo.ist, supplied with the doc distribution; see Section 11.1.6 on page 653 for more information about how MakeIndex treats glossaries).

Finer control is provided with the DoNotIndex command, which takes one argument containing a comma-separated list of commands that are not to be entered in the index. More than one DoNotIndex command can be present, and their contents will be combined. A frequent use of this macro is to exclude native LaTeX commands from the index.

Production (or not) of index entries is controlled by using or omitting the following declarations in the driver file preamble (if no declaration is provided, no index is produced). Using PageIndex makes all index entries refer to their page number. With CodelineIndex, index entries produced by DescribeMacro and DescribeEnv refer to the relevant page numbers, but those produced by the macro and macrocode environments refer to the code lines, which are numbered automatically.

If index entries are produced they have to be sorted by an external program, such as MakeIndex (see Chapter 11). The doc package uses special conventions for the index entries, so you need to run MakeIndex with the -s switch (see Section 11.2.4 on page 659) to specify a suitable style—for example, gind.ist, which is distributed with the doc system.

To read and print the sorted index, you must put the PrintIndex command near the end of your driver file, possibly preceded by bibliography commands, as needed for your citations.

The 〈document-class〉 may be any legal class, such as article or ltxdoc (described in Section 14.3); in the latter case the doc package is already loaded by the class. In the 〈preamble〉, you should place declarations that manipulate the behavior of the doc system, such as DisableCrossrefs, OnlyDescription, and CodelineIndex.

Finally, the 〈input-commands〉 part should contain one or more DocInput and/or IndexInput commands. The DocInput command is used for files prepared for the doc system, whereas IndexInput can be used for macro files that do not obey the conventions of the doc system. The latter command takes a file name as its argument and produces a verbatim listing of the file, indexing every command as it goes along. This functionality can be handy if you want to learn something about macros without enough documentation.

It is also possible to use the PrintIndex and PrintChanges (if the changes are recorded by RecordChanges) commands. Some people put them directly into the source file, but it is better practice to place them into the driver. You can then combine several packages in one document and produce a combined index.

As mentioned in the introduction, most often the driver is included directly in the source file instead of being a separate file of its own. How this works is explained in the next section.

Experiences with the doc system soon suggested that it would be a valuable extension to be able to conditionally produce the ready-to-run files—by building them from several source files or extracting them from parts of one or more source files, for example. For this reason the doc system was extended in two directions:

• A syntax was developed to label parts of the code so that the components could be referred to separately.

• The DOCSTRIP program (see Section 14.2), which was originally used only to strip the comments from doc files, was extended to offer a scripting language in which it became possible to specify how a ready-to-run file is generated from labeled code parts of one or more source files.

Of course, a source containing such conditional code can usually no longer be used directly and requires the DOCSTRIP program before it can be turned into a ready-to-run file. However, the additional possibilities offered by this approach outweigh the inconvenience of an extra production step during installation so much that these days nearly all usages of doc take advantage of it.

Code fragments for conditional inclusion are marked in the source file with “tags”. The simplest format is a <*name> and </name> pair surrounding some part of the code. This enables us to include or exclude that part by referring to its name in a DOCSTRIP script. The tags must be placed at the beginning of the line preceded by a %. For example:

It is possible to attach more than one tag to a part by combining several names with the Boolean operators | for logical or, & for logical and, and ! for negation (using lazy evaluation from the left). For example,

means that this block should be included when either Aname is asked for, or Bname is requested but Cname is not.

There are two other forms of directives for including or excluding single lines of code. A line starting with %<+name> will be included (without its tag) if name is requested. A line starting with %<-name> will be included if name is not requested in a DOCSTRIP run.

The above directives can be nested in each other. If this is done the inner tags are evaluated only if the outer tags are true (i.e., if the whole block is requested for inclusion).

Here nothing is included if Aname is not requested. If it is requested, we get code lines 1, 2, and 4 if Bname is also asked for, and lines 1, 3, and 4 otherwise.

You may have wondered how the conditional coding allows us to include the driver in the main source file. For this you have to place the code for the driver as the first code block and surround it by some tag (e.g., driver). If the user now runs the source file through LaTeX, the driver code is the first code that is not behind % signs so it will be executed. Since it ends in end{document}, the LaTeX run will not execute any later code in the file. Thus, the documentation is typeset assuming that the driver loads the whole file using DocInput. To generate the actual package file(s), you use a DOCSTRIP script (see Section 14.2 on page 824) that ignores the driver code by not requesting code from a block tagged driver.

¹ In those days producing a single page with TeX could easily take half a minute or longer.

The problem with any external program developed for such a purpose is that it may or may not be available for the user’s operating system and even if available may not be installed. But one program is always available on a system that can run LaTeX: the TeX program itself. To achieve widest portability, the DOCSTRIP program was therefore written in low-level TeX language. Since those early days the program has undergone many revisions that changed its purpose from being a simple stripping device to serving as a fully customizable installation tool—one that is even able to distribute files to the right directories on a target machine. Johannes Braams, Denys Duchier, Marcin Woliński, Mark Wooding, David Carlisle, and others contributed to this metamorphosis; details of the program’s evolution can be found in the documented source (which uses literate programming, of course). Here are today’s main applications of the DOCSTRIP program:

• Strip a literate programming source of most of its documentation (i.e., the lines that start with a single % sign in the first column).

• Build ready-to-run code files by using code from one or more source files and including parts of it according to options specified.

• Automatically install the produced files in the right directories on the target machine if desired, thereby enormously easing the installation of updates or additions to a LaTeX installation.

The last possibility in particular is not very widely known but deserves the attention of a wider audience as it can be set up with relatively little effort.

LaTeX then asks a few questions about how to process a given file. When the user has answered these questions, DOCSTRIP does its job and strips the comments from the source.

However, this method of processing was intended to do nothing more than stripping off comments. With today’s sources, which contain conditional code and are intended to be combined to form the final “executable”, it is usually no longer appropriate. Instead, the developers of packages typically provide an installation file (by convention having the extension .ins) that is used to invoke DOCSTRIP behind the scenes. In this case the user simply says

This results in the generation of all “executables” from the source distribution and optionally installs them in the right places. All standard LaTeX distributions (e.g., base, graphics, and tools) are distributed in this form and so are most contributed packages that are described in this book.

In the next section we discuss how to construct your own installation scripts for DOCSTRIP. Section 14.2.3 then shows how to set up DOCSTRIP for automatically installing the generated files in the right places.

It starts by loading the DOCSTRIP code using the TeX primitive input (without braces around the file name), which makes it possible to process such a script with TeX formats other than LaTeX. This is followed by the DOCSTRIP commands that actually do the work of building new files, communicating with the user, and carrying out other necessary tasks. At the very end the script contains endbatchfile. Without that statement DOCSTRIP would display a * prompt while waiting for further input from the user.

Within the argument to generate you specify the result-files you want to produce by using file declarations. The second argument to file contains one or more from commands listing the source-files that should be used to build one result-file. With each from declaration the second argument specifies the tag-list to use with the particular source-file. Then only the code pieces tagged with the appropriate tags and all the untagged source pieces from that file are included (see Section 14.1.5 on page 819).

The source-files are used in the order specified: first the code from source-file₁ is included (according to the tag specification), then the code from source-file₂, and so on. The tag-lists in each from command are comma-separated lists and indicate that code with these tags should be included.

With the syntax specification for generate as given above, you can produce a single result-file from one or more source-files by using a single file declaration. By repeating this as often as needed any kind of distribution can be produced. It is, however, not very efficient. Suppose you have one large source file from which you want to produce many small files—for example, suppose the source for the doc package, doc.dtx, is used to generate doc.sty, shortvrb.sty, gind.ist, and gglo.ist. The file is nearly 5000 lines long, so by using four generate declarations, DOCSTRIP would have to process 20000 lines. To speed up this process, generate allows you to specify several file commands within its argument. These files are processed in parallel, meaning that the source-files are opened only once and distribution of source code to result-files is done in parallel.

As you can see, certain other commands (usepostamble, for example) are allowed within the argument of the generate command. In the above example this has the effect of replacing the standard postamble with a different one (since the standard postamble will add an endinput to the end of the generated file, something not desirable in a style file for MakeIndex).

Restrictions on parallel extraction

There are some restrictions with this approach. For instance, DOCSTRIP will complain if the order of source files in one file command conflicts with the order in a different one; the precise rules are discussed in the DOCSTRIP documentation [125]. If that happens, the simplest solution is to use two separate generate declarations.

The Msg command can be used to present a message on the terminal; thus, it offers a similar functionality as LaTeX’s ypeout command. Ask is similar to LaTeX’s ypein command, with the difference that no trailing space is generated from pressing return in reply to a question. This way simple questions can be asked (using a bit of low-level programming). For example:

You may want to give certain information, or run certain code, only if a DOCSTRIP script is executed on its own, but not if it is called as part of a larger installation (see below). Such information or code can be placed in the argument of an ifToplevel command. For example, all the individual installation scripts from the LaTeX base distribution say what to do with the generated files. But if you use the master installation script unpack.ins, the messages in the sub-scripts are suppressed to avoid repeating the same information over and over again.

Before DOCSTRIP writes its output to a file, it checks whether that operation will overwrite some existing version of this file. If so, the default behavior is to ask the user if overwriting is acceptable. This check can explicitly be turned off (or on if it was turned off) by using the command askforoverwritefalse or askforoverwritetrue, respectively, in the DOCSTRIP script.

Setting askforoverwritefalse in a distribution script may not be the right thing to do, as it essentially means that it is okay to overwrite other people’s files, no matter what. However, for large installations, such as the base LaTeX distribution, being asked individually about hundreds of files is not very helpful either. For this reason DOCSTRIP offers the declaration askonceonly. This means that after the first time the script asks the user a question, the user is given an option to have DOCSTRIP assume that all future questions will get a “yes” as the answer. This applies to all future questions (manually produced by Ask or generated through a file overwrite).

For amusement and because in the original implementation everything was so slow, there was a way to direct DOCSTRIP to show its progress when stripping comments and building new files. These days most scripts run in silent mode.

Nevertheless, you do not want to force the user to process a dozen or more installation scripts (30 in case of the LaTeX base distribution). Therefore, DOCSTRIP offers the command atchinput, which enables you to include installation scripts in some master installation script. Do not use input for this purpose, because this command is exclusively reserved for loading the DOCSTRIP code once, as explained above, and is ignored otherwise. Except for the fact that it contains some special handcrafted code at the beginning so that it can be processed using initex, the file unpack.ins from the base LaTeX distribution is a good example for such a master installation script.

The information you want to add to the start of DOCSTRIP’s output file should be listed between the preamble and endpreamble commands. Lines that you want to add at the end should be listed between the postamble and endpostamble commands. Everything that DOCSTRIP finds for both the preamble and postamble is written to the output file, but preceded with two % characters (or, more exactly, with the current definition of the command MetaPrefix). In general, only straight text should be used, and literal command names should be of the form stringfoo. In addition to the user preamble, DOCSTRIP also includes some information about the current file (i.e., its name and the sources from which it was generated). This information is always added unless you use opreamble (see below) or you sidestep the standard preamble generation (explained in the DOCSTRIP package documentation [125]).

It is also possible to define a number of “named” preambles or postambles and later refer to them when generating files. In fact, this is the usual way to produce the preambles in larger projects.

The declarepreamble declaration works like preamble except that it stores the preamble text for later use in cmd. To activate such a preamble, usepreamble is called in a DOCSTRIP script. For postambles, the declarations declarepostamble and usepostamble are provided. Examples of them can be found in all DOCSTRIP installation scripts in the distributions of the standard LaTeX components.

To fully suppress the writing of a preamble or a postamble, you can use the declarations opreamble and opostamble, respectively.

To make it easier to integrate new packages into a TDS-conforming installation or to install package upgrades, the DOCSTRIP program was extended so that under certain circumstances it can be directed to automatically install the generated files in the right places in this structure. For this operation to work, the DOCSTRIP scripts must contain certain directives. In addition, the user has to configure the DOCSTRIP program by providing a docstrip.cfg file suitable for the installation on the current machine.

For the developer of a DOCSTRIP script there is minimal extra work involved: for each generated file its position in the TDS directory tree needs to be known, but this is usually clear for all such files. This place is then specified with usedir as a directory path relative to the TDS root directory in the DOCSTRIP script just before calling the generate command or within the argument to generate before the next file declaration. For most packages, one such usedir declaration is sufficient. For example, the file format.ins in the standard LaTeX distribution states

to place the LaTeX format file (and others) in the correct directory. In more complex bundles, files may need to be distributed to different directories depending on their type. For example, the installation script for the jurabib package states

to generate the files needed by LaTeX in tex/LaTeX/jurabib, the BibTeX styles in bibtex/bst/jurabib, test documents in doc/LaTeX/jurabib, and so on. By itself, the usedir declaration has no effect: DOCSTRIP still generates files only in the current directory.

To allow DOCSTRIP to make use of such usedir declarations, you have to provide it with a configuration file (docstrip.cfg) that contains a declaration for the root directory of your installation and a set of translations to local directories for the paths used in the argument to usedir.

The BaseDirectory declaration specifies the absolute path to the root directory of your TeX installation; other paths are then given relative to this starting directory. In addition, you have to provide for each relative-directory-path used in the argument of usedir a translation to a local directory. For example, to teach DOCSTRIP the directory structure used by the emTeX distribution, you might have a set of declarations like this:

Once DOCSTRIP knows about a BaseDirectory, it will attempt to interpret all usedir declarations in its scripts. If it finds one for which it doesn’t know a translation to a local directory (through DeclareDir), it will complain and generate the file in the current directory instead. You should then add an appropriate declaration to the .cfg file.

Sometimes it is necessary to put some files outside of the base directory, such as when your BibTeX program is on a different disc. In that case use the starred form of DeclareDir, which expects an absolute path name in the second argument. For example:

Since TeX is unable to create new directories, it is a prerequisite that all local directories specified with DeclareDir actually exist. If one of them is not available when you run a DOCSTRIP script, you will receive a TeX error message stating that it cannot write to some file, and asking you to specify a different one.

On a fully TDS-conforming installation, all translations to local directory names are trivial. For example,

directs DOCSTRIP to install into a local TDS tree (i.e., texmf-local) and not into the main installation tree. You have then to make sure that your local tree is searched first.

To ease the configuration work necessary to describe a TDS-conforming installation, DOCSTRIP offers the declaration UseTDS. It directs the program to use the usedir specifications literally if no explicit DeclareDir declaration is specified. Thus, on most installations, a UseTDS and a BaseDirectory declaration in the .cfg file is all that is needed.

Security considerations

By default, DOCSTRIP will generate files only in the current working directory. Even with a configuration file containing a BaseDirectory declaration, it will always write to directories explicitly specified with DeclareDir or, if you use UseTDS, to the appropriate TDS directories below your base directory. It will not overwrite files in other places, though (in these days of viruses and other nasty creatures) you should be aware that TeX, as such, is capable of doing so and therefore might pose some security threat. In fact, some implementations (for example, those on the TeX Live CD) will not let TeX write to files specified with absolute path names or to files starting with a period in their name, unless explicitly authorized. For example, on the author’s system one has to specify

to take advantage of the automatic installation features of DOCSTRIP.

There are two other declarations that you may wish to add to a DOCSTRIP configuration file. On some operating systems there is a limit on the number of files that can be opened by a program. If that is the case you can limit the total number of open files with a maxfiles declaration and the total number of concurrently opened output files with maxoutfiles (TeX itself has a limit of 16). Use these declarations only when necessary.

Changing the comment character

Furthermore, the use of preambles and postambles is likely to conflict with the syntax requirements of the language for which the file is intended. For example, generating a shell script with a number of lines starting with %% is probably not a good idea. This problem can be circumvented by changing the MetaPrefix (which by default produces DoubleperCent). For a shell script, where you probably want a # sign as the comment character, this modification can be a little tricky as TeX regards the # as special. Try

to produce a single hash sign as a MetaPrefix. To return to the default setting, use the following definition:

Verbatim copying

Another potential problem to watch out for is DOCSTRIP’s standard behavior of stripping away all lines starting with a single percent sign. If your code contains such lines you may want to retain them. This can be achieved by surrounding that block with two special lines as follows:

You can use any tag-name. The important point is that this “verbatim” block ends when DOCSTRIP encounters a single line just containing a percent sign followed by tag-name. The other important point to note is that the tag-name is not used for conditional exclusion or inclusion but only for specifying the block to be copied verbatim. If such a block should be written only in some circumstances, as controlled through the second argument of from, you have to additionally surround it by a set of conditional tags (see Section 14.1.5).

A special feature is that the class can be used to produce a single document from a larger number of source files in doc style. This has the advantage that one can produce a full index of macro usage across all source files. For example, the driver file source2e.tex generates the documented source listing of the 40 files that make up the LaTeX kernel. It generates a document with nearly 600 pages including an index and a change history (reaching back to the early 1990s).

The command cmd prints a command name in typewriter font; for example, writing cmd{foo} typesets foo. In contrast to verb+foo+ (which is otherwise similar), it can be used anywhere—even in the arguments of other commands. The command cs offers the same functionality for those who prefer the syntax without the backslash. In fact, it is slightly more powerful because it can also typeset commands that are made outer—a plain TeX concept normally not used in LaTeX. Furthermore, ltxdoc makes “|” an abbreviation for verb so that you can type |foo| in the documentation. If this is not desired for some reason, you have to cancel it in the source (after egin{document}) via DeleteShortVerb{|}.

The commands marg, oarg, and parg produce the LaTeX syntax for mandatory, optional, and picture arguments, respectively. Thus, writing

produces the (probably less-known) syntax diagram for makebox in picture environments: makebox(〈x-dimen,y-dimen〉)[〈pos〉]{〈text〉}.

The DocInclude command is similar to include except that it uses DocInput on file (with the implicit extension .dtx or .fdd) instead of using input on a file (with the implicit extension .tex). This command is used in source2e.tex to “include” all .dtx files that form the LaTeX kernel.

If ltxdoc.cfg is installed in a directory always searched by LaTeX, it is applied to all documentation files using the ltxdoc class. If it is placed in the current directory, it applies only to documents processed in this directory.

The simplest form of customization is to pass one or more options to the article class upon which ltxdoc is based. For instance, if you wish all your documentation to be formatted for A4 paper, add the line

to ltxdoc.cfg and install it in a place searched by LaTeX.

As discussed in Section 14.1.2, the StopEventually command separates the source files into a “user” documentation and an “implementation” part. To be able to produce only the user manual, the doc package provides the command OnlyDescription, which suppresses the implementation part. This command may also be used in the configuration file, but as the doc package is loaded after the configuration file is read, you must delay the execution of OnlyDescription. The simplest way is to use AtBeginDocument:

For example, the documented source of the fixltx2e package, the file fixltx2e.dtx, generates 30 pages of documented code listings if you run

without a configuration file. However, most people are not interested in how certain macros from the LaTeX kernel are patched in this package, but rather which problems are solved when loading it. With the above configuration line the output is reduced to a 10-page user manual, listing only the problems that are solved.

When the driver source2e.tex for the kernel documentation is processed, an index and a change history are produced by default; however, indexes are not normally produced for individual files. If you are really interested in the source listings in detail, you will probably want to have an index as well. Again the index commands provided by the doc package may be used, and again their execution must be delayed. Thus, the addition to the configuration file could look as follows:

Similar lines would be necessary if you want to produce a change history listing. Recall that the doc package generates .idx and .glo files with a special syntax that require adequate style files for processing with MakeIndex (see Section 14.1.3 on page 817).

The Concurrent Versions System (CVS; see http://www.cvshome.org), originally developed as a front end to RCS, extends the notion of revision control from a collection of files in a single directory to a hierarchical collection of directories consisting of revision-controlled files. These directories and files can be combined to form a software release. CVS provides the functions necessary to manage these software releases and to control the concurrent editing of source files among multiple software developers.

RCS and CVS offer a keyword substitution interface in which fields with a certain structure are updated with management information whenever a file is checked into the system. The most important keywords are $Author$ (account of the person doing the check-in), $Date$ (date and time of check-in in UTC), $Id$ (combination field, with file name, revision, date, time, author, state, and optional locked by), $RCSfile$ (archive file without path name), $Revision$ (revision number assigned to the revision), and $Source$ (full path name of archive file). Initially, one simply adds one or more of these keywords (e.g., $Id$) to the source. Upon first check-in, they are replaced by the structure $ 〈keyword〉 : ⊔〈value〉⊔ $, as can be seen in the next example. Later check-ins then update the 〈value〉 as appropriate.

If you put LaTeX documents under source control, you will often want to have access to the data of the RCS fields within your document—perhaps to place the date of the last check-in and the revision number into the running header. Because of the syntax using dollar signs (which indicate formulas in LaTeX), you cannot use the keywords directly in your text, but there exist packages that provide LaTeX tags to give you access to this information in a way suitable for typesetting.

The RCS command parses a dollar-delimited string for a keyword and its corresponding value; it is able to recognize the two variants shown above. From the keyword, it constructs a command name RCSkeyword that can be used to later retrieve the value. The keyword can be any string containing only letters that are usable in a command name; thus, you are not limited to the RCS keyword names mentioned above (though only these keywords are automatically updated by a standard RCS/CVS system). The RCSdef command works like RCS but additionally prints the keyword and value on the terminal.

In the next example we retrieve four typical keys and typeset their values later in the text. As all examples in this book are automatically generated from the book sources (see page 162), the values that you see after the keywords are those corresponding to the file for this chapter.

If you look closely at the previous example, you will notice that RCSDate does not reproduce the value of $Date$ (which is a numeric date format and the time) but instead produces a date string that looks suspiciously like those being produced by oday. This is, in fact, what happens: the value is internally parsed and the check-out date in the format used by oday is stored in RCSDate. In this way language-specific packages (e.g., from the babel system) may supply their own methods of presenting a date.

For keywords whose values are further manipulated, the original value is automatically made available in the command RCSRawkeyword (e.g., RCSRawDate). It is possible to provide your own manipulation routines for other keywords; how this is done is explained in the package documentation (rcs-user.tex).

For convenience, the package defines a couple of additional commands. To parse the $Date$, you can use the command RCSdate (lowercase “d”) instead of the RCS command used above. This is equivalent to writing

The last check-in date is now automatically used as the date in the document title.¹ Of course, the RCSDate command is still available for other uses.

¹ You often see date{ oday} in documents, but this is seldom a good idea because it produces the date of the last formatting run and not the date of the last modification.

Another alternative to RCS is to use the command RCSID for parsing a keyword. Besides setting up the corresponding RCSkeyword command to hold the value, it typesets the keyword and value literally in the running footer. This command can be used at most once (since each invocation overwrites the footer line) and is best combined with the keyword $Id$ or $Header$. As the rcs package more or less bypasses LaTeX’s page style interface, the command does not work if you use pagestyle commands in your source that update the running footer. In that case use RCS and manually place the relevant information in the page style using the methods and packages described in Section 4.4.

The package also contains some code to typeset RCS revision history logs that can be produced with the $Log$ keyword. However, this is most likely of no use to the majority of our readers, as it requires a special RCS version and does not work with CVS. If you are interested consult the package documentation.

If present, the csInfo command parses the value and stores all information obtained in a set of commands for later retrieval. Otherwise, it places default values in the retrieval commands—in case of date information, the current date as known to LaTeX and for all other data strings like --owner--.

The following example shows all commands set up by the package and their respective output. As you can see, the csInfoLongDate depends on the current language. Here we get a date in Italian format.

To influence its behavior the package offers a few options:

today/notoday By default, csinfo changes LaTeX’s internal date information to the check-in information obtained. The oday command will then generate a date string based on this information. If notoday is used, oday will produce a date string showing the date of the LaTeX run.

fancyhdr/nofancy When specifying fancyhdr the rcsinfo package issues a number of fancyhdr declarations to set up a running footer. You still have to provide your own running header definitions and activate everything with pagestyle{fancy}, so it is probably better to keep full control and do the full set-up yourself.

long/short This option works only if the fancyhdr option is used. It then decides whether a long (default) or a short date string is used in the footer line.

For those who want to convert their LaTeX documents to HTML using the LaTeX2html program [56, Chapter 3], rcsinfo offers direct support in the form of a perl file, rcsinfo.perl; this file must be placed in the appropriate directory in the LaTeX2html installation. Refer to the rcsinfo manual for more information.