% $StyleId: cwebparts.doc,v 1.1 1995/09/16 17:01:59 schrod Exp $ %---------------------------------------------------------------------- % Written by Joachim Schrod . % Copyright conditions see below. % % LaTeX package cwebparts % include parts of CWEB programs in LaTeX documents % % [LaTeX in MAKEPROG] % (history at end) %% FIXME: The user manual is not in cwebparts-user.tex. Most probably %% I'll make one user manual for the whole bundle; due to the usage of %% cwebbase class and package have lots in common. %% %% % If you have received this style file without the user manual (in the %% % file cwebparts-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{cweb-doc} % document-specific markup \usepackage{fullpage} \RCS $StyleRevision: 1.1 $ \RCS $StyleDate: 1995/09/16 17:01:59 $ \begin{document} \title{The \texttt{cwebparts} Package\\ {\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{schrod@iti.informatik.th-darmstadt.de}.% }% } \date{% Revision \RCSStyleRevision\\ (as of \RCSStyleDate)% } \maketitle % doesn't work with progltx yet %\tableofcontents \chap What's this style for?. This style supports inclusion of \cweb{} program parts in \LaTeX{} documents. For that it provides the environment |cweb| where \cweave{} output may be stuffed in. A more versatile explanation is available in the user manual of the \cweb{} bundle; this package is part of that bundle. % \begin{fixme} Read: ``should be available'' -- there is no bundle user manual (yet). |cweb-user.tex| will be enhanced after first testing of this code. \end{fixme} \sect The internal interface is also not described in this source, refer to the configuration documentation for this bundle. % \begin{fixme} Even worse: I don't even have written the internal specs for the \cls{cweb} class, not to speak of this package. \end{fixme} \chap Implementation. Most of the implementation is made available by the module \pkg{cwebbase}. We have to supply macros it demands from a user, and have to deliver the |cweb| environment. \sect This module reserves the namespace |cweb|. (This implies that it cannot be used with the \cls{cweb} class. But you don't want to do that anyhow. :--) \beginprog \ifx \cweb@loaded\undefined \def\cweb@loaded{$StyleRevision: 1.1 $} \else \PackageWarningNoLine{cwebparts}% {Some other package already uses namespace `cweb'} \fi \endprog \sect Let's identify this package. \noindent The code below is explained in the implementation documentation of the |rcs| package. \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{cwebparts}{include CWEB program parts in LaTeX documents} $StyleDate: 1995/09/16 17:01:59 $: 9999/00/00 \endRCS $StyleRevision: 1.1 $: 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 |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's placed there as a gzipped tar file. (The information on the IP~number is dated September~13,~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 \chap Typesetting \cweave{} output. The module \pkg{cwebbase} handles that. It demands some cseqs to be defined before it may be imported. % \begin{fixme} These cseqs should actually be implemented as package options. Have to extract the \pkg{keyvalx} code from the \cls{cweb} class first. Now I fix the usage I need for our Literate Programming book. \end{fixme} \begin{fixme} The options should not only be available as package options, but also on a per environment base. We might to typeset one part with flat and another one with hierarchic structure. Or we might to suppress format directives only in some parts, while other parts feature them. But this needs a change in \pkg{cwebbase}, there code is \emph{defined} depending on the cseqs below. It must be evaluated differently to support the stuff below. OTOH, this will cost performance -- is it worth it? \end{fixme} \beginprog \def\cweb@structure{0 } % hierarchic structure \let\if@cweb@suppress@changehints@=\iffalse % no suppression whatsoever \let\if@cweb@suppress@unchanged@=\iffalse \let\if@cweb@suppress@format@=\iffalse \input{cwebbase} \endprog \sect Now we can typeset pieces of \cweave{} output -- in principle. If these pieces have sections in them, they'll write entries to the |TOC| file. These entries will either mess up the structure of the document's table of contents or lead to \TeX{} error messages. That's because either toc entries for section types |part|, |chapter|, or |section| are written (causing the conflict); or toc entries for section types |chunk| and `|section|$i$' are written (being undefined). The best way seems to stop the included source to add anything to the table of contents or to do any mark processing. For that, we provide a macro |\CwebNoLists| that will locally redefine the \LaTeX{} cseqs that cause such actions to happen. That macro will be used at the start of the environment. \beginprog \def\CwebNoLists{% \let\addtocontents\@gobbletwo \let\mark\@gobble %% \let\markboth\@gobbletwo %% \let\markright\@gobble } \endprog \sect Furthermore, section divisions should not start a new page. % \begin{fixme} Currently, sections in the included parts are typeset exactly the same way as they're typeset in the main document. That should be different -- but how do I change it in a general way? \end{fixme} \beginprog \let\CwebEjectSection\@gobble \endprog \sect OK, what needs to be done for the environment? We need to save and restore counters that are changed globally by section commands. \beginprog \ifx \chapter\undefined \let\cweb@save_c@chapter\@gobble \let\c@chapter\@gobble \else \newcount\cweb@save_c@chapter \fi \newcount\cweb@save_c@part \newcount\cweb@save_c@section \def\cweb@save_for_env{% %% save values changed globally by cwebbase macros \cweb@save_c@chapter\c@chapter \cweb@save_c@part\c@part \cweb@save_c@section\c@section \let\cweb@save_thechapter\thechapter \let\cweb@save_thesection\thesection %% set up typesetting of CWEB source \@nobreaktrue % don't add space from first chunk } \def\cweb@restore_env{% \global\c@chapter\cweb@save_c@chapter \global\c@part\cweb@save_c@part \global\c@section\cweb@save_c@section \global\let\thechapter\cweb@save_thechapter \global\let\thesection\cweb@save_thesection } \endprog \sect For the moment, we use list spacing around a |cweb| environment. \LaTeX{} supplies the |trivlist| environment for such purposes. But the environment content itself must not be typeset in a list context. Two problems exist: There must be at least one |\item|, it will actually add the vertical space and must therefore not be discarded. And list environments redefine |\par|, but the \pkg{cwebbase} macros need a more `normal' definition. An item label is stored by |\item| in the |\everypar| register. The label is only typeset if |@inlabel| is true. The flag |@newlist| tells most other \LaTeX{} macros, that there was no item yet; typically they'll add an empty paragraph if necessary. As the content will start with a \LaTeX{} section division, or even with document markup, we don't want that empty paragraph and should skip the empty item label. (Often enough, due to the initialisation of |\everypar| in |\@startsection|, it will be thrown away anyhow). So we establish its postconditions, the next macro won't notice that the item hasn't been set actually. \begin{fixme} Experimentally, we reduce the skip in front of a chunk to 1\,pc, otherwise the distance between two chunks is far too wide compared to other vertical distances in the text around the included stuff. \end{fixme} \beginprog \def\CwebBeginEnvLayout{% %% use spacing of list, but switch off list handling afterwards \trivlist \@inlabelfalse % don't go in horizontal mode \item\relax \global\@newlistfalse \global\@inlabelfalse\the\everypar \@setpar{\@@par}% \CwebChunkPreSkip 1pc plus 6pt minus 3pt } \let\CwebEndEnvLayout=\endtrivlist \endprog \sect The environment gets trivial now. We supply a hook for a whole document and also environment-specific ones (as an optional environment argument). \beginprog \newenvironment{cweb}[1][]% {% \CwebBeginEnvLayout \cweb@save_for_env \CwebNoLists \csname CwebEnvHook\endcsname #1 }{% \CwebEndEnvLayout } \endprog \sect An a convenience tag to include a complete \cweave{} file. Since we want to test the typesetting of our included \cweb{} program alone, we allow but ignore most kinds of document markup. Many of them have two arguments, one is optional. In the preambel, only |\documentclass| and |\usepackage| may appear. Titlepage material is handled, table of contents is discarded. The document environment does nothing, i.e., unlike the \cls{cweb} class, material behind |\end{document}| is not ignored. An |\end| tag is inserted by \cweave{} and must be redefined, we don't end an environment there. We'll open a group and will use that tag to close it again, as we know that we'll have reached the end of our \cweb{} file. Of course, |\end| must not be redefined during processing the actual program source -- environments are valid there. The redefinition is best be triggered by material inserted from \cweave{} at the very end, e.g., from |\inx|. But |\inx| may not be there (when \cweave{} is called with the `|-x|' option), we'll use |\enddocument| to add a |\inx| tag for safety reason. If the user didn't add an |\end{document}| to his file and used `|-x|', we're going to loose. \TeX{}nical note: |\document| must not have the same binding as |\relax|, as this would be interpreted as a non-existing environment by \LaTeX{}. (That's due to the |\csname| lossage.) \TeX{}nical note: Evaluating |\inx| in |\enddocument| will not have any effect, we're inside a group. That evaluation must be postponed after the group has been closed. \beginprog \newcommand\cweb@doc_markup_gobble[2][]{} \newcommand*\cwebInput[1]{% \begin{cweb} [% \begingroup \let\documentclass\cweb@doc_markup_gobble \let\usepackage\cweb@doc_markup_gobble \let\title\@gobble \let\author\@gobble \let\date\@gobble \let\maketitle\relax \let\tableofcontents\relax \let\document\empty \def\inx{\let\end\endgroup}% \let\fin\relax \let\con\relax \def\enddocument{\aftergroup\inx}% ]% \input{#1}% \end{cweb}% } \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. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{rcslog} $StyleLog: cwebparts.doc,v $ \Revision 1.1 1995/09/16 17:01:59 schrod Add support for inclusion of \cweb{} files in \LaTeX{} documents. \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 compile-command: "make cwebparts.sty" End: