summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rcs/src/rcs.doc
blob: 9712d9c256accca1f35203659d9e26e12d353b80 (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
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
% $StyleId: rcs.doc,v 2.10 2003/02/02 20:42:38 schrod Exp $
%----------------------------------------------------------------------
% Written by Joachim Schrod <jschrod@acm.org>.
% Copyright conditions see below.

%
% LaTeX package rcs
% to use RCS tag values in one's document, and typeset revision logs
%
% [LaTeX in MAKEPROG]
% (history at end)

% If you have received this style file without the user manual (in the
% file rcs-user.tex or the respective DVI file), it's incomplete and
% near to useless. If it was given to you as something that you shall
% use as an author -- complain bitterly to your provider. You need the
% documentation and you have a right on it! (Below you can find info
% where to get the reference version.)



\documentclass{progltx}

\usepackage{rcs-doc}
\usepackage{path}
\usepackage{alltt}
\usepackage{fullpage}


\RCS $StyleDate: 2003/02/02 20:42:38 $


\begin{document}


\title{The \texttt{rcs} Package\\
    {\large (Implementation)}%
    }
\author{%                       % LaTeX does not discard unnecessary glue...
    Joachim Schrod%
    \thanks{%
        \protect\raggedright
        R\"odermark, Germany.
        Email: \texttt{jschrod@acm.org}%
        }%
    }
\date{%
    Revision \RCSStyleRevision\\
    (as of \RCSStyleDate)%
    }

\maketitle



% ------------------------------------------------------------
%
% subdocument: The user interface of rcs.sty
%

\input{rcs-user}

%
% ------------------------------------------------------------
%
% subdocument: The internal interface
%

\input{rcs-conf}

%
% ------------------------------------------------------------



\chap Implementation.

This module reserves the namespace |rcs|.

\beginprog
\ifx \rcs@loaded\undefined
    \def\rcs@loaded{$StyleRevision: 2.10 $}
\else
    \PackageWarningNoLine{rcs}%
	{Some other package already uses namespace `rcs'}
\fi
\endprog


\sect Let's identify this package.

Now I'm caught in a catch-22 situation. The code below---part of my
standard templates for \LaTeX{} packages---uses principles that are
explained later in this document. In particular, the explanation how
the information from the following RCS fields are gathered starts at
chunk~\ref{chunk:value-split}.

There you'll find also the explanation for the funny strings behind
the RCS fields. Actually, I would not need them any more, they make
the initial document (before the first check-in) work. But they won't
be discarded in this package source, as they'll demonstrate another
utilization of RCS at work.

\beginprog
\begingroup
    \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{%
	\def\date{#4}\def\id{v#7}%
	\ProvidesPackage{#1}[\date\space\id\space #2]%
	}

  \RCSPackage{rcs}{typeset info from RCS fields}
  $StyleDate: 2003/02/02 20:42:38 $: 9999/00/00 \endRCS
  $StyleRevision: 2.10 $: 0.0 \endRCS
\endgroup
\endprog


\sect This module is supported. Send bug reports, comments, and
repairs.

The reference version may be retrieved via anonymous ftp from CTAN,
directory \path|/tex-archive/macros/latex/contrib/supported/rcs|.


\sect This is freely distributable software; you can redistribute it
and/or modify it under the terms of the GNU General Public License
(version~2) as published by the Free Software Foundation.

This software is distributed in the hope that it will be useful, but
\textbf{without any warranty}; without even the implied warranty of
\textbf{merchantability} or \textbf{fitness for a particular purpose}.
See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License in
the file |License| along with this package; if not, write to the Free
Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA.


\sect Before we start we declare some shorthands for category codes.
By declaring the underscore~`(|_|)' as letter we can use it in our
macros. (I agree with {\sc D.~Knuth} that
|\identifier_several_words_long| is more readable than
|\IdentifierSeveralWordsLong| and in every case better than
|\p@@@s|.) As this is a \LaTeX{} style option the at sign is a letter
anyhow; so we can use the ``private'' Plain and \LaTeX{} macros; and
with the underscore we can make our own macros more readable.  But as
we have to restore this category code at the end of this macro file
we store its former value in the control sequence |\CatUsCode|. This
method is better than to use a group because not all macros have to
be defined global this way.

\beginprog
\ifx \CatEscape\undefined
    \chardef\CatEscape=0
    \chardef\CatOpen=1
    \chardef\CatClose=2
    \chardef\CatIgnore=9
    \chardef\CatLetter=11
    \chardef\CatOther=12
    \chardef\CatActive=13

    \chardef\CatUsCode=\catcode`\_
\fi

\catcode`\_=\CatLetter                  % top level macro file
\endprog




\chap Parsing RCS fields.

Each RCS field consists of a keyword and an optional value. The value
is delimited by `\verb*|: |' from the keyword, this delimiter is
missing if no value does exist. At the end of a value there's always
a space. I.e., the possible input looks like one of the two following
lines:
 %
\begin{quote}
  \itshape
  |\RCS $|Keyword\/|$|\\
  |\RCS $|Keyword\/\verb*|: |value\/\verb*| $|
\end{quote}
 %
where \textit{Keyword} and \textit{value} may be arbitrary strings. In
fact, we assume that \textit{Keyword} is a sequence of letters---only
then the creation of a cseq |\RCS|\textit{Keyword} is sensible. Our
implementation will not produce an error with an obscure keyword, but
the result will not be of use for the author.
We must not depend on a fixed set of keywords, this style shall be
usable with a configurable RCS version. In such a version one can
bind arbitrary keywords to the information available in RCS\@. This
means we will parse all RCS fields with the same macro,
|\rcs_split_field|. This macro will place its results in two macros:
|\RCS_keyword| and |\RCS_value|. Afterwards we can bind the expansion
of |\RCS_value| to the target cseq.


\sect |\RCS_value| will be set to the expansion of |\RcsEmptyValue|
if there was no RCS value available, i.e., if the field was not
processed by RCS yet. This way the values of non-expanded RCS fields
can be configured. The default value is the empty token list.

\beginprog
\def\RcsEmptyValue{}
\endprog


\sect For those fields where a special handling is demanded, a cseq
|\RcsHandle|\textit{Keyword} must exist. This cseq must handle the
parsing of the value. Usually this means that it will create a macro
named |\RCS|\textit{Keyword} with a transformed (or filtered) value.
If you happen to write a handler you might want to look at the
definition of |\RcsHandleDate| starting at section~\ref{sec:date}
If a special handler for a field exists, the original value is
placed automatically in the macro |\RCSRaw|\textit{Keyword}. This is done
before the handler is called.


\sect \label{chunk:value-split} The macro
|\rcs_split_field| will split the field into |\RCS_keyword| and
|\RCS_value|. This split is done by the argument parsing capability
of \TeX{}: We can separate parameters by token lists and \TeX{} will
use a shortest pattern match to determine the arguments.

Let's look what kind of pattern we can use. As an example we use the
RCS field `\verb*|$Revision: 2.11 $|', i.e., the unexpanded field is
`|$Revision: 2.11 $|'. The macro |\RCS| will use dollars to delimit its
argument, we don't need to worry for them. Eventually we'll have to
discard the space of the expanded field's value---after all,
|\RCSRevision| shall expand to `1.1', not to `1.1~'.

First, we can see that the token list $\it (colon, space)$ may be used
as the seperator of keyword and value:
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\(: \)1.1 \]\\end_value}
\end{quote}
%
($d_i$ is the separating token list between parameter $i$ and~$i+1$.
|#1| denotes the argument of |\RCS|. |\end_value| is a stop token,
used to delimit the last parameter; we have to supply this token at
the call. In fact, all tokens marked by $s$ and the dotted
line---i.e., those after |#1|---are supplied by us.)

When we want this token list as a separator, we have to supply it for
the unexpanded field, since there is no $\it (colon, space)$ in there:
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\]\(: \)\\end_value}
\end{quote}
%
Then the call with the expanded field gets
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\(: \)1.1 \]: \\end_value}
\end{quote}

Well, we want neither the space nor the colon and the other space
after the value---we have to get rid of them. We can utilize the fact
that no RCS field will ever have the token list $\it (space, colon)$
in it. This means we can use it as a terminator for the RCS value:
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\(: \)1.1\( \]:\) \\end_value}
\end{quote}
%
Please note, one token of the delimiter~$d_2$ comes from the
|#1|~argument, the other from the tokens we'll add at the call.

Let's check our unexpanded field again---we don't have $d_2$ there. We
have to add it by the caller:
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\]\(: \)\{\}\( :\)\\end_value}
\end{quote}
%
(Without the empty group the two spaces would be combined into one
token.) Going back to the expanded field, we notice that these
additional tokens do not harm us---we'll ignore everything after $d_2$
anyhow.
%
\begin{quote}
  \macroCall{\\rcs_split_field \[Revision\(: \)1.1\( \]:\) \{\} :\\end_value}
\end{quote}

We can take another look at the whole affair and point out the
parameters we get for the split. Remember, that spaces after a control
word belong to this word. First, the expanded field:
%
\begin{quote}
  \macroCall
      [p]{\\rcs_split_field \[\(Revision\): \(1.1\) \]:\( \{\} :\)\\end_value}
\end{quote}
%
Then the unexpanded one:
%
\begin{quote}
  \macroCall[p]{\\rcs_split_field \[\(Revision\)\]: \(\{\}\) :\(\|\)\\end_value}
\end{quote}
%
($p_3$, the third parameter will be empty in this case.)

\medskip

\noindent As explained above: if the value does not exist, a default
value is supplied.

\beginprog
\def\rcs_split_field #1: #2 :#3\end_value{%
    \def\RCS_keyword{#1}%
    \def\RCS_value{#2}%
    \ifx \RCS_value\empty
	\let\RCS_value\RcsEmptyValue
    \fi
    }
\endprog


\sect |\RCS| triggers the split. After it has occured, we can bind the
expansion of |\RCS_value| to a new name. This name is constructed from
the prefix |RCS|, the string |Raw| iff a handle for this field exists,
and the keyword itself.

Afterwards we call the handle, on non-existance this will be a no-op.

Gathering the field is a bit more complicated, as we need to pay
attention to underscores in file names.

\beginprog
\def\RCS{%
    \bgroup
        \catcode`\_ \CatActive
	\RCS_get_argument
    }
\def\RCS_get_argument $#1${%
        \gdef\RCS_argument{#1}%
    \egroup
    \RCS_process
    }

\def\RCS_process{%
    \expandafter\rcs_split_field \RCS_argument: {} :\end_value
    \expandafter\let \csname RCS\rcs_raw_if_handle\RCS_keyword\endcsname
		     \RCS_value
    \csname RcsHandle\RCS_keyword\endcsname
    }
\def\rcs_raw_if_handle{%
    \@ifundefined{RcsHandle\RCS_keyword}{}{Raw}%
    }
\endprog




\chap Transforming the value of \Date{} fields.
\label{sec:date}

When we implement the special handling for the \Date{} field, we take
care that we don't rely on the fact that the keyword is |Date|.
Certain RCS versions (one of them created at our site) allow the
configuration of the used keywords. I.e., there might be another
keyword used for this field, but we still want to use the
functionality provided here.
For example, let's assume the keyword of the \Date{} field is
|StyleDate|. Then the assignment
%
\begin{quote}
  |\let\RcsHandleStyleDate=\RcsHandleDate|
\end{quote}
%
is all that's needed to turn on the `date special handling' for this
field. (In fact, that's done in this style file you're reading.)


\sect The special handler for \Date{} fields sets up
|\RCS|\textit{Keyword} (|\RCSDate| usually) to produce a textual
representation of the date part of the \Date{} value in a
|\today|-like format. Thus the constructed tag can be used in many
circumstances, e.g., as the argument of the |\date| tag on the
titlepage.

In addition, |\RCSTime| is defined; it expands to the checkin time.

If the value is empty, i.e., if there's no \Date{} value from RCS
available, we use the current date. Later we might supply the current
time, too---currently |\RCSTime| expands to an empty token list in
such a case.
Of course, this whole special handling is only done if |\today| is
defined in some way; otherwise we just handle the \Date{} field like
every other RCS field: The value is stored unfiltered in
|\RCS|\textit{Keyword}.

\beginprog
\def\RcsHandleDate{%
    \ifx \today\undefined
	\expandafter\let \csname RCS\RCS_keyword\endcsname \RCS_value
    \else
	\ifx \RCS_value\RcsEmptyValue
	    \@namedef{RCS\RCS_keyword}{\today}%
	    \let\RCSTime\empty
	\else
	    \expandafter\rcs_set_date \RCS_value\end_date
	\fi
    \fi
    }
\endprog


\sect If the value is not empty we split it using the argument parsing
mechanism of \TeX{}. Then we'll define the value using the current
definition of |\today|. This way language-specific styles (e.g., from
the \textsf{babel} system) may supply their own way to present a date.

\beginprog
\def\rcs_set_date #1/#2/#3 #4\end_date{%
    \begingroup
	\day #3			% <-- space!
	\month #2		% <-- space!
	\year #1		% <-- space!
	\expandafter\xdef \csname RCS\RCS_keyword\endcsname {\today}%
    \endgroup
    \def\RCSTime{#4}%
    }
\endprog




\chap Typesetting revision logs.

If a revision log is to be typeset, we demand a special format.
Namely, it is to be enclosed in the |rcslog| environment. This
environment has an optional parameter, the configuration tokens. The
contents of the environment is the \Log{} field followed by a list of
revision entries. The \Log{} field must be on a line of its own. Each
revision entry is introduced by a line consisting of the tag
|\Revision|, the revision number, the checkin date, the checkin time,
and the author's user id.

I.e., the input looks like the following example sketch, where italic
material is substituted by current values.
%
\begin{quote}
  \chardef\\=`\\                        % just for the example
  \chardef\{=`\{
  \chardef\}=`\}
  \begin{alltt}\frenchspacing
\\begin\{rcslog\}
$Log: rcs.doc,v $
Revision 2.11  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.)

\\Revision {\it revision date time uid}
\qquad {\it log text\/}

\quad \([\,\ldots\) {\it perhaps more entries\/} \(\ldots\,]\)

\\end\{rcslog\}
  \end{alltt}
\end{quote}

We typeset the revision log similar to a |description| environment.
Each revision entry is an item.


\sect The tag for the log intro is implemented as a token register. In
fact, |\rcsLogIntro| is a hook.

\beginprog
\newtoks\rcsLogIntro
	\rcsLogIntro={}
\endprog


\sect The author names are stored in a table named |rcs_author|. We
supply the lookup macro |\RCS_get_author|, which expands to the table
value or to the table key itself.

\beginprog
\def\rcsAuthor#1#2{\@namedef{rcs_author:#1}{#2}}
\def\RCS_get_author#1{%
    \@ifundefined{rcs_author:#1}{#1}{\@nameuse{rcs_author:#1}}%
    }
\endprog


\sect Since this style option shall be usable with many styles, we
must provide means to configure its behaviour. In particular, it must
be possible to configure the layout. What remains fixed, is the layout
of the log like a |description| list. I might add this flexibility if
there is enough interest (or if somebody sends me tested changes).

The first thing to parametrize is the overall layout and the header.
This is set up by |\RcsLogStyle|. This cseq \emph{must} define
|\RcsLogHeading|, which is the macro to set the header. E.g., here
one could insert a |\newpage| to start a new page for the revision log.

In addition, we reduce the base size of the log. That's the reason why
these two configurations are combined in one macro---if you change
one, you also have to consider to change the other.

\beginprog
\def\RcsLogStyle{%
    \def\RcsLogHeading{\subsubsection*}%
    \footnotesize
    }
\endprog


\sect The header itself is created by |\rcs_log_hdr|, which is called
with the expanded \Log{} value as its argument, terminated by
|\end_value|.  We use \TeX{}'s parameter parsing mechanism to chop off
the tail of the value---if the value exists, it always ends in~`|,v|'.
Since only an existing value ends in~`|,v|', we have to supply a
fitting empty value. We will use |\rcs_empty_log_value| for that.

The empty log value gets a bit more complicated: If we have an empty
\Log{} value, we will not have any revision entries. (Well, except in
pathological cases.  Then we will produce spurious text.) Missing
revision entries are missing items; since \LaTeX{} will complain
about a missing |\item|, we must provide one to stop it from doing
so. But here is no place for such tokens, the list environment hasn't
started yet. We will set the flag |@rcs_empty_log@| and check this
flag after we invoked the list.

\beginprog
\def\rcs_log_hdr#1,v\end_value{%
    \@rcs_empty_log@false
    \RcsLogHeading{\RcsLogHeadingName #1}%
    \the\rcsLogIntro
    }
\def\rcs_empty_log_value{%
    \global\@rcs_empty_log@true		% that's most probably in a group!
    \RcsUnknownFile			% text for unknown file name
    ,v%					% assert calling env
    }
\newif\if@rcs_empty_log@
\endprog


\sect The user might want to adapt the text output. He can do so by
redefining |\RcsLogHeadingName|, |\RcsUnknownFile|, and |\RcsEmptyLog|.

\beginprog
\def\RcsLogHeadingName{Revision Log for \ttfamily} % file name in monospace
\def\RcsUnknownFile{\rmfamily\mdseries $\langle\,$Unknown file name$\,\rangle$}
\def\RcsEmptyLog{{\itshape No log entries available.}}
\endprog


\sect OK, we have fixed the header, let's address the entries. Each
entry is typeset by |\RcsLogRevision| which is called with four
arguments: (1)~the revision number, (2)~the checkin date, (3)~the
checkin time, and (4)~the uid of the author.

Such an entry is inserted as an item in the list. The uid is
transformed to an author name, if the respective information is
available. The checkin timestamp is mapped to a neater appearance by
|\RcsLogDate| and |\RcsLogTime|.

\beginprog
\def\RcsLogRevision#1#2#3#4{%
    \item [Revision #1]%
      (created at \RcsLogDate #2\endDate\space \RcsLogTime{#3} % <-- space!
      by \RCS_get_author{#4})\\\relax
    }
\endprog


\sect |\RcsLogDate| sets the date. We can use \TeX{}'s parameter parsing
mechanism to separate the date value (passed as the argument) in its
sub-values.  The code is very similar to |\rcs_set_date|.

|\RcsLogTime| sets the time. As explained in the user manual, the time
is ignored usually. (I don't think that this info is relevant in a
printout.) Here we assume something about the context it's expanded
in: Spaces will be before and after the tag. One of them must be
discarded. The user option |\settime| is implemented here as a
private macro, too.

\beginprog
\def\RcsLogDate #1/#2/#3\endDate{%
    \begingroup
	\day #3			% <-- space!
	\month #2		% <-- space!
	\year #1		% <-- space!
	\today
    \endgroup
    }

\def\RcsLogTime#1{\ignorespaces}
\def\rcs_settime{%
    \def\RcsLogTime##1{[##1]}%
    }
\endprog


\sect Well, that are all possibilities to configure the revision log.
Let's put together the pieces. Within the |rcslog| environment the
tags |\Revision| and |\settime| are used, they are implemented in
the |rcs| namespace.

At the start, we use the optional argument of the environment to
configure it. |\settime| might be placed here, or font switches, etc.

The next entity shall be the \Log{} field.  In fact, it shall be on
the next line. If an optional environment argument was there, the
newline is still in the input and must be discarded before we can use
|\RCS| to parse the field.

\beginprog
\def\rcslog{%
    \@ifnextchar[%			% ] (Emacs)
	\rcslog_configure
	{\rcslog_configure[]}%
    }
\def\rcslog_configure[#1]{%
    \let\Revision\rcslog_revision
    \let\settime\rcs_settime
    \RcsLogStyle
    #1%
    \afterassignment\rcslog_skipcr
    \let\next
    }
\endprog


\sect There are users---programmer's life would be so nice without
them. An empty line (i.e., a |\par|) might have been inserted between
|\begin{rcslog}| and the \Log{} field. There might be even other
garbage between them. We have to check these possibilities and provide
proper responses.

\beginprog
\def\rcslog_skipcr{%
    \ifx \next $%
	\def\next{\rcslog_field $}%
    \else\ifx \next\par
	\let\next\rcslog_field
    \else
	\PackageError{rcs}{Missing RCS Log field in environment}{%
The RCS Log field must be the very first text in the rcslog\MessageBreak
environment. I will discard the rest of your input line and try to\MessageBreak
recover then. If you think this won't work, exit now.\MessageBreak
Otherwise press <Return> and cross your fingers!}
	\let\next\rcslog_discard_line
    \fi\fi
    \next
    }
\endprog


\sect This is the code for the luser. He provided tokens we didn't
wait for---we discard them and check anew if we've got it right now.
(Remember, we're waiting for the `|$|' of the \Log{} field.) %$ Emacs

\beginprog
\def\rcslog_discard_line{%
    \begingroup
	\obeylines
	\rcslog_gobble_line
    }
\begingroup
\obeylines
\gdef\rcslog_gobble_line #1^^M{%
    \endgroup%
    \afterassignment\rcslog_skipcr%
    \let\next%
    }
\endgroup
\endprog


\sect Yep, we've reached a dollar; let's hope that it's our \Log{}
field. It must be on one line, this line is fetched first and then
analyzed.

\beginprog
\def\rcslog_field{%
    \begingroup
	\obeylines
	\catcode`\_ \CatActive
	\rcslog_get_field
    }

\begingroup
\obeylines
\gdef\rcslog_get_field $#1$^^M{%
        \gdef\RCS_argument{#1}%
    \endgroup%
    \rcslog_set_field%
    }
\endgroup
\endprog


\sect When we analyze the \Log{} field, we must supply the default
value. Within the log list there will be no other RCS fields,
therefore we can redefine |\RcsEmptyValue| in this environment.

The header gets passed the expanded \Log{} value, as explained above.
We use |\RCS_value| instead of |\RCSLog| since we don't know which
RCS keyword is used.

At last, we start the list and check the |@rcs_empty_log@| flag,
perhaps we have to supply a dummy |\item|.

\beginprog
\def\rcslog_set_field{%
    \let\RcsEmptyValue\rcs_empty_log_value
    \RCS_process
    \expandafter\rcs_log_hdr \RCS_value\end_value
    \list{}\RcsLogListStyle		% empty label, layout configurable
    \if@rcs_empty_log@
	\item []\RcsEmptyLog		% supply missing item
    \fi
    }
\endprog


\sect The setup of the log list is done by a macro from the protected
interface, the user shall be able to change it. In the default
supplied, there is no skip between paragraphs, but a quad indentation.
|rcslog| is here no list environment in the sense like |itemize| or
|enumerate|, therefore a usage of these environments within an entry
shall result in top-level item markers.

\textbf{Caveat}:\quad Since we globally set |\@listdepth| at the start
of the environment, we must not execute |\endlist| that decrements it.
Instead we use |\endtrivlist| for the termination of the |rcslog|
environment. It might be, that this must be changed if
|\RcsLogListStyle| is changed.

\beginprog
\def\RcsLogListStyle{%
    \global\@listdepth\z@
    \labelwidth\z@		    % item label w/o fixed size
    \itemindent -\leftmargin	    % move label before start of line
    \advance\itemindent \labelsep   % label was moved too much
    \def\makelabel##1{\bf ##1}%	    % how to typeset labels
    \parsep\z@skip		    % no space between pars in items
    \listparindent 1em		    % <-- space!  indent pars in items
    }%

\let\endrcslog\endtrivlist
\endprog


\sect The arguments of |\Revision| are separated by spaces and
terminated by the end of the line. We have to fetch them, then we can
pass them to |\RcsLogRevision| which does the real work.

\beginprog
\def\rcslog_revision{%
    \begingroup
	\obeylines
	\rcslog_get_revinfo
    }

\begingroup
\obeylines
\gdef\rcslog_get_revinfo #1 #2 #3 #4^^M{%
    \endgroup%
    \RcsLogRevision{#1}{#2}{#3}{#4}%
    }
\endgroup
\endprog




\chap Convenience tags.

As a shortcut we
support the direct supply of the checkin date for the titlepage
material. Here we also take care not to depend on the keyword.

\beginprog
\def\RCSdate $#1${%
    \RCS $#1$%
    \expandafter\date \expandafter{\csname RCS\RCS_keyword\endcsname}%
    }
\endprog


\sect |\RCSID| parses the RCS field and redefines the footline. This
tag is from Nelson's |rcs| style. In his style he defines that the RCS
field is passed as an argument to the macro. To be upward compatible,
we have to support this as well: We look at the next token, if it is
an opening brace we fetch the param and trigger the `real' invocation
by |\rcs_id|. If no brace follows, we call |\rcs_id| immediately.

\beginprog
\def\RCSID{%
    \@ifnextchar\bgroup
	\rcsid_get_field
	\rcs_id
    }
\def\rcsid_get_field#1{\rcs_id #1}
\endprog


\sect As a side effect, we'll produce the normal value tags. When we
define the footline, we must assert that |\RCS_keyword| and
|\RCS_value| are expanded. (They will get new bindings at the next
invocation of |\RCS|.) All other macros must not be expanded, they
shall be used in the context of the footline, not in our definition
context. We utilize |\protect| for that, |\framebox| is the only macro
that must be protected.

\beginprog
\def\rcs_id $#1${%
    \RCS $#1$%
    \begingroup
	\let\protect\noexpand
	\xdef\@oddfoot{%
	    \reset@font
	    \protect\framebox[\textwidth]{\RCS_keyword: \RCS_value}%
	    }%
    \endgroup
    \global\let\@evenfoot\@oddfoot
    }
\endprog


\sect |\RCSdef| just outputs its parameter before it's passed to
|\RCS|. This tag is from Tom Verhoeff's |rcs| style. In fact, we're
not fully compatible: Tom did output `RCS keyword string'. I
substitute this by `RCS field', this is consistent with the rest of
this style's description.

\beginprog
\def\RCSdef $#1${%
    \typeout{RCS field: $#1$}%
    \RCS $#1$%
    }
\endprog




\chap The end.

Well, after all we're finished with this style. We must not forget to
restore the underscore catcode.

\beginprog
\catcode`\_=\CatUsCode

\endinput
\endprog


\sect I would like to thank those who helped me to improve this style.
% In particular, XXX provided XXXsubstantial parts of the code.

\textsc{Marcus Speh} pointed out that Nelson's style option exists.
\textsc{Lee Wittenberg} pointed out that Tom style option exists---Tom
posted the style option on |comp.programming.literate| afterwards. I
borrowed the idea of appending a second colon to the call of
|\rcs_split_field| from Tom's style. \textsc{Harald Fuchs} asked for the
possibility to configure the log list layout.

\textsc{Dave Love} brought the problem with the |-kv| option of |co| to
my attention. It's a pitty that I haven't found a solution yet. (I
mean, one that convinces me.)

\textsc{Christine Detig} told me where my documentation was
uncomprehensible. In particular, you won't have the visual explanation
of |\rcs_split_field| without her. barbara beeton proofread the user
manual. In addition, she pointed out where a non-programmer does not
understand it.

After 7.5 years of quiteness, \textsc{Martin Kneißl} emerged and asked
for support of underscores in file names. He got it, and I used the
opportunity to update contact information.



\vskip \PltxPreSectSkip

\rcsLogIntro{Of course, we shouldn't stop without the RCS log of this
    style file.}


\begin{rcslog}
$StyleLog: rcs.doc,v $
\Revision 2.10 2003/02/02 20:42:38 schrod
Support underscores in file names in RCS field values. E.g., in
\rcsField{Id} or \Log{}.

Update my contact information.

\Revision 2.9 1995/08/02 12:09:07 schrod
Transformed this style option into a \LaTeXe{} package.

Updated to \LaTeXe{}.

\Revision 2.8 1993/11/10 12:29:49 schrod
Added acknowledgement of barbara.

\Revision 2.7 1993/11/08 20:15:15 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.6 1993/11/03 20:04:57 schrod
Cleaned up for distribution: Added email address to each document,
added copyright info to |rcs.doc|, added acknowledgements. Checked my
English and the spacing.

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

Rewrote the explanation to |\rcs_split_field|. Added the visual clues
to explain the (mis?)usage of macro expansion and pattern matching.

\Revision 2.5 1993/11/02 20:02:51 schrod
Implemented |\RCSdef|.

Deleted unnecessary macro that did discard the space of an RCS value.
Moved this in the parameter context of |\rcs_split_field|. Added an
explanation to |\RCS| where it is called.

\Revision 2.4 1993/11/02 18:44:49 schrod
Implemented |\RCSID|.\\
Need |\reset@font| now, for the definition of the footline in |\RCSID|.

Paragraphs in revision logs are not separated by vertical space any
more. They are indented instead. I use the ``classic'' indentation of
one quad.

\Revision 2.3 1993/11/01 19:49:49 schrod
Added subdocument about the internal interface.

Cleaned the cseq names: All public names start with `|RCS|' or
`|rcs|', protected names start with `|Rcs|', both have only letters.
Observer names start with `|RCS|', internal names with `|rcs|', both
feature non-letters in the names.

\Revision 2.2 1993/11/01 19:20:58 schrod
Cleaned up the documentation. The enhancement of the |rcslog|
environment was just appended, now it's integrated in the whole
document. Improved the explanation of the implementation: the valid
input is now explained more clearly.

Use |rcs-doc.sty| for documentation of |rcs| style. It does not only
load style options, but does also define |\RCSStyleRevision| for
access of the style's revision.

Added hint that the user manual is urgently needed.\\
 The load tag is now in the protected interface.\\
 Commented out section with definition of |\reset@font|, that cseq is
not needed in the implementation.\\
 OALD tells me to use ``heading'' instead of ``header.''

\Revision 2.1 1993/10/29 19:07:38 schrod
Reorganized the source structure---the style gets too large to keep
everything in one directory. I use the usual setup for my larger
styles.

Changed the RCS keywords. All keywords in use now start with
`|Style|'. Stuff in the text which looks like RCS fields, but where
the keywords do not start with `|Style|', are examples!

\Revision 1.3 1993/10/29 18:08:19 schrod
Each field value supplied by RCS ends with a space; this space is
discarded.

Supports the typesetting of revision logs. The overall documentation
is not yet fully integrated. Of course, our own revision log is
typeset at the end, too.\\
 But we'll have to use other RCS keywords for this document in the
future. E.g., I can't use original RCS keywords currently in the
examples without much hassle.

An hook for the configuration of this style option is provided.

\Revision 1.2  1993/09/08  15:49:00  schrod
Use canonical names for category codes.

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

\end{rcslog}




\end{document}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Local Variables:
mode: LaTeX
TeX-brace-indent-level: 4
indent-tabs-mode: t
TeX-auto-untabify: nil
TeX-auto-regexp-list: LaTeX-auto-regexp-list
End: