The GNU Revision Control System is generally considered a tool for software development, but it is also useful for tracking revisions of text documents. This article explains how to include and format RCS keywords in LaTeX documents, and how to track document revisions using these keywords.
Most discussions of the GNU Revision Control System occur in the context of tracking source code revisions. But RCS can track revisions of any type of file, text or binary, provided that the diff utilities which generate RCS change files can handle binary data.
RCS seems ready-made for working with LaTeX input files. The pre-defined keyword identifiers built in to RCS are easy to format and print. They provide ready information that can include the document's author, its revision, filename, and, revision log entry. RCS also provides facilities for user-defined identifiers.
RCS is commonly included with the development software of Linux distributions. The latest source code version of RCS is available from ftp://prep.ai.mit.edu/pub/gnu and its mirror sites.
The ident(1) manual page has a list of the standard RCS keywords that are generated when documents are checked out by RCS. They include:
* $Author: lg $: The login name of the person who checked in the revision.
* $Date: 2002/10/09 22:24:18 $: The date and time the document was checked in.
* $RCSfile: latex.html,v $ The basename and extension of the RCS file.
* $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $: String containing the name of the RCS file, the revision number, date and time, author, state, and locker if any.
* $Revision: 1.2 $: The document's revision number.
* $Log: latex.html,v $
* Revision 1.2 2002/10/09 22:24:18 lg
* Remove all lg_toc##.html; change hyperlinks to index.html
*
* Revision 1.1.1.1 2002/08/14 22:27:03 dan
* Preliminary.
*
* Revision 1.1.1.1 1997/09/14 15:01:51 schwarz
* Imported files
* The log message entered when the document was checked in.
These keywords are included verbatim in documents. They are expanded when the document is checked out with co(1).
One consideration that needs to be taken into account is that the keywords' dollar signs are interpreted by LaTeX (and TeX) as starting and ending math-mode typesetting. LaTeX and TeX will not generate an error when it encounters the dollar signs. However, because LaTeX and TeX typeset equations differently than normal text, the results can be unpredictable.
For example, including the $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $ string at the top of the odd pages the commands
\pagestyle{myheadings}
\markright{$Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $}
results in the expanded RCS $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $ string to be printed at the top of the pages, but some of the keywords run together because of the way TeX formats the string. An alternative is to use the keywords of the individual identifiers, and separating them with the appropriate command. Here, the TeX command \hfil inserts the necessary space when the keyword strings are typeset in the running head.
\pagestyle{myheadings}
\markright{$Date: 2002/10/09 22:24:18 $\hfil$RCSfile: latex.html,v $\hfil$Revision: 1.2 $}
The string given to the \markright command will be typeset with the date in the upper left of the page, the filename centered, and the revision number at the top right.
The \markright command is all that's needed for printing on one side of a sheet. For printing on both sides of the page, use the \markboth command.
\pagestyle{myheadings}
\markboth{$Date: 2002/10/09 22:24:18 $\hfil$RCSfile: latex.html,v $\hfil$Revision: 1.2 $}{\thepage}
The first argument to \markboth prints the RCS information at the tops of the left-hand pages and the page number at the top of the right-hand pages. The identifier \thepage is a standard LaTeX variable which prints the page number.
The RCS log message can be placed anywhere in a document that the $Log: latex.html,v $ Revision 1.2 2002/10/09 22:24:18 lg Remove all lg_toc##.html; change hyperlinks to index.html Revision 1.1.1.1 2002/08/14 22:27:03 dan Preliminary. Revision 1.1.1.1 1997/09/14 15:01:51 schwarz Imported files keyword can be inserted. For example, to place a (short!) log message in the margin at the beginning of a document, put the command \marginpar{$Log: latex.html,v $ \marginpar{Revision 1.2 2002/10/09 22:24:18 lg \marginpar{Remove all lg_toc##.html; change hyperlinks to index.html \marginpar{ \marginpar{Revision 1.1.1.1 2002/08/14 22:27:03 dan \marginpar{Preliminary. \marginpar{ \marginpar{Revision 1.1.1.1 1997/09/14 15:01:51 schwarz \marginpar{Imported files \marginpar{} immediately after the \begin{document} command, or after the \maketile command if the document has a title page and you'd rather have the RCS log text annotating the body text of the document.
The RCS information can be included in the documents footer by using the fancyhdr package, which is available from any TeX archive site.
If you want to include the $Date: 2002/10/09 22:24:18 $ and $Revision: 1.2 $ keywords at the bottom of a page, you could include
\usepackage{fancyhdr}
\fancypagestyle{rcsfooters}{%
\fancyhf{}
\fancyhead[C]{thepage}
\fancyfoot[L]{$Date: 2002/10/09 22:24:18 $}
\fancyfoot[R]{$Revision: 1.2 $}
in the document preamble; that is, before the \begin{document} command. At the point you want the RCS data to be typeset, insert the commands
\thispagestyle{rcsfooters}
\pagestyle{rcsfooters}
ident(1) also searches files for RCS keywords. Typing the command ident term-paper.tex for example, will print a list of the keywords and their values to standard output. It's a simple matter of typing ident *tex | grep "fred" - to search for the documents which were last checked out by user fred.
For further information, consult the manual pages of the various programs in the RCS package, and the rcsintro(1) manual page for an introduction to the RCS system.
Most discussions of the GNU Revision Control System occur in the context of tracking source code revisions. But RCS can track revisions of any type of file, text or binary, provided that the diff utilities which generate RCS change files can handle binary data.
RCS seems ready-made for working with LaTeX input files. The pre-defined keyword identifiers built in to RCS are easy to format and print. They provide ready information that can include the document's author, its revision, filename, and, revision log entry. RCS also provides facilities for user-defined identifiers.
RCS is commonly included with the development software of Linux distributions. The latest source code version of RCS is available from ftp://prep.ai.mit.edu/pub/gnu and its mirror sites.
The ident(1) manual page has a list of the standard RCS keywords that are generated when documents are checked out by RCS. They include:
* $Author: lg $: The login name of the person who checked in the revision.
* $Date: 2002/10/09 22:24:18 $: The date and time the document was checked in.
* $RCSfile: latex.html,v $ The basename and extension of the RCS file.
* $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $: String containing the name of the RCS file, the revision number, date and time, author, state, and locker if any.
* $Revision: 1.2 $: The document's revision number.
* $Log: latex.html,v $
* Revision 1.2 2002/10/09 22:24:18 lg
* Remove all lg_toc##.html; change hyperlinks to index.html
*
* Revision 1.1.1.1 2002/08/14 22:27:03 dan
* Preliminary.
*
* Revision 1.1.1.1 1997/09/14 15:01:51 schwarz
* Imported files
* The log message entered when the document was checked in.
These keywords are included verbatim in documents. They are expanded when the document is checked out with co(1).
One consideration that needs to be taken into account is that the keywords' dollar signs are interpreted by LaTeX (and TeX) as starting and ending math-mode typesetting. LaTeX and TeX will not generate an error when it encounters the dollar signs. However, because LaTeX and TeX typeset equations differently than normal text, the results can be unpredictable.
For example, including the $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $ string at the top of the odd pages the commands
\pagestyle{myheadings}
\markright{$Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $}
results in the expanded RCS $Id: latex.html,v 1.2 2002/10/09 22:24:18 lg Exp $ string to be printed at the top of the pages, but some of the keywords run together because of the way TeX formats the string. An alternative is to use the keywords of the individual identifiers, and separating them with the appropriate command. Here, the TeX command \hfil inserts the necessary space when the keyword strings are typeset in the running head.
\pagestyle{myheadings}
\markright{$Date: 2002/10/09 22:24:18 $\hfil$RCSfile: latex.html,v $\hfil$Revision: 1.2 $}
The string given to the \markright command will be typeset with the date in the upper left of the page, the filename centered, and the revision number at the top right.
The \markright command is all that's needed for printing on one side of a sheet. For printing on both sides of the page, use the \markboth command.
\pagestyle{myheadings}
\markboth{$Date: 2002/10/09 22:24:18 $\hfil$RCSfile: latex.html,v $\hfil$Revision: 1.2 $}{\thepage}
The first argument to \markboth prints the RCS information at the tops of the left-hand pages and the page number at the top of the right-hand pages. The identifier \thepage is a standard LaTeX variable which prints the page number.
The RCS log message can be placed anywhere in a document that the $Log: latex.html,v $ Revision 1.2 2002/10/09 22:24:18 lg Remove all lg_toc##.html; change hyperlinks to index.html Revision 1.1.1.1 2002/08/14 22:27:03 dan Preliminary. Revision 1.1.1.1 1997/09/14 15:01:51 schwarz Imported files keyword can be inserted. For example, to place a (short!) log message in the margin at the beginning of a document, put the command \marginpar{$Log: latex.html,v $ \marginpar{Revision 1.2 2002/10/09 22:24:18 lg \marginpar{Remove all lg_toc##.html; change hyperlinks to index.html \marginpar{ \marginpar{Revision 1.1.1.1 2002/08/14 22:27:03 dan \marginpar{Preliminary. \marginpar{ \marginpar{Revision 1.1.1.1 1997/09/14 15:01:51 schwarz \marginpar{Imported files \marginpar{} immediately after the \begin{document} command, or after the \maketile command if the document has a title page and you'd rather have the RCS log text annotating the body text of the document.
The RCS information can be included in the documents footer by using the fancyhdr package, which is available from any TeX archive site.
If you want to include the $Date: 2002/10/09 22:24:18 $ and $Revision: 1.2 $ keywords at the bottom of a page, you could include
\usepackage{fancyhdr}
\fancypagestyle{rcsfooters}{%
\fancyhf{}
\fancyhead[C]{thepage}
\fancyfoot[L]{$Date: 2002/10/09 22:24:18 $}
\fancyfoot[R]{$Revision: 1.2 $}
in the document preamble; that is, before the \begin{document} command. At the point you want the RCS data to be typeset, insert the commands
\thispagestyle{rcsfooters}
\pagestyle{rcsfooters}
ident(1) also searches files for RCS keywords. Typing the command ident term-paper.tex for example, will print a list of the keywords and their values to standard output. It's a simple matter of typing ident *tex | grep "fred" - to search for the documents which were last checked out by user fred.
For further information, consult the manual pages of the various programs in the RCS package, and the rcsintro(1) manual page for an introduction to the RCS system.
Powered by ScribeFire.
No comments:
Post a Comment