% % This file is part of mCWEB % Version 1.0 --- June 1996 % \documentstyle[path,epsf,bibnames,twoside,a4]{report} \def\mCWEB{{\tt mCWEB}} \font\tentex=cmtex10 % TeX extended character set (used in strings) \font\ninerm=cmr9 \font\eightrm=cmr8 \font\sevenrm=cmr7 \font\tenrm=cmr10 \font\adctitlefont=cmbx12 % font for Autodoc titles \font\tentex=cmtex10 % TeX extended character set (used in strings) \font\twelverm=cmr12 % ¬ \font\ninebf=cmbx9 % ¬ \font\ninett=cmtt9 % ¬ \font\ninesl=cmsl9 % ¬ \font\nineit=cmti9 % ¬ \font\ninei=cmmi9 % ¬ \font\ninesy=cmsy9 % ¬ \font\nineex=cmex9 % ¬ \font\sixbf=cmbx6 % ¬ \font\sixrm=cmr6 % ¬ \font\sixi=cmmi6 % ¬ \font\sixsy=cmsy6 % ¬ \font\fivebf=cmbx5 % ¬ \font\fiverm=cmr5 % ¬ \font\fivei=cmmi5 % ¬ \font\fivesy=cmsy5 % ¬ \let\cmntfont=\tenrm \let\mc=\ninerm % medium caps \def\CEE/{{\mc C\spacefactor1000}} \def\UNIX/{{\mc U\kern-.05emNIX\spacefactor1000}} \def\CTANGLE/{{\tt CTANGLE}} \def\CPLUSPLUS/{{\mc C\PP\spacefactor1000}} \def\named<#1:#2>{$\langle\,${#2\eightrm\kern.5em#1}$\,\rangle$} \newbox\PPbox % symbol for ++ \setbox\PPbox=\hbox{\kern.5pt\raise1pt\hbox{\sevenrm+\kern-1pt+}\kern.5pt} \def\PP{\copy\PPbox} \def\.#1{\leavevmode\hbox{\tentex % typewriter type for strings \let\\=\BS % backslash in a string \let\{=\LB % left brace in a string \let\}=\RB % right brace in a string \let\~=\TL % tilde in a string \let\ =\SP % space in a string \let\_=\UL % underline in a string \let\&=\AM % ampersand in a string \let\^=\CF % circumflex in a string #1\kern.05em}} \chardef\AM=`\& % ampersand character in a string \chardef\BS=`\\ % backslash in a string \chardef\LB=`\{ % left brace in a string \chardef\RB=`\} % right brace in a string \def\SP{{\tt\char`\ }} % (visible) space in a string \chardef\TL=`\~ % tilde in a string \chardef\UL=`\_ % underline character in a string \chardef\CF=`\^ % circumflex character in a string \def\angled#1{$\mangled{#1}$} \def\mangled#1{\langle\,\hbox{#1}\,\rangle} \outer\def\adoc#1{%\mark{#1} \begingroup \def\B{\rightskip=0pt plus 100pt minus 10pt % go into C mode \sfcode`;=3000 \pretolerance 10000 \hyphenpenalty 1000 % so strings can be broken (discretionary \ is inserted) \exhyphenpenalty 10000 \global\ind=2\noindent} \def\<##1>{{\vskip-\lastskip\advance\leftskip by-\parindent \bigbreak\noindent\bf##1 \par\smallskip}\noindent\ignorespaces} \long\def\*##1{\hangindent\parindent\noindent##1\par\smallskip} \goodbreak\vskip 15pt plus 6pt minus 6pt\noindent{\adctitlefont #1} \nobreak\smallskip\hrule\advance\leftskip by\parindent\nobreak} \outer\def\endadoc{\nobreak\bigskip\hrule\goodbreak\vskip 15pt plus 6pt minus 6pt \endgroup}%\vfill\eject} \def\adocmode{ \newcount\ind % current indentation in ems \def\B{\rightskip=0pt plus 100pt minus 10pt % go into C mode \sfcode`;=3000 \pretolerance 10000 \hyphenpenalty 1000 % so strings can be broken (discretionary \ is inserted) \exhyphenpenalty 10000 \global\ind=2 \1\ \unskip} \mathchardef\AND="2026 % bitwise and; also \& (unary operator) \def\|##1{\leavevmode\hbox{$##1$}} % one-letter identifiers look better this way \def\\##1{\leavevmode\hbox{\it##1\/\kern.05em}} % italic type for identifiers \def\1{\global\advance\ind by1\hangindent\ind em} % indent one more notch \def\2{\global\advance\ind by-1} % indent one less notch \def\3##1{\hfil\penalty##10\hfilneg} % optional break within a statement \def\5{\hfil\penalty-1\hfilneg\kern2.5em\copy\bakk\ignorespaces}% optional break \def\6{\ifmmode\else\par % forced break \hangindent\ind em\noindent\kern\ind em\copy\bakk\ignorespaces\fi} \def\7{\par\smallskip\6} % forced break and a little extra space \def\C##1{\5\5\quad$/\ast\,${\cmntfont ##1}$\,\ast/$} \def\&##1{\leavevmode\hbox{\bf \def\_{\kern.04em\vbox{\hrule width.3em height .6pt}\kern.08em}% ##1\/\kern.05em}} % boldface type for reserved words \def\setsec{\rightskip=0pt % get out of C mode (cf. \B) \sfcode`;=1500 \pretolerance 200 \hyphenpenalty 50 \exhyphenpenalty 50} \let\K== % assignment operator \newbox\bak \setbox\bak=\hbox to -1em{} % backspace one em \newbox\bakk\setbox\bakk=\hbox to -2em{} % backspace two ems \parskip 0pt % no stretch between paragraphs \parindent 1em % for paragraphs and for the first line of C text } \def\smallfont{ % small fonts for C examples ¬ \textfont0=\ninerm \scriptfont0=\sixrm \scriptscriptfont0=\fiverm \def\rm{\fam0 \ninerm} \textfont1=\ninei \scriptfont1=\sixi \scriptscriptfont1=\fivei \def\oldstyle{\fam1 \ninei} \textfont2=\ninesy \scriptfont2=\sixsy \scriptscriptfont2=\fivesy \textfont3=\nineex \scriptfont3=\nineex \scriptscriptfont3=\nineex \def\it{\fam\itfam\nineit} \textfont\itfam=\nineit \def\sl{\fam\slfam\ninesl} \textfont\slfam=\ninesl \def\bf{\fam\bffam\ninebf} \textfont\bffam=\ninebf \scriptfont\bffam=\sixbf \scriptscriptfont\bffam=\fivebf \def\tt{\fam\ttfam\ninett} \textfont\ttfam=\ninett} % ¬ \title{{\tt mCWEB}, an Extension of {\tt CWEB} for Teams} \author{Markus \"Ollinger} \begin{document} \bibliographystyle{plain} \pagestyle{headings} \maketitle \begin{titlepage}\ \end{titlepage} \begin{abstract}\setcounter{page}{1} This book describes \mCWEB---a descendant of the \CWEB\ system of structured documentation by Donald E.~Knuth and Silvio Levy---that adds some features that are indispensable when working in a team. \mCWEB\ regards a project as a book consisting of several chapter files. By means of import and export commands, it automatically manages all relationships between the chapters of a book and to other books. Interface Documentation is now part of the \mCWEB\ file and can be extracted into a second \TeX\ file. This allows to define well known interfaces between the individual parts of a project that will be implemented by different persons. In the first part, this paper also gives a general overview about literate programming and tries to give hints how to write \lq good literate programs\rq. \end{abstract} \ \thispagestyle{empty}\newpage \tableofcontents \part{Literate Programming} \chapter{Overview} The term \lq literate programming\rq\ has been introduced by Donald E.~Knuth in~\cite{Knuth:CJ-27-2-97}. Knuth thought programs should best be seen as works of literature that are meant to be read by human beings. The main difference to conventional methods is that a programmer is supposed to write the program as if he or she wants to present it to another programmer, which means that one should present the program in any order which is suitable to understand it easily. Knuth has created two preprocessor tools which make it possible to combine documentation and code in one document, the \.{WEB} system of structured documentation \cite{Knuth:web83}. It has been used to write programs of any size, from rather small examples \cite{Bentley:CACM-29-5-364,Bentley:CACM-29-6-471} to rather large ones like \TeX\ \cite{Knuth:ct-b} and \MF\ \cite{Knuth:ct-d}. In a \.{WEB} program, code is divided into manageable {\em sections} which can be arranged in any order. This makes it possible to present a program so that it is easier to understand for human beings and not in the order the compiler expects to see it, since there is no reason to explain programs to compilers: they simply do not care anyway. Some sections may have a name which means that they can be inserted in completely different places of the source program thus making code rearrangement possible.\medskip {\bf4.\quad}\named<4:Set initial values>=\par \hskip1em$x:=1$;\par \hskip1em$y:=2$;\par\medskip \noindent means that the given chunk of code can be used in the program under the name \angled{Set initial values} and that it is first defined in section~4. If one defines another section with the same name, the code is accumulated. So, if one writes (maybe much later in the program):\medskip {\bf15.\quad}\named<4:Set initial values>+=\par \hskip1em$z:=1$;\par\medskip \noindent it will simply be appended to the code defined above. In this particular case, this means that one can insert our named section in a place where all initialisation should be done and then define the different parts of initialisation wherever one wants. This makes it easy to define and initialize a variable where it is first used and not at the very beginning of the program where the compiler requires it to be. \noindent The general outline of a section is \begin{enumerate} \item Description as an ordinary \TeX\ text. \item Macro definitions and formatting hints. \item Code part of the section. \end{enumerate} \noindent where each of these parts may be missing. Sections get numbers starting with one, so that they can be referenced. The translation process from the combined code/document {\tt WEB} source file to an ordinary computer language (like {\sc PASCAL} in the case of Knuth's {\tt WEB}) is done by a preprocessor called {\tt TANGLE}. Another preprocessor, {\tt WEAVE} converts the {\tt WEB} file into a \TeX\ file that can subsequently be printed. \.{WEAVE} also automatically creates an index containing all identifiers with references to the section numbers where they have been defined or used. \begin{figure}[h] \centerline{\epsfbox{mcwebman.1}} \caption{{\tt WEB} file as a common source} \end{figure} \section{Literate Programming Tools} Many people found that \.{WEB} could not fulfill all their needs and they built their own literate programming tools. A couple of tools have been largely accepted by the literate programming community. These tools can be divided into two parts: language dependent tools and language independent tools with each having their own advantages. Language independent tools are not restricted to any formatter and can be used with any language, but they cannot support the programmer as much as language dependent tools can. They usually don't do pretty-printing since they don't know anything about the syntax of their host language. Some people think that this is an advantage rather than an inconvenience, especially if the language dependent tool's pretty-printing does not conform to their own style. Among the literate programming tools, \.{FWEB} \cite{Avenarius:SIGPLAN-25-1-52} and \.{FunnelWEB} \cite{Williams:FUM92}, and especially the language independent tools \.{noweb}~\cite{Ramsey:LPT92} and \.{nuweb}~\cite{Briggs:NUWEB-93} have become popular. The latter have the advantage of being very simple (where \.{noweb} uses \.{awk} (or \.{icon}) scripts and is therefore a little bit more \UNIX/ related than \.{nuweb}). \.{nuweb} has the advantage of having its options embedded in the program itself, so that there are not that many command line options necessary. \.{noweb} passes the input source through a pipeline of filters allowing for user customisation without recompiling. Knuth's \.{WEB} has been ported to different languages and further extensions were made to the syntax of the language. Only the \CEE/ version \.{CWEB}~\cite{Knuth:CSS93} has become more widespread and is still maintained. Marc van Leeuwen has build a \.{CWEB} clone called \.{cwebx} with some enhancements. \section{The {\tt CWEB} System} In this section, we want to take a closer look at \.{CWEB}. For more detailed explanations, please consult~\cite{Knuth:CSS93}. \subsection{Introduction} We have already seen, that web programs consist of small sections that contain a \TeX\ part describing what's going on in this section, a macro part with macro definitions and a \CEE/ part containing one piece of code of the whole program. Each of these parts may be empty, but if present, they must appear in that order. \par\medskip\begingroup\tt\obeylines @\SP We will define a data structure called |pair| that can contain two integer values |x| and~|y|. We will store our coordinates in |pair| variables. @d dist(x,y) sqrt(x*x+y*y) @c struct pair $\{$ \hskip1em int x,y; $\}$; \endgroup\par\medskip\noindent As one can see, sections are introduced by \.{@\SP} or an \.{@} sign immediately followed by a newline. \.{@d} defines constants and macros just like {\bf\#define} does except that these constants are also known in the preceding sections and not only in the following ones. The command \.{@c} introduces the \CEE/ part of the section. In the above example, we define a data structure. As already mentioned, the \CEE/ part of a section can be given a name, thus making it possible to insert it somewhere else in the program. If one wants to name the \CEE/ section, one must use \.{@<\dots@>=} instead of \.{@c}. \par\medskip\begingroup\tt\obeylines @ @c \hskip1em@; \hskip1em@; \smallskip\dots\smallskip @*Transformations. We will define a global transformation matrix |transformation\UL matrix| that is applied to all points to map them on the screen. @= \ \ struct matrix transformation\UL matrix; \smallskip @ We have to keep track where the pen currently is, so we store its current position in |pen|. @+= \ \ struct pair pen; \endgroup\par\medskip\noindent The first section defined here is a \.{@c} section, which means it will be written to the resulting \CEE/ file. This section contains two named sections, \lq Types\rq\ and \lq Global Variables\rq\ that are defined elsewhere in the program. The following section defines the \lq Global Variables\rq\ section. In the last section, we have the section name \.{Glob...} which is simply an abbreviation for {\tt Global Variables}. \.{CTANGLE} merges all named sections with the same name together, so the code defined there will be appended to the named section {\tt Global Variables}. \subsection{Titles for Sections} In the above example, we have seen another kind of section, a {\em starred section} \.{@*}. Starred sections are like ordinary \.{@\SP} sections but the \.{*} is followed by an optional level number and a name terminated by a period. One can see the web sections like paragraphs in a book. Like each paragraph explains something to the reader and one starts a new paragraph each time one introduces something new, each section has one clear topic. In traditional books, paragraphs are grouped into chapters. In \CWEB, a section can be {\em starred}. Starred sections have a name that represents a kind of title for all following sections. This makes it possible to say: everything that follows now is dealing with transformations. \par\medskip\begingroup\tt\obeylines @*Transformations. Let's have a look at the routines that perform transformations. There are three different kinds of transformations: Translation, Rotation and Scaling. \smallskip @*1Translation. \angled{\it sections dealing with translation} \dots @*1Rotation. \dots @*1Scaling. \endgroup\par\medskip\noindent Like a book has a table of contents with all its chapters, \.{CWEAVE} makes a table of contents containing all starred sections. As indicated above, starred sections may have a level. This is like having chapters that contain sections which in turn consist of subsections and so on. The lower the level, the bigger is the title. The default level is zero. The highest level is \.{@**} which corresponds to level~$-1$. \subsection{Translating a {\tt CWEB} File} The \.{CTANGLE} preprocessor converts a \.{CWEB} file into an ordinary \CEE/ file that can be passed on to the compiler. The \CEE/ file will contain {\bf\#line} instructions so that debugging can be performed on \.{CWEB} level. \.{CTANGLE} rearranges the sections by collecting all named sections and then inserting them at the right places into the program. In addition, \.{CTANGLE} moves all macro definitions to the very beginning of the program or to the place where the \.{@h} command was given. \.{CWEAVE}, on the other hand, takes the \.{CWEB} file and converts it into a \TeX\ file ready to be typeset by \TeX. \.{CWEAVE} does not only pretty-print the code, it also automatically creates an index containing all identifiers defined in the source file with references to the various section numbers, as well as a list of all named sections and a table of contents containing all starred sections. \subsection{Formatting Issues} First of all, one has to understand that \CEE/ code is different from \TeX\ text. \TeX\ text follows \TeX\ rules, which means that some special symbols like '\.{\UL}' have to be protected by a backslash. \CEE/ text is pretty-printed by \.{CWEAVE} and converted into \TeX\ text, so here, this conversion is done automatically. If one wants to refer to variable and function names in \TeX\ text, one has to enclose them in \.{|\dots|} to inform \.{CWEAVE} that everything in between has to be formatted in \CEE/ code style. The opening '\.{|}' and the closing '\.{|}' have to be on the same line. On the other hand, ordinary \CEE/ comments in the code part of the section will be regarded as \TeX\ text. Likewise, the name of a named section is also \TeX\ text. Every \CWEB\ program includes a macro package called \.{cwebmac.tex}, that contains a bunch of \TeX\ macros to typeset the code. Most of these macros are of no use to the programmer, they are simply used by \.{CWEAVE}. There is one possibility of changing the appearance of special identifiers. This has to be done in the macro part of a section by \.{@f \it identifier like-identifier}. This causes \.{CWEAVE} to treat the given identifier like {\it like-identifier}, thereby making it possible to introduce new keywords. If there is a keyword {\bf\_\_far} on the system and one wants it to be a qualifier like {\bf extern}, one simply writes: \.{@f \UL\UL far extern}. If one doesn't want this definition to appear in the output file, \.{@s} is used instead of \.{@f}. These formatting commands also provide a more powerful way to change how \.{CWEAVE} typesets the identifier. If, for example, one has an identifier {\it alpha} and one wants \TeX\ to print it like $\alpha$ in the output, one simply states: \.{@f alpha TeX}. In general words, \TeX\ will then use a \TeX\ macro with the same name as the identifier to typeset the identifier. This means, that one can define a macro in the limbo part of the \.{CWEB} file (that is the part before the first section starts) $$\.{\\def\\ax\{a\UL x\}}$$ and then give a formatting command in the middle part of a section $$\.{@f ax TeX}$$ telling \.{CWEAVE} to use the \TeX\ macro {\it ax} to typeset the variable \.{ax} like $a_x$. \subsection{Other Commands} We have already seen that \.{@\SP} and \.{@*{\it title}.} introduce a section. Please try to keep \TeX\ commands in {\it title} simple since it will also be used in the header line of each page. Next comes the \TeX\ part of the section. This is eventually followed by a middle part, defined by \.{@d} (macro definition), \.{@f} or \.{@s} (formatting commands). Last but not least we can have a unnamed \.{@c} code part or a named \.{@<{\it name}@>=} \CEE/ code. There is another way of introducing the \CEE/ part of a section. If one says \.{@({\it file name}@>=}, \.{CTANGLE} treats this named section like all others except that it will be output to the given {\it file name} and not to the default output file. This can be used to generate header files. \.{@h} determines where all the \.{@d} macro definitions go. If no \.{@h} is encountered, the macros are inserted at the very beginning of the output file. One should normally put a \.{@h} after having included the system header files. There are also three commands to insert text into the index. \.{@\^{\it text\/}@>} inserts the given text using roman font type. Likewise, \.{@.{\it text\/}@>} inserts something in typewriter type. The third command, \.{@:{\it text\/}@>} can be used to enter text into the index which is under the control of \TeX\ macro \lq\.{9}\rq, which has to be defined by the user. \noindent Now let's take a look at the rest of \.{CWEB}'s commands: \begin{description} \item[\.{@t{\it\TeX{} text\/}@>}] will put the given \TeX\ text into a \.{\\hbox} and insert it at the current position in the output file. \item[\.{@={\it text\/}@>}] will pass {\it text} verbatim to the \CEE/ program. \item[\.{@q{\it text\/}@>}] will cause {\it text} to be totally ignored. It's only a comment for the reader of the source. \item[\.{@!}] This will cause the section entry in the index for the identifier or control text following the \.{@!} to be underlined thus indicating that it is defined here rather than only used. \item[\.{@\&}] Causes the left and right side of \.{@\&} to appear adjacent to each other with no blank in between, in the \CEE/ output. \item[\.{@l {\it hex-code char-replacement}}] In \.{CWEB} programs, one can use all 8-bit characters in identifiers. This makes it possible to use german umlauts in a program. By default, \.{CTANGLE} translates them into their hex code, which means that a variable {\it Men\"u} will be changed into \.{MenXFC}, since the hex code for \lq{\tt\"u}\rq\ is \.{0xfc}. If one says \.{@l fc ue}, {\it Men\"u} will become \.{Menue} in the resulting \CEE/ program. The \.{@l} may only appear in limbo, i.e.~before the first section starts. Note, that the \lq\"u\rq\ will be passed on to \TeX\ by \.{CWEAVE}, so TeX\ must be able to handle high bit characters to print them properly. One should have a macro package coming with the \TeX\ distribution to do this. In case it is not provided, here is a template for \lq\"u\rq: \par\medskip\begingroup\obeylines\tt\parskip0pt\advance\leftskip by1em \BS lccode'\"u='\"u \BS uccode'\"u='\"U \BS lccode'\"U='\"u \BS uccode'\"U='\"U \BS catcode'\"u=\BS active \BS def \"u\{\BS "\{u\}\} \endgroup \item[\.{@,}] inserts a thin space into \.{CWEAVE}'s \TeX\ output. \item[\.{@/}] tells \.{CWEAVE} to break the line at this place. \item[\.{@|}] This is an optional line break one might insert into long formulae to give \TeX\ a hint where to break the expression. \item[\.{@\#}] Like \.{@/}, this forces a line break. In addition, it causes a little vertical skip to appear before the next line comes. \item[\.{@+}] Has the opposite effect of \.{@/} since it prevents \.{CWEAVE} from breaking the line at this point. This can be used to put more than one instruction on a single line. \item[\.{@;}] is treated like an ordinary semicolon except that it does not appear in the output. One can set a \.{@;} after each inserted named section to make it look like an ordinary statement. \par\medskip\begingroup\obeylines\tt\parskip0pt\advance\leftskip by1em \dots if(x) @@; else @@; \endgroup \item[\.{@[\dots@]}] tells \.{CWEAVE} that everything that is enclosed in the bracket should be formatted like an expression. In particular, one should use \.{@[@]} when using a pointer to a function, $$\.{int @[@] (*f)();}$$ otherwise \.{CWEAVE} will believe it's a \CPLUSPLUS/ cast expression ${\bf int}(*f)$. \item[\.{@i \it file name}] inserts the given file at this point in the web file. \end{description} \subsection{The Change File} Change files are used to make minor changes to a web source file to reflect local conditions. They simply replace individual lines of the web source by others. The format of a change file is as follows: \par\medskip\begingroup\obeylines\tt @x {\it original lines in web source} @y {\it lines that should replace the above ones} @z \dots \endgroup\par\medskip\noindent The original lines must exactly match the lines to replace in the web source. After the \.{@z} comes the next line chunk to override. All replacement texts must appear in the same order they appear in the web source. The change file may be passed in addition to the web file to the preprocessors. So, to invoke \.{CTANGLE} one can pass the following arguments: $$\.{ctangle $[$options$]$ webfile$[$.w$]$ $[\{$changefile$[$.ch$]\vert$-$\}$ $[$outfile$]]$}$$ To start \.{CWEAVE} simply replace the name \.{ctangle} by \.{cweave}. For a list of options, see Table~\ref{tabflags}. \section{Pros and Cons} We have now seen how \.{CWEB} programs look like and what commands the system offers. If one wants to see how a final \.{CWEB} program looks like take a look at part two, the implementation of \.{mCWEB}. It should not be denied that writing \.{CWEB} programs requires an additional intellectual effort. \begin{center} {\bf Writing a literate program is harder than writing a program in a traditional language!} \end{center} \noindent One should not underestimate the effort required to present a program so that it is easily comprehensible. Computer programs are inherently complex and making them easier to understand is quite a challenging task. Programming in the \lq literate style\rq\ does not only mean documenting programs for the poor soul who comes after and will have to maintain it, it also makes sense during the implementation phase. Large programs are said to grow until they exceed the intellectual faculty of their creators. This means that from a certain point on, even the creator of a program will lose control over it. For this reason, the easier a program is to understand, the longer its creators will be able to understand what has been done so far. However, everything has its price. \subsection{What does it cost?} Literate programming is not the same as \lq writing programs with many comments\rq. It is a completely new style of writing software products which---if used properly---can lead to better quality, but one can also produce a totally illiterate program with a literate programming tool. It takes time to learn how to program in a literate way and software metrics must be found to mesure the \lq literateness\rq\ of a program. \noindent In~\cite{Ramsey:LPT92}, Ramsey wrote: \begin{quotation} \noindent {\tt WEB} is a complex tool. In addition to enabling programmers to present pieces of a program in any order, it expands three kinds of macros, pretty-prints code, evaluates some constant expressions, provides an integer representation for string literals, and implements a simple form of version control. The manual for the original version documents 27 ``control sequences''~\cite{Knuth:web83}. \end{quotation} \noindent Ramsey then created his own tool \.{noweb} with focus on simplicity and extensibility. As far as the implementation details of \.{CWEB} are concerned, it is true: \.{CWEB} is complex. However, I disagree with Norman Ramsey that using \CWEB\ is too complex. \.{WEB}'s 27~control sequences contain some commands which are rarely needed. It is easy to keep those in mind which are used frequently, and to simply forget about the others (or look them up if one really should need them one day). According to examinations of five \.{WEB} programs in~\cite{Smith:SP-13-1-35}, only \.{@\SP}, \.{@<\dots@>} and \.{@!} were used frequently, \.{@*}, \.{@p}, \.{@d}, \.{@;}, \.{@/} and the index entry commands \.{@\CF} and \.{@.} were rarely used, and most other commands did never appear at all. At first glance, the biggest hurdle is \TeX. If one doesn't know plain\TeX\ at all, he or she will have a hard time formatting the programs. This is the reason why literate programming is not very widespread on Microsoft operating systems, where Word is the favorite documentation system (although some optimists are attempting to make WYSIWYG literate programming tools using Winword). However, examining some of my own \.{CWEB} programs, I found out, that one can get by using very few \TeX\ commands, most of them were \.{\\item} commands, various math typesetting commands or font switching commands like \.{\\it} or (the \CWEB\ specific) \.{\\.}. What is even harder to learn is how to write a good literate program. Similar to some \CPLUSPLUS/ programs which have nothing to do with object oriented programming, some people use literate programming tools to insert a \TeX\ comment every now and then. They have not changed their way of thinking or writing and don't use the new features at all. Learning how to write a real \lq literate\rq\ program requires probably the most effort. I think one can do that with any literate programming tool since all of them are extremly simple compared to the computer language itself. \subsection{Why it is worth the Trouble} Despite all the difficulties, one should give it a try. Like authors of novels tend to fail with their first book because of their lack of experience, one cannot expect one's first works of computer literature to be a masterpiece. Nevertheless, the more literate programs one writes, the better they will be and everyone will evolve his own \lq literate programming style\rq. In this section, we want to present a few arguments in favor of literate programming. Maybe they will convince you to give it a chance. \subsubsection{It can be Fun} Literate programming is fun. Knuth once said in an interview: \begin{quote} Jill [his wife] will tell you, I come out of my office serveral times a week saying, ``\.{CWEB} programming is such fun!'' It's true, I just can't do enough of it. \end{quote} This is mainly due to the aesthetic aspect. Literate programs are \lq literary works of art\rq\ (see Chapter one in \cite{Knuth:LP92}: Computer Programming as an Art). People who like to explain what they are doing and to present their work will enjoy writing literate programs. Since a motivated worker will do a better job, this should also be in the company's interest. \subsubsection{Better Documentation} What is a little bit more obvious is the excellent documentation a literate program can contain. Literate programs are better documented. This is not only because of automatic index generation---which makes it easy to find the places where an identifier is defined and used---and division into small pieces that can be described more easily than large blocks could be, there is also a psychological reason. In a \.{CWEB} program, there is a language defined place where the preprocessor expects the comments. If one omits the explanations of a section, the lonesome \.{@\SP} looks a little bit like an accusation: what, you have nothing to say about this section? If there are supposed to be some explanatory sentences after a \.{@\SP}, people will put them there. Better documentation is essential if one doesn't intend to throw away one's software product after one has finished it (and I hope nobody does). The largest part of software costs is in the maintenance phase, when the product is already shipped and error corrections as well as enhancements are necessary. These modifications can only be done efficiently, if the programmers in charge have a thorough knowledge about the internals of the program. However, most programs are not maintained by their original authors, because either they are already working on another project or they have left the company. Even if exactly the same group is maintaining the program for its whole lifetime, they will not be able to keep the details in mind. Time is wasted on code analysis of things that once have been known, but of which all the knowledge is gone since it was not written down. \subsubsection{Less Errors} \.{CWEB} does not only help mastering the maintenance phase, the test phase will usually be shorter too. It seems that writing a verbose documentation does not only lead to better documented code, it also has better quality, and: for free!\par \noindent Knuth \cite{Knuth:CJ-27-2-97} found out \begin{quote} The costs of \.{WEB} are more difficult to estimate at higher levels, but I have found to my surprise that the total time of writing and debugging a \.{WEB} program is no greater than the total time of writing and debugging an ALGOL or PASCAL program, even though my \.{WEB} programs are much better, and even though I am putting substantially more documentation into the programs. [\dots] The extra time I spend in preparing additional commentary is regained because the debugging time is reduced. \end{quote} \noindent This does not mean that one doesn't have to test anymore, but one simply will find many errors before they appear in testing and therefore one doesn't have to correct them during the test phase. This conforms with my own experience: literate programming does not shorten the process of software {\em creation}, but neither does it lengthen it, so the only thing one gets is a better documented code of better quality in about the same time one would have spent writing an ordinary \CEE/ program. \subsubsection{Better Quality} The effect that programmers suddenly impose higher quality standards on themselves when they start writing literate programs is due to the fact that literate programs are meant to be published. Even if the final document never finds its way out of the company, surly no programmer wants to create a nice looking final document that contains code of bad quality, since everybody \lq could\rq\ read it and find out. In addition, if one explains what he or she is doing in a section, one is in \lq expository mode\rq\ which means that one has to clarify his or her thoughts in order to explain them in an understandable way. \subsubsection{Code Reviews} The style of literate programming encourages a team to make code reviews and walkthroughs, since \.{CWEB} programs are easy to read and therefore also easy to present. During such code reviews, implementation details and design decisions are discussed and all members of the group are encouraged to give their opinions. Individual criticism should be avoided in the review process. \noindent Code Reviews \begin{itemize} \item are a way to statically verify programs, thus ensuring quality, \item help to find errors and design flaws at an early stage in the software process, \item make sure one doesn't lose the overview about the different parts of a project, \item lead to commonly accepted, consistent \lq company standards\rq, without imposing them by means of \lq company laws\rq. \end{itemize} \subsubsection{Freedom} Literate programming offers no methodology. It does not say that one has to use top-down or bottom-up design. It does not require the use of object oriented analysis. One can simply use it as one likes. No restrictions, no limitations. The reason why \CEE/ has become so popular is not because it is such a great language that offers features no other language offers, but because it does not restrict the programmer. Everybody has seen examples showing \CEE/ programs with lots of \.{?:} operators and other tricky things nobody but the author himself can understand, but nobody writes such programs. \CEE/ programs tend to be as structured or unstructured as Modula-2 or ADA code. But if one wanted to do something in a tricky way, he or she would be able to do so, and sometimes a tricky, well documented implementation really makes a programmer's job easier. You could, if you wanted. That's why people are using \CEE/. That's why people should use literate programming. Note that \.{CWEB} makes it easy to write programs nobody will ever be able to understand. As far as that is concerned, it is even worse than pure \CEE/. As a matter of fact, it is easy to confuse the reader if, for example, the closing brace is not in the same section as the opening brace of a compound statement. Sections should always contain full blocks. \par\medskip\begingroup\obeylines\tt @ @c int func( @ \hskip1em return x+1; \} \smallskip @ @= int x) \{ \endgroup\par\medskip\noindent is not really a good example of a good literate programming style. However, since most programmers are old enough to know what they are doing, nobody will be crazy enough to do write such code. \section{A Guide to Literate Programming} The purpose of this chapter is to provide a set of rules of thumb which should help to write literate programs that really merit this label. When writing a literate program, we have to answer the following questions: \begin{itemize} \item Which starred section shall we define (at which level of hierarchy)? \item In which order shall we arrange our sections? \item What is each section supposed to contain? \end{itemize} \subsection{Literate Programming and Design} In \cite{Knuth:CJ-27-2-97}, Knuth writes \begin{quotation} \noindent I think that a complex piece of software is best regarded as a {\it web} that has been delicately pieced together from simple materials. We understand a complicated system by understanding its simple parts, and by understanding the simple relations between those parts and their immediate neighbors. \noindent\dots \noindent I have come to realize that there is no need to choose once and for all between top-down and bottom-up [design], because a program is best thought of as a web instead of a tree. \end{quotation} \noindent I think that programs are best seen as a web {\em and} as a tree. \.{CWEB} provides a hierarchical way of presenting the program using {\em starred sections} which allows us to give a collection of sections a name which can itself be part of another starred section, like we group several paragraphs of an article in sections which can be subsections of another one. Sho-Huan Tung has presented a literate programming method called HSD (hierarchical structured document) \cite{Tung:JSP-10-2-113}. The Table of Contents usually provides valuable information about the design of a program as the following excerpt shows: \par\medskip\goodbreak\noindent\begingroup \def\line{\hbox to\hsize} \def\contentsline#1#2#3#4{\ifnum#2=-1 \smallbreak \line{\ifnum#3=-1\else\hbox to2em{\bf#3\hss}\fi \bf#1\hfil\rm\hbox to3em{\hss\bf#4}} \else\goodbreak \line{\consetup{#2}#1 \rm\leaders\hbox to .5em{.\hfil}\hfil\ #3\hbox to3em{\hss#4}} \fi} \def\consetup#1{\ifcase#1 \hskip2em\bf % depth -1 (@**) ¬ \or \hskip2em % depth 0 (@*) \or \hskip4em % depth 1 (@*1) \or \hskip6em % depth 2 (@*2) \or \hskip8em % depth 3 (@*3) \or \hskip10em % depth 4 (@*4) \or \hskip12em % depth 5 (@*5) \else \hskip14em \fi} % depth 6 or more \let\ZZ=\contentsline \ZZ{Actions}{-1}{4}{61} \ZZ{Actions of the Scrollbar}{2}{11}{64} \ZZ{Shift-Click on the Scrollbar}{3}{12}{64} \ZZ {Click on Scrollbar without Shift}{3}{13}{64} \ZZ {Actions of the Drawing Area}{2}{14}{64} \ZZ {New Window Size}{3}{15}{65} \ZZ {Draw Icons}{3}{16}{65} \ZZ {Mouse Button 1 or 2 pressed}{3}{26}{72} \ZZ {Mouse moved while Button pressed}{3}{38}{78} \ZZ {Mouse Button 1 or 2 released}{3}{43}{82} \ZZ {Mouse Button 3 pressed}{3}{62}{95} \ZZ {Actions of the Shell}{2}{64}{95} \ZZ {Focus assigned}{3}{65}{96} \ZZ {Focus lost}{3}{70}{98} \ZZ {Reparent}{3}{71}{98} \ZZ {Index}{1}{72}{99} \endgroup\par\medskip\noindent Looking at this table, we can immediatly distinguish the various parts the translation unit consists of. This reflects the {\em architectural design}, only stating the different parts in a single line. When one is about to start a literate program, he has to take a look at the design to identify the various parts and break it up into units of the same purpose. In~\cite{Brown:SP-11-2-85} one can see examples how three convention design methods, top-down design, data-flow design and JSD (Jackson System Design), can be converted into a literate program that still captures the original design. It is generally a good idea to include the whole design into the literate program, otherwise everybody who wants to read and understand the program will have to recover the design from the code. In \TeX\ it is not only possible to typeset mathematical formulas that can describe the behaviour of the program, one can also include graphics to describe the design. As indicated in~\cite{Lins:JSP-10-1-60}, diagrams are also very useful for depicting the organization of data structures and their interrelations. John Hobby's Metapost~\cite{Hobby:TB10-4-505-512} is a great tool that allows to draw data structures (among other things) using a script language to define them. \subsection{Determining Section Order} The individual sections of a program can be arranged in any order, which can be regarded as a big advantage, but not every order is equally good. The task of deciding in which order to present the sections is nontrivial and strongly determines how \lq literate\rq\ a program really is. I found out that, when I am writing a \.{CWEB} program, I always try to present the code in that order, that it can be read sequentially without jumping around in the source code. If moving around should be necessary, the index greatly helps in finding the right place, but nevertheless, this should be avoided. This order implies that, when I refer to parts of the program that will be defined later in the program, I only do it using a named section (or a function call, if necessary). This means that every time I add a new function or named section to the \.{CWEB} source, I don't add it \lq where the cursor is\rq, but I have to decide where it fits best so that all parts that should be known to understand it are defined earlier in the program (or at least in one of the following sections) and everything that depends or uses the new code comes later in the source. This is very similar to a PASCAL programmer writing a program in the order the compiler needs it except that one writes it in the order the human reader needs it. Note that this order will be completely different. A program might start with the {\it main$(\,)$} section without really depending on things defined later, just containing a number of named sections outlining the general functionality of the function on an abstract level without going into detail. In particular, I describe all data structures prior to their first use. If a function uses a data structure not yet introduced, one will not define the function prior to the definition of this datatype. It is generally a good idea for most typical applications to start defining a couple of suitable data structures. \CPLUSPLUS/ programmers will think of them as classes. Then a couple of (member) functions are added dealing with that data structure. Basic functions appear before the more sophisticated ones. Last but not least we must bring the datatype definitions in the right order, which means that we will start with those datatypes that have the least dependencies. \subsection{The Contents of each Section} We have seen how to determine which starred sections we should have and in which order they should be presented. Now, we want to consider what to put into the sections themselves. \subsubsection{The \TeX\ Part of the Section} As already mentioned, each section will usually consist of \TeX\ text followed by \CEE/ code, thus we have a (more or less) informal description in natural language and an unambiguous, formal \CEE/ equivalent immediately following. Most people know what to put in the code part since they have been writing \CEE/ programs for years, the problem is rather: what shall the \TeX\ text contain? When writing the \TeX\ text of a section, one always has to keep the intended reader and his supposed background in mind. Of course, he must at least be familiar with \CEE/ and we should also assume that he knows about the basic data structures like lists, stacks, binary trees or hash tables. In addition, the user is supposed to have read the specification and user documentation of the program he wants to analyze and in most cases he should have seen the program running. Since the new \mCWEB\ system now supports interface documentation, we will also be able to refer to it. People who are used to insert documentation with \CEE/ comments only, tend to use rather scarce formulations like \par\medskip\begingroup\obeylines\tt /* \ * Draw an icon in its window. \ */ void draw\UL icon(struct Icon *icon) $\{$ \dots $\}$ \endgroup\par\medskip\noindent Literate programs usually should be more verbose. Note, that writing a whole phrase does not take much longer, but makes the documentation more readable. The program is read much more often than it is written (by its own author, every time he looks at it). The comment used above is more or less an optical separator and contains no additional information to the function name at all. \noindent Each \TeX\ text can (and usually should) contain the following parts: \begin{enumerate} \item How is the following code part related to the previous ones and {\em why} is it here (interrelationship and raison d'\^etre). \item {\em What} is it supposed to do (relation to the program specification). \item {\em How} does it achieve that (implementation). Describe algorithmic details that are not obvious. \item In case of a function: Meaning of {\em parameters} and {\em return values}; in case of a datatype structure: Description of the individual fields of the structure. This will be covered by so called autodoc sections in the new \mCWEB\ system (see Chapter~\ref{chautodoc}). \end{enumerate}\noindent While most people find it natural to describe {\em how} the following code works (first we do this then we do that)---something that could be recovered from the \CEE/ code with some additional effort if the explanation is missing---many forget to say {\em what} the function is supposed to accomplish. While the {\em why} and {\em what} part must have been written before one tackles the \CEE/ code following, the {\em how} part can also be added after the code is written, in case the algorithm decision was not too complicated and was made while implementing the code. Not all section will require a {\em why} part, but sometimes, one should give a short explanation about the general purpose of the following definitions. {\em Why} parts are generally recommended in the first \TeX\ texts after a starred section. If there are no {\em why} parts at all, readers not familiar with the program will ask themselves {\em why} the programmer defines a function or data structure they don't know what it is good for. This is especially the case if a bottom-up approach was used where many code parts are defined and nobody can estimate what they will be good for (sometimes, when the program is under development, not even the authors). Don't confuse the reader by defining things that seem to be superfluous. As for the {\em what} part, one will have to search for good excuses if one want to omit it. Although often neglected, it is the essential part of the documentation, even more important than the {\em how} part. One should be able to read the \TeX\ description of the section and know what it {\em should} do. The reader should always know what part of the program specification we are going to implement. In addition, this often helps finding errors before they even occur in testing. This is an interesting fact, because it automatically leads to less error-prone programs. How comes? If the program specification and the implementation are at the same place, it is much easier to realize that there is a difference between what one {\em intends} to do and what one is {\em actually doing}. It is more likely to find these differences if it has been written down because writing down the thoughts often helps to clarify your thoughts. This is like explaining a problem to a colleague (who might not know anything about the problem at all and therefore is absolutely unable to find the bug) often helps to find the error because one had to explain his intentions in detail and had to speak out what he wanted to do, realizing in the same moment that there is a discrepancy between the specification and the implementation or that the specification is wrong or incomplete. \subsubsection{The \CEE/ Part of the Section} Each section in a \.{CWEB} program should have a reasonable size, which means that they should fit on a single page. If they don't fit, there can be two reasons: either the \TeX\ text that describes the section is too long (in which case you have given an exhaustive explanation, good!) or probably the code part of the section is too long and one should investigate the function searching for possibilities to further partition the section. \noindent Good candidates are: \begin{itemize} \item Error handling lines and code treating special cases: These parts tend to distract the reader (and the writer) from the \lq real problem\rq, although they are absolutely necessary. The function itself should concentrate on the general outline of its algorithm, don't overload it with details. Another reason why they should always be placed in named sections is, that otherwise programmers intuitively tend to neglect them, because they don't like to see that there are more lines treating special cases than there are code lines for the \lq usual\rq\ case. If the former are put in a named section of their own, the purpose of this named section is, say, \named<45:Check if {\it r} is a valid argument, {\bf return} if not> and that's what the whole section will be about. The programmer will automatically focus on the new purpose of this section. \item Multi-way instructions like {\bf switch}-{\bf case} or multiple {\bf if}-{\bf else} constructs: Here, each case usually requires special treatment that should be described separately. A named section allows to put extra \TeX\ text for each case, thus documenting it in more detail. \item Independent subjobs: Some functions do a couple of jobs one after the other. If they are relatively independent from each other and can be described by an expressive named section, why not putting them into one? Sometimes, these subjobs can be easily recognized because most \CEE/ programmers separate them with empty lines. Of course, not every empty line justifies a named section of its own. \end{itemize} %%%%%%%%%%%%%%%%% \subsection{Naming Conventions} Literate programming does not only mean shifting code sections around and using \TeX\ to get a nice looking printable document, but also carefully choosing variable names and section names. Knuth suggests that one has a thesaurus at hand, choosing names that express the meaning of a variable best. Chapter~9 of~\cite{Knuth:LP92} and~\cite{Knuth:CJ-27-2-97} give some stylistic suggestions. Not everybody will write literate programs in the same way, but if you are new to the topic, some hints might be helpful. It is always a good idea to use verbs for functions and nouns for variables. For functions and named sections which really perform an action, use imperative style, for named sections that collect various parts one can use descriptors. For example, one should write \named<63:Draw icon image> rather than \named<63:Draws the icon image>, but one still would write \named<56:Drawing Functions> for a collection of functions. If sections can have an effect on the control flow, this should be stated in the section name. Typical examples would be \named<23:Check if inside range, {\bf return} if not> or \named<46:Store {\it s\/} in the hash table, {\bf goto \it done\/} if already there>. \section{Literate Programming and Reverse Engineering} The fact the literate programming leads to well documented software might imply that it would be a good method for reverse engineering, i.e.~trying to document an existing \CEE/ program of which usually no or at least not very much documentation exists. Usually, even the requirements are poorly understood and nobody really knows what the program really does and what not. Everyone who has tried to squeeze an existing ordinary \CEE/ program into the style of a literate program will agree, that this is really a hard job. \CEE/ programs tend to have a completely different structure and one has to do a lot of copying and restructuring, even if one perfectly knows what the program does. If one tries to do that with a program not really understood, he will find himself unable to give meaningful explanations because he simply doesn't know what's going on. One will only put in comments here and there, every time one found out something new, but one will avoid restructuring the program. One could also do this in ordinary \CEE/. For this reason, I cannot recommend literate programming as a method for reverse engineering. If the author does not explain all the decisions he made while writing the program, this information is probably lost forever. Even literate programs under development need restructuring from time to time. Sometimes, I spend half of a day only on rearranging the code because I realize some parts of the program aren't where they best should be. However, I found out that such a restructuring always paid off. Afterwards, the code was much clearer and seemed to have a \lq logical\rq\ order and I felt more comfortable when I added new parts to it, knowing that the existing code was \lq clean\rq. \section{Inadequacy of the {\tt CWEB} System for Teams} Although the \CWEB\ system also makes sense for smaller programs, its strong points lie in the support of large scale software projects, where accurate documentation and careful design are basic requirements for success. But nowadays, most large projects are developed by software teams rather than one single programmer. This means, that the program will necessarily consist of more than one \.{WEB} source file, since one file can only be edited by one person at a time. Unfortunately, \CWEB\ does not support multiple source files at the moment. It requires one single source document, which makes it difficult to use for projects where more than one person is involved. Even for projects which are developed by a single person it may be desirable to split the source file up into more files. There is a historical reason for this inconvenience. \.{CWEB} is a descendant of Knuth's \.{WEB} which was intended for PASCAL. PASCAL, unlike \CEE/, does not support linking of multiple files and did indeed expect one single input file. However, adapting \.{WEB} to a new language like \CEE/ does not only mean changing the grammar for pretty-printing, but one also has to consider the language specific properties. One of the features of \CEE/ are header files, which are used to insert shared data into different translation units. In release~3 of the \.{CWEB} system of structured documentation, the new \.{@(} command was introduced, which allows writing some sections into a file other than the \CEE/ output file. With this option, it is possible to create \CEE/ header files. \medskip\begingroup\tt @ @(foo.h@>=\par \hskip1em void bar(int);\par \endgroup\medskip {\bf 13.}\quad\named<13:{\tt foo.h}>=\par \hskip1em{\bf void \it bar$\,(\hbox{\bf int})$};\par\medskip\noindent outputs the code of this section to the file \.{foo.h}. This header file can then be included with \hbox{\bf\#include \.{"{}foo.h"{}}}, but if we are using \.{make}, the header file is rewritten every time we call \.{CTANGLE} thus causing a retranslation of the whole project and making \.{make} useless. Knuth's demonstrates how he uses \.{@(} in \cite{Knuth:SGB94}. Still, the index covers one single \.{CWEB} file only and is unaware of all identifiers in other files. Anyway, since we want to define our data structures and functions where they best fit and not where the compiler wants them to be, the \mCWEB\ system described below has a couple of export and import commands which make the manual creation of header files for information interchange between translation units obsolete. Furthermore, software teams usually break their projects into smaller, independent units to be assigned to individual programmers. To coordinate the work between the individual members of the team, an interface specification which only covers how the different units interact with each other is made. This means that each unit is regarded as a black box with a well-defined interface. \.{mCWEB} is able to combine the interface documentation in the web code. \chapter{The {\tt mCWEB} System} During many years of experience with the \CWEB\ system, I found that everything was fine as long as one didn't want to cut his programs into different translation units. Several programmers complained about \CWEB's inability to handle multiple input files and still maintaining a complete index about all identifiers known in each part of the project. In addition, I found it annoying to put a prototype for every function in a single \named<3:Predeclaration of procedures> section right before the function only to make the compiler happy. I realized that there should be some kind of export and import commands that make prototypes and forward declarations of variables obsolete. Since it seems that large projects nowadays consist of a couple of (dynamic) link libraries and sometimes even more than one executable, the interrelations of the individual files that make up a project can be complex and should be covered fully by the tool. This should include managing dependencies between the various files. \section{The Book Concept}\label{chbook} Conforming to the idea of creating works of literature, I decided to regard each executable or library as a {\em book} consisting of several chapters. Each chapter is a single file that can be edited independently from all other files. Thus, an old-style \CWEB\ source file would only be a chapter of a \mCWEB\ book. Chapters are meant to contain functions that have a high cohesion (e.g.~they work on the same data structure). Book files usually have the file extension \.{.prg}. For instance, an example book \.{foobar.prg} could look like the following: \par\medskip\begingroup\obeylines\tt \BS def\BS title$\{$The FooBar Program$\}$ \BS def\BS author$\{$A. U. Thor$\}$ \BS showtitle \BS noindent This is an example book that does not really exist. \BS vfill @c foo @c bar @m \# \# Here is the makefile \# foobar : \$(CHAPTERS) \hskip1cm \$(CC) -o foobar \$(CHAPTERS) foo.o : \$(FOO) bar.o : \$(BAR) \endgroup\par\medskip \noindent As we can see, the book imports two chapters \.{foo.w} and \.{bar.w}. This is done by $$\.{@c \angled{\it chapter name} \angled{\it change file name} \angled{\it output file name}}$$ which is quite similar to a call of \.{CTANGLE}. \noindent Everything following the $$\.{@m }[\mangled{\it makefile name}]$$ command goes to the makefile. We will talk about makefiles in more detail in Chapter~\ref{chdep}. \.{mCWEAVE} processes all chapters given by the \.{@c} commands and copies all other lines of the book file up to the \.{@m} command or the end of file to the output file \.{foobar.tex}. This means that one can define \TeX\ macros in the limbo part of the book that will be available in all chapters of the book. In particular, one can write an introduction to the book after the \.{\\showtitle} command like it is indicated in the above example. This introduction should contain information about what the program the book contains does. In addition, if it is necessary to have read other books in order to understand this one, please say so in the introduction so that reader can find out which book to start reading with if a project consists of multiple books. \section{The Chapter Files} Chapter files are ordinary \.{CWEB} files and therefore end in \.{.w}. Each chapter file usually starts with the \TeX\ macro $$\.{\\chapter {\it name-of-chapter}.}$$ giving the name of the chapter (terminated by a \lq\.{.}\rq) which will also be used in the header. Unlike in former \.{CWEB} files, the first section should {\em not} be a starred section because the \.{\\chapter} macro already puts a chapter title line and adjusts the header. Use an ordinary \.{@\SP} instead to introduce the first section. In addition to some new commands, there are other differences between how \mCWEB\ processes the input file and how \CWEB\ did. If, in \.{CWEB}, one wrote something like this: \medskip\begingroup\obeylines\tt @ Let us now introduce a new type called |Node| \dots @c typedef struct $\{$ \dots $\}$ Node; \endgroup\par\medskip \noindent The first reference to {\bf Node} will be printed in italics because \.{CWEAVE} only knows that Node is a type from the point on where it was defined. However, in \mCWEB, this will be printed in boldface, like all type names. An even more important improvement is that \mCWEB\ now parses all header files that are included into the program by means of the preprocessor instruction {\bf\#include}. This means that all types defined in these files are known and typeset correctly. This is especially important if one is writing X window programs where there will be a lot of predefined data types. In order to make this possible, one has to define the environment variable \.{INCLUDE} to contain all directories that have to be searched for include files, each path separated by colons. Unlike \CWEB, \mCWEB\ now explicitly distinguishes between \CEE/ and \CPLUSPLUS/ programs. Although \CPLUSPLUS/ is said to be a superset of \CEE/, there is still a difference: \CPLUSPLUS/ treats structure labels as data types while \CEE/ does not. For this reason, \.{mCWEAVE} now has the \lq\.{++}\rq\ command line switch for \CPLUSPLUS/ programs. If \.{++} is not given, structure labels are printed in italics and are no type keywords. This makes it possible to write things like \hbox{\bf struct \it List List\/\rm;} which is absolutely legal in \CEE/ but not in \CPLUSPLUS/. A file extension of \.{.wpp} or \.{.wxx} automatically switches on \CPLUSPLUS/ mode too. \section{Translating a Book} To translate a book to a \TeX\ file, just call \.{mCWEAVE} as one did call \.{CWEAVE} in order to translate old-style \.{CWEB} files. Files with the recommended book file extension \.{.prg} are automatically treated as book files. If one has chosen another file extension, one must explicitly set the \lq\.{+m}\rq\ flag or \mCWEB\ will be in \CWEB\ compatibility mode. \noindent \.{mCTANGLE} and \.{mCWEAVE} take the following arguments $$\.{mctangle}\ [\mangled{\it options}]\ \mangled{\it webfile}\ \bigl[(\mangled{\it changefile}\vert\.{-})\ [\mangled{\it outfile}]\bigr]$$ $$\.{mcweave}\ [\mangled{\it options}]\ \mangled{\it webfile}\ \bigl[(\mangled{\it changefile}\vert\.{-})\ [\mangled{\it outfile}]\bigr]$$ \noindent where {\it webfile} is either a book or an old-style \.{CWEB} source file, {\it change file} is the change file to use, and {\it output file} is the name of the output file which defaults to {\it webfile}. If one wants to give an output file but omit the change file, use \lq\.{-}\rq\ for the change file name. Table~\ref{tabflags} lists all command line options for \mCWEB. \.{mCTANGLE} will only translate those chapters that have changed. This means that chapters that have not been modified will not create new \CEE/ files, so that the compiler won't have to retranslate them. \.{mCWEAVE} always weaves all chapters of the book. Weaving now takes a little bit longer than with \.{CWEAVE}, depending on how many include files have to be parsed. For an input file \.{foobar.prg}, \.{mCWEAVE} outputs a file \.{foobar.tex} containing the implementation (as \.{CWEB} did) and---if there is an interface documentation in the book---a file \.{autodoc.tex}. Both files are plain\TeX\ files and can be passed on to \TeX\ to get printable DVI files. \begin{description} \item[Important Note:] Since \.{mCWEAVE} reads some of \.{mCTANGLE}'s output files (that is the shared and export files, see below) to make the index, one must make sure that all books a particular book is related to have been tangled before one calls weave. In particular, each book must be tangled before it may be woven. \end{description} \def\multilinecol#1{ \begingroup\hsize=2.5in\raggedright\baselineskip10pt \hbox{\vtop{\noindent#1\strut}}\endgroup} \def\onoff#1{\hbox to 0pt{#1\hss}\phantom{Off}} \begin{table} \begin{tabular}{|c|c|l|c|} \hline Flag&For&Description&Default\\\hline \.{+}&\.{mCWEAVE}&\multilinecol{Switch \CPLUSPLUS/ mode on.}&\onoff{Off${}^{\dag}$}\\ \.{b}&\.{CWEB}&\multilinecol{Print a banner line at the beginning of execution.}&\onoff{On}\\ \.{f}&\.{CWEAVE}&\multilinecol{Force line breaks after each \CEE/ statement.}&\onoff{On}\\ \.{h}&\.{CWEB}&\multilinecol{Print a happy message at the conclusion of a successful run.}&\onoff{On}\\ \.{i}&\.{mCWEAVE}&\multilinecol{Show names of all {\bf\#include}d header files.}&\onoff{Off}\\ \.{k}&\.{mCTANGLE}&\multilinecol{Make Kernighan \& Richtie \CEE/ prototypes.}&\onoff{Off}\\ \.{l}&\.{mCWEAVE}&\multilinecol{The +l{\it prefix} causes \TeX{} to use {\it prefix\/\tt mcwebmac.tex} instead of {\tt mcwebmac.tex} which makes it easy to use localized versions. Use \.{+ld} to include the german macro file, or \.{+lf} for the french one.}&N/A\\ \.{m}&\.{mCWEB}&\multilinecol{Input file is a book (\mCWEB\ mode).}&\onoff{Off${}^{\ddag}$}\\ \.{p}&\.{CWEB}&\multilinecol{Give progress reports as the program runs.}&\onoff{On}\\ \.{s}&\.{CWEB}&\multilinecol{Show statistics about memory usage after the program runs to completion.}&\onoff{Off}\\ \.{x}&\.{CWEAVE}&\multilinecol{Make indexes and a table of contents in the \TeX\ output of \.{CWEAVE}.}&\onoff{On}\\ \hline \noalign{\tiny\phantom{vskip}} \noalign{\footnotesize${}^{\dag}$On, if (chapter) file extension is {\tt.wpp} or {\tt.wxx}} \noalign{ \footnotesize${}^{\ddag}$On, if file extension is {\tt.prg}} \end{tabular} \caption{Options for {\tt mCWEB}}\label{tabflags} \end{table} \section{Import and Export} As mentioned above, \mCWEB\ now supports export and import commands which greatly simplify the maintenance of the relationship between the individual source files that make up a project. What we want to do is to automatically generate declarations for all parts of a chapter we want to make visible to others. For example, if one has a function {\it func} in chapter~A one wants to be accessible from other chapters of the same book, one simply writes: \par\medskip\begingroup\obeylines \bf shared int \it func$($\bf int \it x$)$ $\{$ \dots $\}$ \endgroup\par\medskip\noindent In chapter~B of the same book, one can write \par\medskip\begingroup\obeylines \bf\#import chapter \tt"{}A"{} \endgroup\par\medskip\noindent and chapter~B will automatically have a prototype of chapter A's function {\it func} thus making it able to call it (as well as all other {\bf shared} functions defined in chapter~A). This does not only work for functions but for all \CEE/ definitions like datatypes or variables. \subsection{Export Commands}\label{chexport} Let's have a look in more detail what export commands are available. For the sake of simplicity, we will only demonstrate the use of the export commands with \CEE/ functions although they work fine for other \CEE/ constructs as well. There are three export levels. There first level is to make a function visible in the whole chapter where it is defined, which means that---unlike in ordinary \CEE/---the function can be called before it is defined. This makes it easy to rearrange sections without caring about their interrelationships. In order to make a function visible in its own chapter, precede its definition by \.{@\_global} as demonstrated in the following example: \par\medskip\begingroup\obeylines\tt @\_global void func(s) char *s; $\{$ \dots $\}$ \endgroup\par\medskip\noindent it is generally a good idea to precede every \CEE/ function by \.{@\_global} which saves the work of creating all function prototypes by hand and putting them into annoying \angled{Predeclaration of procedures} sections. \mCWEB\ now creates a prototype for {\it func} and puts it at the place in the \CEE/ code where \.{@h} was given. If no \.{@h} was found, it is inserted at the beginning of the \CEE/ code. One usually will set \.{@h} right after including the required system header files. The next export level makes the function callable by another chapter of the same book. The name of this export command is \.{@\_shared}, where \.{@\_shared} implies \.{@\_global} (i.e.~all shared functions are automatically global). Last but not least, one can export functions to another book. This can be done using \.{@\_export} in front of the \CEE/ definition. Exported functions are {\em not} automatically global nor shared so one might want to combine two export commands to make a function, say, \lq exported and shared\rq. Exporting to other books is often necessary if a project is made of more than one book. This is the case in Client-/Server Applications and projects that make use of libraries. Since libraries are books too, they are supposed to \.{@\_export} all their interface functions to make them visible for users of the library. Export commands make it possible to define global variables inside a function body: \par\medskip\begingroup\obeylines\tt void func() $\{$ \hskip1em\dots \hskip1em @\UL global int this\UL is\UL global; \hskip1em\dots $\}$ \endgroup\par\medskip The \mCWEB\ system automatically creates the required header files (called shared and export files) for each chapter which consist of declarations for the exported stuff. See Appendix~\ref{appfiles} if you are interested what files really are created and what they are good for. \subsubsection{Exporting Definitions} If one wants to export macros defined with \.{@d}, one can do it like that: $$\.{@d @\_export Number(x) sizeof((x)/sizeof(*(x)))}$$ \noindent which means that the export commands must immediately follow the \.{@d}. Note that \.{@\_global} does not make much sense since all \.{@d} are per definitionem global. \subsection{Import Commands}\label{chimport} Since we now know how to export data, we will take a look at the import commands. Again, we can choose among different import commands. First of all, we will want to import all \.{@\_shared} functions of another chapter of the same book. This is done using % $$\.{@\_import chapter "{}\angled{\it chaptername}"{}}$$ % \noindent In order to import \.{@\_export}ed functions from various chapters of another book, we use the command: \par\bigskip\noindent \.{@\UL from $(\.{program}\vert\.{library})$ "{}\angled{\it bookname}"{}} \par\nobreak {\tt import $[$transitively$]$ "{}\angled{\it chaptername}"{}$\,\{\hbox{,"{}\angled{\it chaptername}"{}}\}$} \par\bigskip \noindent Here we distinguish between books that make up programs (or other types of books that don't get linked) and link libraries. Link libraries should be imported using the \.{library} keyword while other books are imported with \.{@\_from program\dots}. \noindent If one wants to import {\em all} chapters of another book, one can use: % $$\.{@\_import $[\.{transitively}]$ $(\.{program}\vert\.{library})$ "{}\angled{\it bookname}"{}}$$ % \noindent The optional keyword {\tt transitively} determines if these imported chapters are passed on transitively to whatever imports this chapter. If, for example, chapter~B transitively imports chapter~A and chapter~C in turn imports chapter~B, then chapter~C automatically imports chapter~A, too. However, if {\tt transitively} was omitted, chapter~A would not automatically be imported into chapter~C. The dependencies of all books are stored in so called {\em dependency files} which lie in the same directory as export files. \subsection{The Environment Variable {\tt DEPDIR}} In order to have a common base point from which references to other books are searched, the environment variable \.{DEPDIR} must be set to a directory in which a subdirectory for each book will automatically be created at the first call of \.{mCTANGLE}. For this reason, books must have a unique name. This subdirectory in \.{DEPDIR} will contain all export files so that they can be found again by other books. If one decides to import chapter \.{foo} of book \.{foobar}, \.{mCTANGLE} will create a {\bf\#include \.{"{}foobar/foo.exp"{}}} statement. For this reason, the \.{DEPDIR} directory must be part of the compiler's default include search path. For \UNIX/ compilers this is usually done with the \.{-I\$(DEPDIR)} command line option. If the book is a link library that must be found by the linker, one can put the final \.{.a} file in the \.{DEPDIR} variable and add it to the default library search path using the \.{-L\$(DEPDIR)} command line option. In addition, \.{mCWEAVE} also needs this environment variable because it reads the export files in order to find out all references to foreign books and to learn about the new datatypes they define. So, if one forgets to define this environment variable, both---\.{mCTANGLE} and \.{mCWEAVE}---will abort with a fatal error. \subsection{The Improved Index} Since a \.{mCWEB} book consists of several chapters and can be even related to other books, we have to print a more complete index than \.{CWEB} did. \.{mCWEB} outputs an index at the end of each chapter and a final index at the end of the book. Note, that one must have run \.{mCTANGLE} on all books that are in the index or one will have an incomplete or wrong index. The reason for this is that \.{mCWEAVE} reads the export and shared files \.{mCTANGLE} creates to find out what is defined in the other books/chapters. \subsubsection{The Chapter Index} At the end of each chapter one gets an index containing all identifiers defined in this chapter or imported from other chapters. Let's take a look at an excerpt of a chapter index: \par\medskip\begingroup\obeylines {\it AddHead\/}:\kern1em$\underline{1}{}^{2}$, 19. {\it AddIcon\/}:\kern1em$\underline{19}{}^{\dag}$, 24, 30, 39. \dots {\it compare\_icons\/}:\kern1em 20, $\underline{21}$. \endgroup\par\medskip\noindent In this index, {\it compare\_icons} is a function that is defined in the current chapter and not exported. {\it AddIcon} is also defined in this chapter, but the $\dag$ sign indicates, that this identifier is shared between chapters within the book. Identifiers exported to other books are marked with a $\ddag$ sign. Each imported identifier has a superscript number telling where it comes from. In our example, {\it AddHead} was defined in section~1 of another part of the project and is used in section~19 of the chapter the index belongs to. \noindent At the end of the index we have a description of the superscript indices like: \par\medskip\begingroup\obeylines ${}^{\dag}$\kern1em shared within book\bigskip {\bf Referenced books:}\smallskip\nobreak ${}^{1}$\kern1em {\tt lists}, Chapter 1 ${}^{2}$\kern1em {\tt lists}, Chapter 2 \dots \endgroup\par\medskip\noindent Thus, {\it AddHead} is defined in book \.{lists}, Chapter~2. \subsubsection{The Final Index} The final index consists of three parts. First come the shared identifiers, which means every\-thing that is exchanged between the chapters of the book, followed by the exported identifiers (all names exported to other books). Last but not least comes the list of all identifiers imported from other books into the current one. Like in the chapter index, the entries in the final index have superscripts to indicate where they really come from. \section{Dependencies and Makefile}\label{chdep} I presume that every software team uses \.{make} or a similar tool which helps to automatically keep a project up-to-date by only retranslating the files that have changed. This requires a \.{makefile} to give all the dependencies of the files. These dependencies are not trivial if one has a large program consisting of several libraries where individual parts of the program {\bf\#include} many header files, some of them resulting from transitive dependencies. Due to import and export commands, \.{mCTANGLE} knows about that interrelationship of its chapter files and can help the programmer creating the dependencies for the \.{makefile}. As we have seen in Chapter~\ref{chbook}, the book file can contain a \.{@m} command followed by an optional name of the makefile. All the lines following this command until EOF are copied to this makefile without change. When \.{mCTANGLE} writes the makefile, it puts some useful constants at the very beginning of the file. For each chapter, there is a makefile constant with the name of the chapter which contains all files this chapter depends on. For a chapter \.{foo.w} that contains an import command {\bf\#import chapter} \.{"{}bar"{}} and a {\bf\#from library \.{"{}mylib"{}} import \.{"{}libchapter"{}}}, this could look like the following: $$\.{FOO=foo.c bar.shr \angled{\it DEPDIR}/mylib/libchapter.exp}$$ if there are no transitive dependencies. One can then use $$\.{foo.o : \$(FOO)}$$ to inform \.{make} about the dependencies for chapter \.{foo.w} without caring about the individual files. Linking is simplified by the \.{CHAPTERS} constant which contains all object files that emerge from the book. $$\.{foobar : \$(CHAPTERS)}$$ can be used to give the dependencies for the final executable, adding libraries after the \.{CHAPTERS} constant as needed. For a book \.{foobar.prg} consisting of two chapters named \.{foo.w} and \.{bar.w}, \.{mCTANGLE} defines \.{CHAPTERS= foo.o bar.o}. The last makefile constant defined by \.{mCTANGLE} is \.{LIBRARIES} which contains all associated link libraries the book depends on. If a book imports, say, the libraries \.{xwblib.prg} and \.{lists.prg}, there will be the following constant in the makefile: $$\.{LIBRARIES= \$(LIBPREFIX)lists \$(LIBPREFIX)xwblib}$$ where \.{\$LIBPREFIX} is a user defined constant that gets appended in front of each library name. This makes it possible to write: \par\medskip\begingroup\obeylines\tt \# use -l in front of each library name in \$(LIBRARIES) LIBPREFIX=-l \# system libraries LIBS=-lXm -lXt -lX11 foobar : \$(CHAPTERS) \$(DEPDIR)/libxwb.a \$(DEPDIR)/liblists.a \hskip1cm cc -o foobar -L\$(DEPDIR) \$(CHAPTERS) \$(LIBRARIES) \$(LIBS) \endgroup\par\medskip\noindent assuming that both libraries lie in the \.{DEPDIR} directory. \subsection{Using two Makefiles} Since the makefile is created by \.{mCTANGLE} and one might want to use a makefile for the tangling process too, one will probably create two makefiles. Here is a recommended way to do this. Give the makefile that gets created by \.{mCTANGLE} another name by stating it after the \.{@m} command (e.g.~\.{@m makefile.unix}). The standard \.{Makefile} will then look like this: \par\medskip\begingroup\obeylines\tt all : tangle translate tangle : \hskip1cm mctangle {\it book} translate : \hskip1cm make -f makefile.unix weave : tangle \hskip1cm mcweave {\it book} \hskip1cm tex {\it book} \hskip1cm $[\.{tex autodoc}]$ \endgroup\par\medskip\noindent which makes it possible to say \.{make} if one wants to translate the book and it will automatically tangle first and translate afterwards using the \.{makefile} created by the tangling process. On the other hand, one can say \.{make weave} to run \.{mCWEAVE} and \TeX\ on the book. This will also cause \.{mCTANGLE} to translate the program if needed which ensures that one always gets the right references. If one has a project consisting of several books, create an overall makefile looking like this: \par\medskip\begingroup\obeylines\tt all : tangle translate tangle : \hskip1cm make -C {\it firstbook} tangle \hskip1cm make -C {\it secondbook} tangle \dots translate : \hskip1cm make -C {\it firstbook} translate \hskip1cm make -C {\it secondbook} translate \dots \endgroup\par\medskip\noindent thus ensuring that all books get tangled before the first one gets compiled. \section{Inserting Example Code}\label{chexample} Sometimes, one might want to give an example to illustrate the use of a function or datatype. \CWEB\ provides the \.{|\dots|} instruction in \TeX\ text to set identifiers like \CEE/ text, but it didn't work for \CEE/ text that contains multiple lines. For this reason, \mCWEB\ now knows the \.{@e} command which switches example mode on and off. One can use \.{@e} in the \TeX\ text part of a section. Example code may only contain ordinary \CEE/ code, no named sections. In ordinary books, the opening \.{@e} is usually preceded by \.{\\bex} (begin example) which makes a small horizontal indentation and vertical skip and switches to a smaller font so that the user can see that the following code is not part of the program but only an example code. The closing \.{@e} should then be followed by \.{\\eex} (end example) to switch back to the previous settings. \medskip\begingroup\obeylines\tt @\SP Here is an example that demonstrates how to access all nodes of a list: \BS bex@e \ \ struct List l; \ \ struct Node *n; \ \ NewList(\&l); \ \ @t\BS dots@>@; \ \ for(n=FirstNode(\&l);NextNode(n);n=NextNode(n)) \ \ @t\BS dots@> @e\BS eex \endgroup\par\medskip\noindent results in \par\medskip\noindent {\bf6.}\quad Here is an example that demonstrates how to access all nodes of a list: \par\begingroup\medskip\advance\leftskip by\parindent\smallfont\adocmode \B\&{struct} \\{List} \|l;\6 \&{struct} \\{Node} ${}{*}\|n;{}$\7 ${}\\{NewList}({\AND}\|l);{}$\6 \hbox{\dots}\6 \&{for} ${}(\|n\K\\{FirstNode}({\AND}\|l);{}$ \\{NextNode}(\|n); ${}\|n\K% \\{NextNode}(\|n)){}$\1\5 \hbox{\dots}\2 \par\medskip\endgroup \noindent If one doesn't want to have the example printed differently from ordinary code (e.g.~in autodocs, see below), one can simply use \.{\\smallskip} instead of \.{\\bex} and \.{\\eex}. \section{Interface Documentation}\label{chautodoc} In software teams, the individual members are not interested in the implementation details of those parts, which have been written by other members of the group. They rather would like to see each part reduced to an interface documentation, so they can see another user's chapter from outside without having to read the whole document. Unfortunately, the \CWEB\ system did not support interface documentation. Therefore, a so called {\em autodoc} section has been added to \mCWEB. Autodoc sections may only appear in the \TeX\ text of a section and are exported to a separate book called \.{autodoc.tex}. Each autodoc entry has a name and belongs to an {\em autodoc class}. For each class {\it classname}, \.{mCWEAVE} creates a file \.{{\it classname\/}.adc} with all autodocs sorted by their name. Autodoc classes can be used to group the same kind of things. For example, for simple books, one may create a class \.{Functions} and a class \.{Datatypes}, thus having a chapter in the reference manual which describes all functions and one for the various datatypes. In a more complex project one might refine this classification. The idea of putting the interface documentation in the same file as the source file is obvious. If the interface is documented at the same place where the code is, it is easy to keep both up-to-date if changes are necessary. One doesn't have to search the corresponding places in two separate files. \subsection{The Autodoc Command @a} Interface documentation in \mCWEB{} is done using the \.{@a} command. It may only be used in the \TeX\ text description of a section and has the following syntax: $$\.{@a}\{\hbox{\angled{\it class}}\}\,\{\hbox{\angled{\it name}}\}\,\{\hbox{\angled{\it description}}\}$$ where all $\{\,\}$ denote real braces, not optional arguments. The name of the class is also the name of the \TeX\ file that will be created. All autodocs are grouped by their class and within their class sorted by their names. Note, that \angled{name} is a \TeX\ text and no \CEE/ code, and must please follow \TeX\ conventions (i.e.~all underscores and other special characters must be protected by a backslash). The final document is called \.{autodoc.tex} and contains all autodoc classes in the order in which they appeared in the \mCWEB\ source. Unlike named sections which can only be used in the chapter where they have been defined, the scope of autodocs is the whole book, so that one can put autodocs of different chapters in the same class. There is one special name each autodoc class can have. If one uses \.{*} as the autodoc name, the description is not a real autodoc, but \TeX\ text that is inserted at the very beginning of the autodoc class file. This can be used to define the title of the autodoc class (which defaults to the class name): $$\.{@a}\{\hbox{func}\}\,\{\hbox{*}\}\,\{\.{\BS def\BS chapname}\{\hbox{Functions}\}\}$$ If one uses an empty name, one can write an introduction that gets inserted right after the title. All other names are treated as ordinary autodoc entries that are sorted and printed in a special way. Similarly, if one omits the autodoc name as well as the class name, one is defining the autodoc book header, i.e.~the \TeX\ text gets inserted right after the \.{\BS input mcwebmac} at the beginning of \.{autodoc.tex}, the book containing all auto\-doc classes. A typical autodoc header could look like the following:\par\medskip \begingroup\obeylines\tt @a$\,\{\,\}\>\{\,\}\>\{$ \BS input epsf\qquad\% for including postscript graphics \BS def\BS title$\{$\angled{\it title of autodoc book}$\}$ \BS def\BS author$\{$\angled{\it your name}$\}$ \BS def\BS topofcontents$\{$\BS showtitle$\}$\quad\% title on same page as toc $\}$ \endgroup\par\medskip\noindent If one doesn't define \.{\\title}, one gets the default title, but the autodoc header should at least contain the command \.{\\showtitle} or the autodoc book will have no title. \subsection{\TeX\ Macros for Autodocs} Inside an autodoc description, one should use the macros provided for setting autodocs. An autodoc usually consists of different parts, like its name, synopsis or function. Let's take a look at a typical autodoc describing a function. \adoc{StealMoney} \adocmode \ \*{\\{StealMoney} -- Steal money from the Federal Reserve Bank. (V77)} \ \par\B$\\{err}\K\\{StealMoney}(\\{userName},\39\\{amount},\39\\{destAccount},\39% \\{falseTrail});{}$\7 \&{int} \\{StealMoney}(\&{char} ${}{*},\39\&{int},\39{}$\&{struct} % \\{AccountSpec} ${}{*},\39{}$\&{struct} \\{Trail} ${}{*}){}$;\par \setsec \ Transfer money from the Federal Reserve Bank into the specified interest-earning checking account. No records of the transaction will be retained. \ \*{\\{userName} -- name to make the transaction under.% Popular favorites % include "{}Bill Clinton"{} and "{}Mohamar Quadaffi"{}.% } \*{\\{amount} -- number of dollars to transfer (in thousands).} \*{\\{destAccount} -- A filled-in \\{AccountSpec} structure detailing the destination account (see datatype \\{AccountSpec}).} \*{\\{falseTrail} -- If the \.{DA\_FALSETRAIL} bit is set in \\{flags} field of \\{destAccount}, a \\{falseTrail} structure must be provided.} \ \*{\\{err} -- zero for success, else an error code is returned (see~Financial Error Codes).} \ Federal regulations prohibit a demonstration of this function. \Do not run on Tuesdays! \ Before V66, this function would occasionally print the address and home phone number of the caller on local police 976 terminals. We are confident that this problem has been resolved. \ \\{CreateAccountSpec}$(\,)$, Security~functions/\\{DestroyEvidence}$(\,)$ \endadoc \noindent There are two different macros for autodocs: $$\.{\\<$\,$\angled{\it part}$\,$>}$$ introduces one of the parts that can be seen above. For example, the first part was created using \.{\\}. The second macro is used every time we start with an identifier that we describe afterwards. This was the case with the Name, Inputs and Result parts above. A $$\.{\\*}\{\hbox{\angled{\it description}}\}$$ makes sure that the first line is less intended than the following which can be seen by looking at {\it destAccount} in the Inputs part. This was written using \.{\\*}$\{$\.{|destAccount| -- A filled-in\dots}$\}$. \subsection{Autodoc Style Guide} We already have seen a typical autodoc for a function, let's describe the various parts in more detail. The autodoc style conforms to the autodoc guide of AT. \begin{description} \item[NAME:] Here, one puts the name of the function followed by a {\em one line} description what it does. Don't forget to enclose the name in \.{|\dots|} since it is a \CEE/ text rather than a \TeX\ text. \item[SYNOPSIS:] The Synopsis has two parts, the \CEE/ calling convention and the ANSI function prototype. The Synopsis part is \CEE/ text that spans over more than one line, so use the \.{@e} command (example code). \medskip\begingroup\obeylines\tt\parskip0pt \BS @e \angled{\CEE/ \it calling convention} \angled{\sc ANSI \CEE/ \it prototype} @e \endgroup\medskip\noindent \item[FUNCTION:] Describe {\em what} the function does in generally accepted English, keep jargon to a minimum, but don't sacrifice clarity and accuracy. \item[INPUTS:] Describe the range and domain of each input parameter. Use the same name token used in the first Synopsis line (so the user can match inputs to the descriptions). The preferred follower is \.{--} (see~example). Don't forget to note the actions taken for $\Lambda$ pointers! Please use the \.{\\*} \TeX\ macro described in the previous section. \par\smallskip\begingroup\obeylines\tt\parskip0pt \BS \hskip1em\BS*$\{$|name| -- \angled{\it description}$\}$ \endgroup \item[RESULT:] Describe the range and domain of the output. Describe which abnormal conditions produce each error output. In case of a {\bf void} function, this part will be missing. \item[EXAMPLE:] In the autodoc shown above, there is no real example, but if one wants to include an example demonstrating how to use the function, use the \.{@e} command to switch example mode on and off (see~Synopsis). Not all functions will need an example how they are called. The example should be short and must be {\em tested}. Write, test, then remove lines if needed to shorten the example. Use \.{@t\\dots@>@;} to indicate removed sections. \item[NOTES:] Notes usually contain helpful hints, warnings, tricks, traps and are optional. \item[BUGS:] If there are any, describe the bug, and how it can be avoided. This is especially useful for libraries where older versions may still be around. List versions, workarounds, etc. \item[SEE ALSO:] If there are other autodocs which help describe the data structures, or are otherwise related to this function, place their names here. Functions in {\em this} class are simply listed, with $(\,)$ to indicate they are a function. Functions from {\em other} classes are preceded by the module name. (See the {\it StealMoney\/\kern.05em}$(\,)$ autodoc for examples). \end{description} \noindent Please use the parts in the order indicated above to provide a consistent look to the reader. Feel free to introduce additional autodoc parts, but each part should have a well known purpose and position. Every autodoc entry should have at least a Name part and a Function part, all functions should also have a Synopsis part. The Inputs and Result part should be present if there are parameters and return values, respectively. Autodocs for datatypes usually have different parts. It is recommended to use at least Name, Definition (like Synopsis) and Description (like Function). \adoc{Node} \adocmode \ \*{\\{Node} -- a node for doubly-linked lists} \ \par\B\&{struct} \\{Node} ${}\{{}$\1\6 \&{struct} \\{Node} ${}{*}\\{ln\_Succ}{}$;\C{ successor in the list }\6 \&{struct} \\{Node} ${}{*}\\{ln\_Pred}{}$;\C{ predecessor in the list }\2\6 ${}\}{}$;\par \setsec \ The \\{Node} should be the first element of each structure that has to be part of a list. It only contains pointers to the successor and predecessor. \endadoc \subsection{Literate Programming and the User Manual} From time to time, one and the same idea arises: not only combining the implementation documentation and code in one file, but also putting the user documentation into the same file. The intention is to keep the user documentation consistent with the program. After people realized that this generally does not work, the idea disappeared until proposed by somebody else a couple of months later. \noindent The user documentation should not be in the same document for the following reasons: \begin{itemize} \item The way one presents a program to a programmer is not necessarily the same way he or she would present it to a user. Users don't care about data structures and the relationship between the various parts, what they want to know is what the program can do and how to work with it. \item In most big companies, user documentation is done by a different department (this explains why it is often so inconsistent, those writing the user documentation often don't really know what the real implementation does). \end{itemize} \noindent In spite of all, one can use autodoc sections to define user interface documentation that is not intended for the end user, but should serve as an information base for the author of the user documentation. This autodoc class will be the base of facts that gets changed when the functionality changes. The author of the user documentation has the possibility of writing a user manual that conforms to that specification. Since he is supposed to have read the program specification too, the autodoc sections will be rather brief. \section{Copy \& Paste}\label{chcopy} Sometimes, one wants to have a part of the code in two different places. Copying and inserting by means of an editor is not only a nuisance but also dangerous because in case one of the copies gets changed, one will have to change all of them (which are sometimes hard to remember). So, every time one needs consistent copies of parts of the code, one can use \.{mCWEAVE}'s mark/copy/paste commands. Suppose, one has a \CEE/ structure and also wants to have it in an autodoc section, something that really happens very often. Then one encloses the part of the code to copy in \.{@\_mark "{}\angled{\it name}"{}} and \.{@\_copy}, thus assigning it the name \angled{\it name}. This code chunk can be inserted anywhere in the \.{mCWEB} source code using \.{@\_paste "{}\angled{\it name}"{}}. \medskip\begingroup\obeylines\tt @ \dots @a$\{$datatypes$\}\,\{$Node$\}\,\{$ \advance\leftskip by1em\BS \BS*$\{$|Node| -- a node for doubly-linked lists$\}$ \smallskip \BS @e @\UL paste "{}Node"{} @e \smallskip \BS The |Node| should be the first element of each structure that has to be part of a list. It only contains pointers to the successor and predecessor. \advance\leftskip by-1em$\}$ @c @\UL export @\UL mark "{}Node"{} struct Node $\{$ \hskip1em struct Node *ln\UL Succ,*ln\UL Pred; $\}$; @\UL copy \endgroup\medskip\noindent The scope of the copy buffer commands is a chapter. Note that one can paste a copy buffer even before defining it. \part{Implementation} \chapter{Common code for {\tt mCTANGLE} and {\tt mCWEAVE}} \setcounter{page}{39} \chapter{The {\tt mCTANGLE} processor} \setcounter{page}{77} \chapter{The {\tt mCWEAVE} processor} \setcounter{page}{189} \newpage\setcounter{page}{380} \part{Appendices} \appendix \chapter{File Survey}\label{appfiles} When tangling and weaving a book, \.{mCWEB} takes a couple of input files, creates some intermediate files and finally outputs the desired output files. Usually, one doesn't have to care about the meanings of the individual file extensions, but if one is curious, here is a complete description of the purpose of the \.{*.scn}, \.{*.dep}, \.{*.shr}, \dots\ files. \section{Input files} Input files are files the programmer creates or which are already available on the system, anyway, \.{mCWEB} only reads them. \begin{description} \item[{\tt.prg}] are {\em book files}, which means that they contain the names of all the chapter files. In addition, they contain the makefile. \item[{\tt.w}] are the {\em chapter files}, which can be compared to \.{CWEB}'s web files. They contain the code and documentation in one book. None of the chapter files of a book may have the same name as the book itself. \item[{\tt.ch}] denote {\em change files}. They simply replace lines in a book or chapter file by modified ones. Change files are usually used to port an application to a slightly different operating system. \item[{\tt.h}] are {\em include files} which usually are system header files. Only \.{mCWEAVE} parses them to find out which types are defined in there. They are always searched relative to the environment variable \.{INCLUDE}. Please don't forget to define this environment variable properly. Several paths can be separated by a colon (as for the \UNIX/ version; on operating system where colons can be part of the file path commas are used). \end{description} \section{Output Files} All files that are generated by \.{mCWEB} and are subsequently processed either by the compiler or by \TeX\ are called output files. One will not have to care about all of them. \subsection{Output files of {\tt mCTANGLE}} Here is the list of all files that are created by tangle and will be translated by the compiler afterwards. \begin{description} \item[Makefile] can take any name specified in the book file and is used to inform the \.{make} utility about the dependencies between all the files of a program and how to translate the individual files. \item[{\tt.c}] files are ordinary \CEE/ files that can be compiled with a \CEE/ compiler. This is usually done by \.{make}. \item[{\tt.shr}] files contain code {\em shared} between different chapters of the same book. They lie in the same directory as the associated \CEE/ files and are automatically included into those files where needed. Note that \.{mCWEAVE} reads the shared file \.{mCTANGLE} outputs (in order to know what the chapter exports to other chapters). Thus, in order to have proper indexes, one must have run \.{mCTANGLE} before \.{mCWEAVE}. \item[{\tt.exp}] are {\em export files} that contain all data exported from a chapter or a book. There is exactly one export file for the book and for each chapter. The export file of the book simply includes ({\bf\#include}) the chapters' export files. Unlike shared files, export files (like \.{mCTANGLE}'s {\tt.dep} files) are always created in the directory \.{\$(DEPDIR)/{\it bookname}} where \.{\$(DEPDIR)} is the environment variable \.{DEPDIR} and {\it bookname} is the name of the book file (without \.{.prg}). This is necessary so that export files of other books can be found via the book name. Like shared files, export files are read by \.{mCWEAVE}, so please take care that all associated books are tangled. \end{description} \subsection{{\tt mCTANGLE}'s Information Files} In addition to the files describe above, \.{mCTANGLE} creates a couple of information files it needs to keep information about dependencies. Please never delete one of these files after tangling, even if they seem to be useless because they are never passed to the compiler. Usually, one doesn't have to worry about any of those files, they are only listed for completeness. \begin{description} \item[{\tt.dep}] files are so called {\em dependency files} that are used to keep track of which chapter depends on which other chapter of which book. They lie in the same directory as export files. The dependency file of a book simply states the chapters the book consists of. The chapters' \.{.dep} files give a list of other chapters and books they directly depend on. \item[{\tt.rep}] files are used to determine if a chapter has to be retranslated. They contain the name of the change file last used, the names of all files included into the chapter using \.{@i} and if the chapter has an export file. \end{description} \subsection{Output files of {\tt mCWEAVE}} \.{mCWEAVE}'s job is to create the \TeX\ file for the implementation and for the autodoc of the book. Both of these files can then be passed on to \TeX. \begin{description} \item[{\tt.tex}] files are \TeX\ files. There is a \TeX\ file for the book, one for each chapter and a file called \.{autodoc.tex} which includes all the \.{.adc} files. Usually, one only has to translate \.{tex {\it bookname}} and \.{tex autodoc} to get the final DVI files. \item[{\tt.adc}] files are {\em autodoc files} and in \TeX\ format. There is one autodoc file for each autodoc class of the book. These files are \.{\\input} into the file \.{autodoc.tex}, so the user is not supposed to call \TeX\ on them directly. \item[{\tt.scn}] files are {\em section files}. They are in \TeX\ format and contain all the named sections of a chapter. There is one section file per chapter. Section files are read by \TeX\ when it translates the chapter. \item[{\tt.idx}] files contain the {\em index} and---like section files---are read by \TeX. There is one index file for the book (containing the final index) and one for each chapter. \end{description} \subsection{{\tt mCWEAVE}'s Intermediate Files} \.{mCWEAVE}'s intermediate files are true intermediate files, which means that one can eventually delete all \.{.xid}, \.{.sid} and \.{iid} files after weaving. In any case, one won't need to fiddle around with them. \begin{description} \item[{\tt.xid}] stands for {\em exported identifiers}. This files lists all identifiers that are exported from a chapter together with the section names where they have been defined. \item[{\tt.sid}] lists all {\em shared identifiers}. \item[{\tt.iid}] states all {\em identifiers imported} into a chapter together with the book, chapter and section number they came from. \end{description} \begin{figure} \centerline{\epsfbox{mcwebman.2}} \caption{Data-flow of {\tt mCWEB}}\label{figmcwebdataflow} \end{figure} \chapter{Summary of all New Commands} Here is a brief summary of all commands that are new in \mCWEB\ in alphabetical order: \begin{description} \item[\.{@\_copy}]\ \par\noindent Is used to copy parts of the code into a copy buffer, from which it can then be pasted to another place in the file. See chapter~\ref{chcopy}. \item[\.{@\_export}] \angled{\CEE/ \it code}\par\noindent Converts the following \CEE/ definition into a declaration and puts it into a an export file which can be included by other books. This is used in order to make parts of the chapter visible to other books. See Chapter~\ref{chexport}. \item[\.{@\_from}] \.{$(\.{program}\vert\.{library})$ \angled{\it book} import $[\.{transitively}]$ \angled{\it chapters}} \par\noindent Imports only some specified chapters of another book. The name of the book as well as the list of chapters must be enclosed in quotes. See Chapter~\ref{chimport}. \item[\.{@\_global}] \angled{\CEE/ \it code}\par\noindent Converts the following \CEE/ definition into a declaration and moves it to the top of the program (or where \.{@h} is given), thus making it known in the whole chapter. This is especially useful for generating prototypes. See Chapter~\ref{chexport}. \item[\.{@\_import}] $[\.{transitively}]\ (\.{chapter}\vert\.{program}\vert\.{library})$ \angled{\it name} \par\noindent Imports declarations previously exported by means of \.{@\_shared} or \.{@\_export}. See Chapter~\ref{chimport} for details. \item[\.{@\_mark}] \angled{copy-buffer} \par\noindent Sets the beginning of the copy buffer {\it copy-buffer} to the pointer where the statement is. This is used in conjunction with \.{@\_copy}. The name of the copy buffer must be enclosed in quotes. See Chapter~\ref{chcopy} \item[\.{@\_paste}] \angled{copy-buffer} \par\noindent Pastes the content of a copy buffer defined with \.{@\_mark} and \.{@\_copy}. \item[\.{@\_shared}] \angled{\CEE/ \it code}\par\noindent Converts the following \CEE/ definition into a declaration and puts it into a shared file which is included before the global stuff and can also be included by other chapters of the same book. This is used in order to make parts of the chapter visible to other chapters. See Chapter~\ref{chexport}. \item[\.{@a}] $\{\mangled{\it class}\}\>\{\mangled{\it name}\}\>\{\mangled{\it description}\}$ \par\noindent Is used to create an autodoc {\it description} (i.e.~an interface documentation) which is sorted by its name within its class. See Chapter~\ref{chautodoc} for details. \item[\.{@c}] $\mangled{\it chapter}\ \bigl[\mangled{\it change}\ [\mangled{\it output}]\bigr]$ \par\noindent Only valid in book files. Includes the given chapter. See~\ref{chbook}. In chapter files, this starts the \CEE/ part of a section like it did in \.{CWEB}. \item[\.{@e}]\ \par\noindent Switches \lq example mode\rq\ on and off. This is used to typeset example code that never gets its way through \.{mCTANGLE}. See Chapter~\ref{chexample} for further information. \item[\.{@m}] $[\mangled{\it makefile}]$ \par\noindent Only valid in book files. Starts the makefile. For any details, see Chapter~\ref{chdep}. \end{description} \bibliography{litprog,tugboat} \end{document}