% $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{schrod@iti.informatik.th-darmstadt.de}}% } \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 This package may only be used with classes (or other packages) that define the `plain-style' font switch commands |\it| and |\rm|. This holds for all default classes, like |article|, |report|, |book|, etc. I expect most other classes to be derived from these ones, so this restriction should not bite you in reality. I need the functionality of these tags and didn't want to repeat their definition here. In my opinion, this was one of \emph{the} errors in the switch to \LaTeXe{}, that these tags are not defined in the kernel any more. Their additional functionality (switching unconditionally to some font, changing math fonts for letters) is needed much too often. \sect Sorry, you have another 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 calls `|co -kv|' internally.) 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$| and you check in your document, RCS will transform this to something like |\RCS $Revision: 1.1 $| 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$| \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$|\\ |\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! \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.) \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.th-darmstadt.de:pub/programming/management/confrcs|. (This is software in beta test; we welcome comments and bug reports.) \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$ \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