% $StyleId: cweb.doc,v 3.6 1995/11/30 15:44:53 schrod Exp $ %---------------------------------------------------------------------- % Written by Joachim Schrod . % Copyright conditions see below (GPL). % % LaTeX class cweb % support for LaTeX markup in CWEB sources % % [LaTeX in MAKEPROG] % (history at end) % If you have received this style file without the user manual (in the % file cweb-user.dvi or the respective LaTeX 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{cweb-doc} % document-specific markup \usepackage{fullpage} \RCS $StyleRevision: 3.6 $ \RCS $StyleDate: 1995/11/30 15:44:53 $ \begin{document} \title{The \texttt{cweb} Class\\ {\large (Implementation)}% } \author{% % LaTeX does not discard unnecessary glue... Joachim Schrod% \thanks{% \protect\raggedright TU~Darmstadt, Computer Science Department, WG Systems Programming, Alexanderstr.~10, D-64283~Darmstadt, Germany. Email: \texttt{jschrod@acm.org}% }% } \date{% Revision \RCSStyleRevision\\ (as of \RCSStyleDate)% } \maketitle % doesn't work with progltx yet %\tableofcontents % ------------------------------------------------------------ % % subdocument: The user interface of cweb.cls % \input{cweb-user} % % ------------------------------------------------------------ % % subdocument: The internal interface % \input{cweb-conf} % % ------------------------------------------------------------ \chap Implementation. This implementation must typeset complete files output by \cweave{}. Large parts of this task are available from the module \pkg{cwebbase}. It remains mainly to implement document-level markup and front and back matter (table of contents, index, etc.) In particular, the back matter material is not trivial; its tags are behind |\end{document}|, we have to read carefully behind the end of our \cweb{} document to detect if we have to typeset them at all. \sect This module reserves the namespace |cweb|. \beginprog \ifx \cweb@loaded\undefined \def\cweb@loaded{$StyleRevision: 3.6 $} \else \PackageWarningNoLine{cweb}% {Some other package already uses namespace `cweb'} \fi \endprog \sect Let's identify this class. \noindent The code below is explained in the implementation documentation of the \pkg{rcs} package. \beginprog \begingroup \def\RCSClass#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% \def\date{#4}\def\id{v#7}% \ProvidesClass{#1}[\date\space\id\space #2]% } \RCSClass{cweb}{LaTeX markup for CWEB sources} $StyleDate: 1995/11/30 15:44:53 $: 9999/00/00 \endRCS $StyleRevision: 3.6 $: 0.0 \endRCS \endgroup \endprog \sect This module is from a supported bundle. Send bug reports, comments and repairs. The reference version may be retrieved via anonymous ftp from |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/programming/literate-programming/c.c++/|. It's placed there as a gzipped tar file. (The information on the IP~number is dated August~29,~1995. It might have changed, although this is very unlikely. Use your friendly nameserver.) \sect This is freely distributable software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version~2 of the License, or (at your option) any later version. 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 \textsc{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 file the at sign is a letter anyhow; so we can use the ``private'' \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. Since somebody might use more styles from me, this cseqs might be defined already. \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 % is defined in Plain already \chardef\CatUsCode=\catcode`\_ \fi \catcode`\_=\CatLetter % top level macro file \endprog \sect Problems over problems with different \LaTeX{} versions. I have decided that I will take the same stand as the \LaTeX{} team: I will only support the last two official \LaTeX{} versions, folks who run older software might need to upgrade. The implementation will use `star'-forms of \LaTeX{}'s command definition macros. They were introduced with \LaTeX{} \mbox{$\langle$1994/12/01$\rangle$}. Currently (as of 07 Nov 95), 1995/06/01 is the most recent version. I want to use a features introduced with that version: |\newif| is not outer any more. So I check here for the version and supply the new definition if necessary. \beginprog \NeedsTeXFormat{LaTeX2e}[1994/12/01] \@ifl@t@r \fmtversion{1995/06/01}{}% else { \@namedef{newif}#1{% \count@\escapechar \escapechar\m@ne \let#1\iffalse \@if#1\iftrue \@if#1\iffalse \escapechar\count@ } \def\@if#1#2{% \expandafter\def \csname \expandafter\@gobbletwo\string#1% \expandafter\@gobbletwo\string#2\endcsname {% \let#1#2% }% } } \endprog \chap Options. Our options are of the ``keyword-value'' category. We realize them by the \pkg{keyvald} package, an enhancement of the \pkg{keyval} package from the Graphics bundle that supports defaulting for unknown keys. \begin{fixme} Most of the code below should be extracted and moved to a \pkg{keyvalx} package (or a new version of \pkg{keyval}). In particular, support for package/class option processing, enumeration values, and set values for keyword options. \end{fixme} |\ProcessKeyValOptions| may be used instead of |\ProcessOptions|, it takes the keyval set identifier as argument. At the end it evaluates and resets a hook. That hook may be used at option definition to define further dependencies. (E.g., enabling that option implies enabling an other option, too.) % \begin{fixme} Like |\ProcessOptions|, I define |\@curroptions|, since I don't know if that's needed later. The only place where it could been needed is in the check for unprocessed options. \end{fixme} \beginprog \RequirePackage{keyvald} \let\ProcessKeyValOptionsHook\empty \providecommand*\ProcessKeyValOptions[1]{% \edef\@curroptions{\@ptionlist{\@currname.\@currext}}% \edef\next{\noexpand\setkeys{#1}{\@curroptions}}% \next \ProcessKeyValOptionsHook \let\ProcessKeyValOptionsHook\empty } \endprog \sect The enumeration option |structure| selects hierarchic~(0) or flat~(1) structure. The predefined value is `hierarchic', there is no default. The option value is bound to |\cweb@structure|. \beginprog %% \define@key@enum{cweb}{structure}{hierarchic,flat}[hierarchic] \@namedef{KV@cweb@structure@enum:hierarchic}{0 } % <-- space! \@namedef{KV@cweb@structure@enum:flat}{1 } % <-- space! \define@key{cweb}{structure}{% \expandafter\let \expandafter\@tempa \csname KV@cweb@structure@enum:#1\endcsname % \relax if undefined \ifx \@tempa\relax \PackageError{cweb}% {% Invalid value `#1' for option structure% }{% Possible valid values are `hierarchic' and `flat'.\MessageBreak The predefined value is `hierarchic'.\MessageBreak There's no default value, you have to specify one.% }% \else \let\cweb@structure\@tempa \fi } \setkeys{cweb}{structure=hierarchic} \endprog \sect With the set option |suppress| one can select suppression of different document parts: |changehints| suppresses output of hints that a changefile was involved, |unchanged| output of unchanged chunks, |index| and |reflist| output of index and reference list, and |format| output of `|@f|' directives. The predefined value is no suppression. There is no default value. % \begin{fixme} Shouldn't I supply a default value? `|{index,reflist}|'? \end{fixme} Set options are represented by flags named |@cweb@|\