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

%
% internal interface of the rcs package
%
% [LaTeX]
% (history at end)


% This file is either a subdocument of the style 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 an additional
% revision log.
% Of course, this test works only if LaTeX 2e is used for processing.

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

        \let\endSubDocument=\endinput

        \chap The internal interface.

\else

        \let\endSubDocument=\relax

        \documentclass{progltx}

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

        \nofiles

        \begin{document}

        \title{The \texttt{rcs} Package\\
            {\large (Internal Interface)}%
            }
        \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


You can configure the |rcs| package by redefining control
sequences (cseqs for short). The cseqs which may be redefined form the
\textsl{protected interface}, all of them start with `|Rcs|'. Some cseqs
may be used by you to get information about the state of this module.
These form the \textsl{observer interface}, all cseqs herein start with
`|RCS_|'. Both cseq sets together form the internal interface.

You must not redefine a cseq starting with `|rcs|' or `|RCS|'. In no
case redefine a cseq containing an at~sign or an underscore---all of
them belong to the implementation. Here you have a description of an
internal interface you can rely on, use it (and only it) for
configuration.


\sect \textsl{The protected interface}.

\medskip

\noindent The cseqs of the protected interface fall in two
categories: Configuration of RCS fields and of revision logs.

In general, handlers for RCS fields may be defined, they have the
name |\RcsHandle|\textit{Keyword}. These sequences are responsible for
the filtering of the value of the RCS \textit{Keyword} field. The
unfiltered value itself is provided in the cseq
|\RCSRaw|\textit{Keyword} or in |\RCS_value| (see below).

\smallskip

\noindent The following cseqs my be redefined to configure the |rcs|
package:
%
\begin{quote}
\begin{tabular}{ll}
|\RcsEmptyValue| & used as value for an empty field\\
|\RcsHandleDate| & handler for the \Date{} field\\[1ex]
%
|\RcsLogStyle| & determines general layout of revision log\\
                & must define |\RcsLogHeading|\\
|\RcsLogListStyle| & determines layout of revision log list\\
\itshape |\RcsLogHeading{|text\/|}| & heading of revision log\\
\itshape |\RcsLogDate| date\/|\endDate|
                & typesets date in revision entry intro;\\
                & \textit{date} has the form \textit{yyyy/mm/dd}\\
\itshape |\RcsLogTime{|time\/|}|
                & typesets time in revision entry intro\\
\end{tabular}
\end{quote}


\sect The cseq |\RcsLogListStyle| needs further explanation: The
|rcslog| environment is, in fact, a list environment.
|\RcsLogListStyle| will be used as the second argument of |\list|, it
must define |\makelabel| and setup all list layout parameters.

Even though |rcslog| is implemented via |list|, I don't regard it as
such. For example, I think it should not increase the list level: an
item list in a revision entries should use the first-level item
labels. This is realized by placing the |rcslog| environment on list
level~0. It follows that |\endlist| must not be used for |\endrcslog|,
|\endtrivlist| is used instead. If you redefine |\RcsLogListStyle| in
such a way that this special list level setting is not done any more,
you \emph{must} redefine |\endrcslog| as well. You were warned.

Of course, if you just want to change some paragraph layout values,
it's better to append your definitions to the end of
|\RcsLogListStyle|.


\sect The following macros must be looked at for internationalization:
%
\begin{quote}
\begin{tabular}{ll}
|\RcsLogHeadingName| & log heading text, in front of filename\\
|\RcsUnknownFile| & used for unknown filename\\
|\RcsEmptyLog| & no revision entries are available\\
\itshape |\RcsLogRevision{|rev\/|}{|date\/|}{|time\/|}{|uid\/|}|%
        \hidewidth\null \\
                & introduces a revision entry, must be an |\item|\\
\end{tabular}
\end{quote}



\sect \textsl{The observer interface}.

\medskip

\noindent The following cseqs provide you with information you might
utilize in your configuration.
%
\begin{quote}
\begin{tabular}{ll}
|\rcs@loaded| & the module's RCS revision field\\
              & (This name does not follow the name conventions\\
              & for internal reasons.)\\[1ex]
|\RCS_keyword| & keyword of the last parsed RCS field\\
|\RCS_value| & value of the last parsed RCS field\\
\itshape |\RCS_get_author{|uid\/|}| & gets \textit{uid}'s author name\\
\end{tabular}
\end{quote}



\endSubDocument


\vskip \PltxPreSectSkip

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

\Revision 2.5 1995/08/01 22:54:09 schrod
Updated to \LaTeXe{}; |\RcsLoadHook| is not necessary any more as that
functionality is provided by \LaTeX{} now.

Spell checked.

\Revision 2.4 1993/11/08 20:15:12 schrod
Added possibility to configure the layout of the log list
(|\RcsLogListStyle|).

Now the log list is on level~0. Thereby item lists or enumerations in
revision entries get first-level labels. This has consequences for
the configuration, this implementation strategy must therefore be
specified in the internal interface description.

\Revision 2.3 1993/11/03 20:04:05 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.

\Revision 2.2 1993/11/02 18:43:03 schrod
|\RcsLoaded| must not be redefined, belongs therefore to the observer
interface. I don't write it as |\RCS_loaded| though---it must be
usable outside of style files.

Don't need auxiliary files.

\Revision 2.1 1993/11/01 19:49:21 schrod
    Added sub-document that describes the internal interface.

\end{rcslog}


\end{document}

% LocalWords:  rcs yyyy mm dd rcslog rev uid