summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/rcs/src/rcs-conf.tex
blob: a743678574aa9513bcda12422091d2c81525cf6a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
% $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