diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/rcs/src/rcs-user.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/rcs/src/rcs-user.tex | 416 |
1 files changed, 416 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/rcs/src/rcs-user.tex b/Master/texmf-dist/source/latex/rcs/src/rcs-user.tex new file mode 100644 index 00000000000..025df2e7dfb --- /dev/null +++ b/Master/texmf-dist/source/latex/rcs/src/rcs-user.tex @@ -0,0 +1,416 @@ +% $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 |