% $DocId: rcs-user.tex,v 1.9 1995/08/02 12:08:41 schrod Exp $
%------------------------------------------------------------

%
% user manual/requirement definition for rcs package
%
% [LaTeX]
% (history somewhere inmidst, search for RCS DocLog field)


% This file is either a subdocument of the package or a document on
% its own. In the former case it's a chapter, in the latter it's a
% ``normal'' LaTeX progltx document.
%     If it's a subdocument, this file will be included after
% \begin{document}. We can detect this: \document redefines
% \documentclass to be \@twoclasseserror. Then we also have to define
% how this document is ended: Either by \endinput or by \end{document}.
% Of course, this test works only if LaTeX 2e is used for processing.

\expandafter\ifx \csname @twoclasseserror\endcsname \documentclass

        \let\endDocument\endinput

        \chap What's this package for?.

\else

        \def\endDocument{\end{document}}

        \documentclass{progltx}

        \usepackage{rcs-doc}            % addition document-specific markup
        \usepackage{a4-9}               % Tschichold's A4 layout

        \nofiles

        \begin{document}

        \title{The \texttt{rcs} Package}
        \author{Joachim Schrod%
                \thanks{Email: \texttt{jschrod@acm.org}}%
                }

        \RCS $DocDate: 1995/08/02 12:08:41 $
        \date{%
            \RCSDocDate\\[3pt] % LaTeX Error: Paragraph terminated too early
            (Revision \RCSStyleRevision{} of \texttt{rcs.sty})%
            }

        \maketitle

        \sect

\fi


An important problem in program development and maintenance is version
control, i.e., the task of keeping a software system consisting of
many versions and configurations well organized.  The \textsl{Revision
Control System} (RCS) is a software tool that assists with that
task.  RCS manages revisions of text documents, in particular source
programs, documentation, and test data.  It automates storing,
retrieval, logging and identification of revisions, and it provides
selection mechanisms for composing configurations. In addition, it is
able to insert management information in the text document, in
so-called \textsl{RCS fields}.

The \textsl{Concurrent Versions System} (CVS) is a front end to RCS
which 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.


\sect If you put \LaTeX{} documents under RCS control, you'll often want to
have access to the data of the RCS fields within your document, e.g.,
to put the date of the last checkin, the revision number, or the
author's name in your document. This package provides \TeX{}
tags that give you access to this information. In addition, using a
configurable RCS, you can typeset your revision logs.


\sect There is one restriction: If you checked out with the |-kv|
option, you cannot \LaTeX{} your document any more. You'll get an
error then. If you're a CVS user, the same holds for the `|cvs export|'
command. (Actually, this is equivalent to `|co -kv|'.) This
would discard the dollars and all keywords from the RCS fields; the
tags explained below need the keywords to work properly.

If you have any idea how a tag might look which circumvents this
problem, contact me. (I'm not asking for an implementation, I'm asking for an
idea for a user interface!) E.g., are you hit by this problem, and are
you willing to enter an additional argument with the keyword for each
RCS field?

\medskip

This package assumes the file naming possibilities of Unix. It does not
work without changes on systems with a restricted file name syntax,
like MS-DOS, VMS, etc. In particular, it assumes that RCS uses~`|,v|'
as the suffix for its files, as it's the default.


\sect Let's first consider the access to the values of RCS
fields. By writing
%
\begin{quote}
  |\RCS $|\textit{Keyword}|$|
\end{quote}
%
in your document, a tag
%
\begin{quote}
  |\RCS|\textit{Keyword}
\end{quote}
%
is created which expands to the value of the field with this
respective keyword. E.g., if you write |\RCS $Revision: 1.10 $| and you
check in your document, RCS will transform this to something like
|\RCS $Revision: 1.10 $| and you can access the revision of your
document as |\RCSRevision|. This will expand to~`1.1' (note that the
trailing space was discarded).

Of course, an RCS field has a value only if you have checked in your
file at least once after you inserted it. If the field is brand new,
the constructed \TeX{} tag expands to nothing.%
  \footnote{Well, not quite exactly---this can be changed. Refer to
    the documentation of the style's internal (programmer's) interface.}


\sect The \Date{} field is handled in a slightly different manner: Here
|\RCSDate| doesn't expand to the original RCS value, it's transformed
first. The expansion is the checkin date in a |\today|-like format.
The checkin time is available via |\RCSTime| then.

If the \Date{} value is empty, |\RCSDate| will expand to the
current date and |\RCSTime| will expand to nothing.

The ``original'' \Date{} value is stored in |\RCSRawDate|. This whole
transformation is done only if the tag |\today| is defined (which is
the case for all standard classes).



\sect \textsl{Tags for your convenience}.

\medskip

\noindent |\RCS| puts information from RCS fields into \TeX{} tags.
Some usages of such values are wanted more often than others: placing
the checkin date on the title page, and placing the field keyword and
value in a footline. This was made available in other |rcs| style options;
we use the tag names from there for the sake of compatibility.


\sect The tag |\RCSdate| (with a lowercase~`d') is a convenient
way to put the last checkin date on the title page. It's used instead
of |\date| and expects an RCS \Date{} field afterwards; i.e., to be
input as
%
\begin{quote}
  |\RCSdate $Date: 2003/02/02 22:30:22 $|
\end{quote}
%
Afterwards |\maketitle| will use the checkin date.

In fact, the \Date{} value is still placed in |\RCSDate| (with an
uppercase~`D') and this tag is used as the argument for |\date|.
I.e., this is identical to writing
%
\begin{quote}
  |\RCS $Date: 2003/02/02 22:30:22 $|\\
  |\date{\RCSDate}|
\end{quote}


\sect The tag |\RCSID| places the keyword and the value of the RCS
field in a box into the footline. The RCS field is expected after the
tag. The value is not transformed---you'll see it exactly as RCS
inserted it. Aside from this, |\RCSID| has the same effect as |\RCS|:
The field value is stored in |\RCS|\textit{Keyword}.

\textbf{Note:}\quad If you use this tag, you cannot use any other page
style or package that sets the footline! The RCS field value must not
be a file name with underscores, you get \TeX{} errors otherwise.


\sect The tag |\RCSdef| is like |\RCS|, but it additionally outputs
the RCS field to the terminal. (As with everything output to the
terminal, it will be in the |LOG| file, too.) The RCS field value must
not be a file name with underscores, you get \TeX{} errors otherwise.



\sect \textsl{Typesetting revision logs}.

\medskip

\noindent RCS creates a revision log (sometimes also called change
log, version history, etc.)\ in the lines below a \Log{} field. When
one's \LaTeX{} document is really a program (e.g., if one uses a
system of the WEB family like \texttt{CWEB} or noweb, or if one
uses a documentation system \`a la MAKEPROG), one might want to
incorporate such a log in the typeset document. This is strongly
encouraged for every literate program---the version history is an
integral part of a program's documentation.

This package provides an environment |rcslog| which supports the
typesetting of logs. But you cannot use it with a normal RCS version.
You need to be able to configure the format of a revision entry. We
have created such a configurable version, you can retrieve it by
anonymous ftp from
\path|ftp.tu-darmstadt.de:pub/programming/management/confrcs|. (We
welcome comments and bug reports.)

Since version 1.10, CVS has its own internal RCS implementation,
therefore you cannot typeset revision logs with CVS, sorry. Please
contact me if you find a way nevertheless.


\sect You must create an RCS configuration file |.rcsrc| where a
backslash is prepended to the revision entries. I.e., it must contain
the following configuration line:
 %
\begin{quote}
  |log_entry "\\Revision %r %d %t %a\n%l\n"|
\end{quote}
 %
This line changes the format of revision entries for \emph{every}
file in your directory. If you want to have this special entry format
only for specific files, you can put a guard in front of this
configuration: the filename and a colon. You can also use wildcards
in the filename. For example, to change the entry format for all
files with the suffix |doc| use
 %
\begin{quote}
  |*.doc: log_entry "\\Revision %r %d %t %a\n%l\n"|
\end{quote}
 %
The configurable RCS gives you more possibilities, refer to its
documentation.


\sect The |rcslog| environment needs the \Log{} field as the first
line, there must be no material either before or behind it. If you
just create a new document, you simply input the three lines
 %
\begin{quote}
  \begin{verbatim}
\begin{rcslog}
$Log: rcs-user.tex,v $
Revision 1.10  2003/02/02 22:30:22  schrod
Removed dependeny on \LaTeX2.09 font selection commands. (Though
they're still used in the package documentation, as convenience.)

\end{rcslog}
  \end{verbatim}
\end{quote}
 %
(Note that the configurable RCS will now set the comment leader to the
empty string, which is exactly the value we need.)

If you have checked in your document already once and if you don't
have a revision log by now, you still insert the three lines listed
above. Then you have to set the comment leader to the empty string.
If you don't have a WIMP interface to RCS, you do this with the
command `|rcs -c |\textit{filename}'.
%With CVS, you use the command
%`|cvs admin -c |\textit{filename}'.

If you have checked in your document already and if you already have a
revision log, you insert the environment start
(|\begin{rcslog}|) in a new line before the \Log{} field and
|\end{rcslog}| below the entries. Usually all lines from the revision
log will be prefixed with a comment, delete this prefix from each
line. Each revision entry starts with `|Revision|', change this to
`|\Revision|'. Check that your log texts are valid \LaTeX{} input.
Set the comment leader to the empty string (this is described in the
previous paragraph). Voil\`a, you're finished---welcome to the
community of Literate Programmers!


\sect And since the description of this functionality might have been
a bit dry, I want to show you the output you get usually: I insert
here the log of this user manual. In fact, it was created by the
method described in the previous paragraph---the capability of
typesetting revision logs was not available from the very start.

\begin{rcslog}
$DocLog: rcs-user.tex,v $
\Revision 1.9 1995/08/02 12:08:41 schrod
Transformed this style option into a \LaTeXe{} package.

\Revision 1.8 1995/08/01 21:02:14 schrod
Adapted to \LaTeXe{}. Spell checked.

\Revision 1.7 1993/11/10 12:26:56 schrod
barbara proofread the user manual. Besides her minor changes she
asked what RCS and CVS are, and if this can be used somewhere else
than on Unix. I added appropriate paragraphs to explain the tools.
Actually, the package may be used only on Unix, due to the dependency
on the `|,v|' filename suffix.

\Revision 1.6 1993/11/03 20:04:23 schrod
Cleaned up for distribution: Added email address to each document,
added copyright info to |rcs.doc|, added acknowledgments. Checked my
English and the spacing.

Explained the restriction concerning the |-kv| option of |co|.

\Revision 1.5 1993/11/02 20:02:29 schrod
Introduced new tag |\RCSdef|. This is done to be upward compatible with
Tom Verhoeff's |rcs| style option.

\Revision 1.4 1993/11/02 18:43:19 schrod
Introduced new tag |\RCSID|. This is done to be upward compatible with
Nelson's |rcs| style option.

\Revision 1.3 1993/11/01 19:54:08 schrod
Added a description of the internal interface, I can refer now to
that description. (Previously, I refered to the style's documentation.)

Don't create auxiliary files, we don't need them.

\Revision 1.2 1993/11/01 19:21:22 schrod
Explained the new feature of typesetting logs. This includes the user
manual's log as an example.

Improved the documentation. Told first what happens, then the
exceptions. Used ``pseudo section headings'' to give visual clues for
the structure.

Added the style's revision number to the title page.\\
 Used |rcs-doc.sty| for documentation of |rcs| style. It not only
loads style options, but it also defines |\RCSStyleRevision| for
access of the style's revision.

Prefixed keywords of RCS fields with `|Doc|'. This way we can use the
normal keywords in examples and don't have to care about
non-expansion.

\Revision 1.1  1993/09/03  21:01:28  schrod
Re-implemented |rcs| style option. Made it a documented option.

\end{rcslog}


\sect Nearly every detail of the formatting of the log is done by
macros that can be changed, refer to the documentation of the style's
internal interface for more information.

In particular, the |rcslog| environment accepts an optional argument,
the configuration. Here \LaTeX{} code is expected, which is inserted
after the initial setup, before the heading is set. E.g., this is the
place for you to change the type size. (Although this should be done
with care---you'll also have to change the heading to get a consistent
layout.)

In addition, the tag |\settime| may be used in this optional argument
to add the checkin time to all revision entries. (Longtime RCS users
will have noticed already that it was omitted.) This tag---as well
as |\Revision|---is not defined outside the environment.


\sect Longtime RCS users will have noticed another fine point in the
log presented above: My full name was presented, not my user id
(actually, `|schrod|'). This was done by placing the tag
 %
\begin{quote}
  |\rcsAuthor{schrod}{Joachim Schrod}|
\end{quote}
 %
somewhere before the log. Of course, if no full name has been
presented for a user id, the user id itself is used as the author's
name.


\sect As explained above, one can configure the layout with an
optional argument of the environment. (Or by redefining macros from
the style writer's interface in another style option.) What's wanted
sometimes are some introductionary words to the log; this can't be
done easily this way. (Remember, the heading is not typeset yet.)
Therefore, we provide a tag for this obvious need.

The introductionary text can be specified as the parameter of the tag
|\rcsLogIntro|. It will be inserted after the heading, before the
\Log{} list.



\sect \textsl{Compatibility issues}.

\medskip

\noindent This package is user interface compatible to \textsc{Piet van
Oostrum}'s |rcs| style option. The internal interface of Piet's style
option is not supported; check the documentation of this package's
internal interface for its own internal configuration possibilities.

This package is user interface compatible to \textsc{Nelson Beebe}'s |rcs|
style option. But it does not set the footline unconditionally.

This package is user interface compatible to \textsc{Tom Verhoeff}'s |rcs|
style option. (Well, the text output by |\RCSdef| is not identical.)

And, of course, it's upward compatible to previous revisions\,\dots



\endDocument

% LocalWords:  checkin kv cvs co rcslog confrcs rcsrc doc rcs admin Voil Piet
% LocalWords:  proofread Verhoeff's Nelson's Oostrum Piet's Verhoeff
