diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex/rcs')
| -rw-r--r-- | Master/texmf-dist/tex/latex/rcs/rcs.sty | 1024 |
1 files changed, 1024 insertions, 0 deletions
diff --git a/Master/texmf-dist/tex/latex/rcs/rcs.sty b/Master/texmf-dist/tex/latex/rcs/rcs.sty new file mode 100644 index 00000000000..453b947d75c --- /dev/null +++ b/Master/texmf-dist/tex/latex/rcs/rcs.sty @@ -0,0 +1,1024 @@ +% $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.) + + + +%%%% +%%%% +%%%% These TeX macros were documented with the documentation system +%%%% MAKEPROG and automatically converted to the current form. +%%%% If you have MAKEPROG available you may transform it back to +%%%% the original input: Remove every occurence of three percents +%%%% and one optional blank from the beginning of a line and remove +%%%% every line which starts with four percents. The following Perl +%%%% command will do this: +%%%% +%%%% perl -pe 's/^%%%%.*\n//; s/^%%%( )?//' +%%%% +%%%% If you just want to print the documentation you may fetch +%%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory +%%%% pub/tex/latex). It contains *all* used styles -- but beware, they +%%%% may not be in a documented form... +%%%% +%%%% +%%% \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: |