%******************************************************************************* %* START OF AUTOMATICALLY GENERATED TEX FILE * %******************************************************************************* %* * %* This TeX file was automatically generated by the FunnelWeb preprocessor. * %* You can typeset this file to produce printed documentation by running it * %* through the TeX typesetter using a command such as: * %* tex thisfilename * %* The resultant file thisfilename.dvi can be printed using a command such as: * %* lpr -Pcslw -d thisfilename.dvi * %* * %* FunnelWeb is a preprocessor that allows programmers to weave programs and * %* their documentation together in a single document. The FunnelWeb program * %* analyses such documents producing both program files and typeset * %* documentation such as this TeX file. * %* FunnelWeb was created by Ross Williams. * %* * %* For more information on FunnelWeb look in the following FTP archive: * %* Machine : sirius.itd.adelaide.edu.au [IP=129.127.40.3]. * %* Directory: ~pub/funnelweb/ * %* (or some other appropriately named directory). * %* or email Ross Williams at ross@spam.adelaide.edu.au * %* * %******************************************************************************* %===================== Start of FunnelWeb TeX Definitions ====================== % Version % ------- % This is FunnelWeb TeX Macro Library Version 1.0. % Copyright % --------- % This set of FunnelWeb TeX definitions was written by Ross Williams and was % originally Copyright (C) 1992 Ross N. Williams. However, I, Ross Williams, % hereby forego any claim to Copyright in this set of FunnelWeb TeX definitions % and hereby authorize that the set of TeX definitions pass into the public % domain. -- Ross N. Williams, 3:41pm 07-May-1992, Adelaide, Australia. % Modification % ------------ % Please record all modifications to these TeX definitions here. Unless % otherwise specified, all modified definitions fall in the public domain too. % % Programmers: % RNW Ross N. Williams ross@spam.adelaide.edu.au % % Changes: % 07-May-1992 RNW Prepared this work for public domain release. % % General Comments % ---------------- % This set of TeX definitions exists for two reasons: % % 1. To shorten and neaten the FunnelWeb TeX output. % 2. To allow users to fiddle with the output format in their input files % (by inserting redefining "\def"s) without having to resort to % modifying the FunnelWeb code. % % The user is warned that these definitions may be changed from time to time % (but probably not much). The user should not be too sneaky. In particular, % users wishing to redefine some of these macros should do so in an explicitly % defined section at the top of their input file. This will mean that in the % event of problems, that section can simply be deleted or commented out to % allow the document to at least be typeset in the default format. Users should % limit themselves to redefining these macros in such a section and should % refrain from using the macros throughout their documents. % Environment Parameters % ---------------------- % \tolerance tells TeX how tolerant it should be about making bad line and % page breaks. Here we set it to it's maximum, as % 1) Computer programs are likely to cause lots of bad breaks. % 2) In most cases the user would probably rather get the TeX file through % TeX without any errors than fiddle with spacings for perfection. \tolerance=10000 % I don't like indentation as it makes the page look more busy. Instead, % paragraphs are separated by a little space (see next). \parindent=0pt % In many cases, users will produce documents with long runs of paragraphs. % In order to space out these paragraphs, it is convenient to maintain a % prevailing non-zero \parskip (end-of-paragaph skip). The only trouble is % that the skip becomes a problem in macro definitions which require no skip % and so we have to turn the skip on and off. The following two macros % simplify this process. \def\fwparskipon{\parskip=\medskipamount} \def\fwparskipoff{\parskip=0pt} \fwparskipon % Setting raggedbottom allows TeX to leave a bit of space at the bottom of the % page in order to better vertically align the rest of the page (e.g. skips % won't stretch as much). It also means that headings are less likely to be % isolated at the bottom of the page without any following text. \raggedbottom % Fonts % ----- % Most of the typeset output is set in 10pt roman and 10pt tt font. % The major extra font needs spring from titles and headings. % For portability's sake we use only the following fonts: % cmr10 % cmbx10 % cmtt10 % and some enlargements of them. These fonts are all "standard" fonts % in Plain TeX. See The TeXbook p.350. \font\fwfontnote=cmr7 \font\fwfontnorm=cmr10 \font\fwfontnorma=cmr10 scaled \magstep1 \font\fwfontnormb=cmr10 scaled \magstep2 \font\fwfontbold=cmbx10 \font\fwfontbolda=cmbx10 scaled \magstep1 \font\fwfontboldb=cmbx10 scaled \magstep2 \font\fwfontboldc=cmbx10 scaled \magstep3 \font\fwfontboldd=cmbx10 scaled \magstep4 % Macros for Stylistic Details % ---------------------------- % This section contains all the fiddly little macros for setting the details % of each macro definition. % Macro definitions are sandwiched by calls to these macros which can be used % to sort out the spacing before and after the macro definition. \def\fwbeginmacro{\fwparskipoff\bigskip} \def\fwendmacro{\fwparskipon\par} % These macros deal with the macro name and definition line. \def\fwmacroname#1#2{{\sl #1\/}$\lbrack$#2$\rbrack$} \def\fwfilename#1#2{{\bf #1}$\lbrack$#2$\rbrack$} \def\fwzero#1{{\bf Z}} \def\fwmany#1{{\bf M}} \def\fwequals{ $\equiv$} \def\fwplusequals{ $+\equiv$} % Now for the actual body of the definition. It looks nice to have the tt % code indented a little. Again, we use macros instead of writing direct TeX, % so as to allow the user to fiddle this stuff to taste without having to % modify the FunnelWeb C code. \def\fwodef{\parindent=15pt\vskip0pt$\lbrace$\parindent=20pt} \def\fwcdef{$\rbrace$\vskip0pt\parindent=0pt} \def\fwoquote{`} \def\fwcquote{'} \def\fwoparen{$($} \def\fwcomma{$,$} \def\fwcparen{$)$} \def\fwparam#1{$\diamond #1$} \def\fwparams#1{$(\diamond #1)$} % These macros deal with the notes that are appended at the end of each % macro definition. Note that even though \fwisafile,\fwusedin, and \fwseealso % have the same definition, they are given different names so as to allow the % user to redefine these macros to typeset each kind of information differently % if desired. \def\fwbeginmacronotes{\begingroup\baselineskip=9pt\smallskip} \def\fwnote#1{{\fwfontnote #1}\par} \def\fwisafile#1{\fwnote{#1}} \def\fwusedin#1{\fwnote{#1}} \def\fwseealso#1{\fwnote{#1}} \def\fwendmacronotes{\endgroup} % Macros to Typeset Program Code Verbatim % --------------------------------------- % This is by far the hairiest and most difficult part of the typesetting task % because we have to turn off most of TeX's natural instincts in order to % typeset the program text exactly as it appears in the input file. % Two macros are defined to pull this off: \fwbtx and \fwverbatimgobble. % Their code was inspired by the following sections of "The TeXbook": % Appendix D: Dirty Tricks, 3.Verbatim listing, p.380-382. % Appendix E: Example Formats, p.421. % The \fwbtx[ (for "FunnelWeb Begin TeXt") macro does most of the hard work. % The liberal use of "%" is because I don't understand TeX well enough to % understand when an end of line will cause trouble, and I am playing it safe. % Before defining the main \fwbtx macro, we have to stash away some definitions % in the hidden part of TeX's environment. Let's hope that these "hidden" % definitions don't affect anything except what is desired to be affected. % The tt font in which we wish to set the text has two Latin lurking ligatures! % These are ?` and !`. To disable them, we define the left quote when ACTIVE % to be defined in such a way as to prevent ligatures. The main TeX text will % normally not be exposed to this definition because normally the leftquote % character is not active. The \fwbtx macro temporarily makes the left quote % character active thus activating the deactivation of left quote ligatures. % See The TeXbook p.381. {\catcode`\`=\active \gdef`{\relax\lq}} % TeX is fairly carefree about spaces and so we have to make it more serious. % To do so we pull the same trick as above, setting up a definition for active % space, but only making space active during the span of the verbatim text. % In Plain TeX the active space is defined to be simply a space, but here we % define it to be a control space. This ensures that the space cannot % be gobbled up by one of TeX's mysterious mechanisms when activated. % See The TeXbook, p.381 and p.352. {\obeyspaces\global\let =\ } % Here is the main \fwbtx verbatim text macro. % Note: The order in which all these pieces of business have to be done is % still a partial mystery to me. Don't fiddle with this stuff unless you % think you know what you are doing. \def\fwbtx[{% % % The funnies involved in getting verbatim output are safely housed inside % this \begingroup, and the \endgroup in \fwverbatimgobble. Groups are used % instead of curly braces because we have to be able to signal the end of % this macro with a curly brace. \begingroup% % % \pars at the end of empty lines in the verbatim text won't come out normally % because TeX is in vertical mode and they get gobbled up. To prevent this, % we force \par to exit vertical mode first. See The TeXbook p.381. \def\par{\leavevmode\endgraf}% % % Activate the leftquote character so as to avoid ligatures (see above). \catcode`\`=\active% % % The \obeylines macro simply defines end of line (^M) to be \par. This ensures % that TeX will treat each verbatim line as a new paragraph. \obeylines% % % To get verbatim output, we have to desex all the special characters. This % is explained in detail in The TeXbook p.380. \def\do##1{\catcode`##1=12 }\dospecials% % % Activate the space character so as to make TeX treat blanks seriously. % This activation invokes an eralier definition (see above). \obeyspaces % % Interparagraph skips do not help the cause. % Note: We have to preserve the indentation though, as the code is actually % indented in the final output. See \fwodef in an earlier section. \parskip=0pt% % % We typeset the verbatim text in tt font (courier on the Macintosh) for a % number of reasons: % - tt font has the same horizontal spacing for each character. % - tt font covers the ASCII character set. % - tt font doesn't have many surprises (e.g. ligatures). % - tt font looks much what you might see on a computer terminal screen. \tt% % % Having set up an environment for verbatim, we are ready to use it. % By invoking \fwverbatimgobble, this \fwbtx macro gobbles up text verbatim (as % part of the parameter of \fwverbatimgobble) until it sees the termination % string "]fwetx=" (the "=" was thrown in to add obscurity as this sequence % must never occur in the verbatim text). \fwverbatimgobble} % The \fwverbatimgobble macro exists to allow \fwbtx to bracket verbatim text. \def\fwverbatimgobble#1]fwetx={#1\endgroup} % Table of Contents % ----------------- % The five levels of table of contents that FunnelWeb supports are identified % by the five letters [A..E]. These are used throughout the following macros. % The following macros are utilities to the TOC macros to follow. \def\fwrule{\medskip\hrule\medskip} \def\fwqh{\hskip1.5em\relax} \def\fwbeforesec{\penalty-200\bigskip\medskip\par} % The following macros are used to typeset the table of contents. \def\fwtocstart#1{\fwrule\leftline{\fwfontbolda Table of Contents}\fwrule} \def\fwtoca#1#2{\leftline{{\bf #1 #2}}} \def\fwtocb#1#2{\leftline{\fwqh #1 #2}} \def\fwtocc#1#2{\leftline{\fwqh\fwqh #1 #2}} \def\fwtocd#1#2{\leftline{\fwqh\fwqh\fwqh #1 #2}} \def\fwtoce#1#2{\leftline{\fwqh\fwqh\fwqh\fwqh #1 #2}} \def\fwtocfinish#1{\fwrule} % The following "library" macros define five different strengths of headings % which can be used later in the section macros. \def\fwliba#1#2{\vfill\eject{\fwfontboldc #1 #2}\penalty200\smallskip} \def\fwlibb#1#2{\fwbeforesec{\fwfontboldb #1 #2}\penalty200\smallskip} \def\fwlibc#1#2{\fwbeforesec{\fwfontnormb #1 #2}\penalty200\smallskip} \def\fwlibd#1#2{\fwbeforesec{\bf #1 #2}\penalty200} \def\fwlibe#1#2{\fwbeforesec{\bf #1 #2}} % Here are the macros that actually typeset the section headings throughout % the document. The fwlib system has been employed so as to easily allow the % user to redefine the strengths of headings to taste. For example, the % user could insert in the input document a similar set of definitions to these % but with the b..e headings set to \fwlibc. This would tone down the output. \def\fwseca#1#2{\fwliba{#1}{#2}} \def\fwsecb#1#2{\fwlibb{#1}{#2}} \def\fwsecc#1#2{\fwlibc{#1}{#2}} \def\fwsecd#1#2{\fwlibd{#1}{#2}} \def\fwsece#1#2{\fwlibe{#1}{#2}} % Support for Explicit Typesetting % -------------------------------- % FunnelWeb supports pragmas and other constructs that allow % typesetter-independent typesetting commands to be given. The % following macros support these features. % The in-text literal @{sloth@} and emphasise @[walrus@] features. \def\fwlit#1{{\tt #1}} \def\fwemp#1{{\it #1}} % The "@p new_page" pragma. \def\fwnewpage{\vfill\eject} % The "@p vskip Nmm" pragma. \def\fwvskip#1{\null\vskip #1mm} % The "@p title " pragma. \def\fwfontnormal#1{{\fwfontnorm {#1}}} \def\fwfonttitle#1{{\fwfontboldd {#1}}} \def\fwfontsmalltitle#1{{\fwfontboldb {#1}}} \def\fwleftline#1{\leftline{#1}} \def\fwcenterline#1{\centerline{#1}} \def\fwrightline#1{\rightline{#1}} % Support for Old FunnelWeb % ------------------------- % The following macros were used extensively in the first version of % FunnelWeb and are retained so that these older input files will still % typeset cleanly. \def\p#1{{\tt #1}} % P for Program text. \def\flagpage#1#2{ \null \vfill \centerline{\fwfontboldd #1} \vskip 1cm \centerline{\fwfontboldd #2} \vfill \null \vfill } %====================== End of FunnelWeb TeX Definitions ======================= EX13: This example is used to generate typeset documentation which is discussed in the tutorial in the FunnelWeb user's manual. \fwseca{1}{Table of Contents} \fwtocstart{} \fwtoca{1}{Table of Contents} \fwtoca{2}{Macros for Moral Support} \fwtoca{3}{An Extremely Imperative Stack Abstraction} \fwtocb{3.1}{Define the Stack} \fwtocb{3.2}{Push the Stack} \fwtocb{3.3}{Pop the Stack} \fwtocb{3.4}{Rough the Stack Up a Bit} \fwtocfinish{} \fwseca{2}{Macros for Moral Support} The following macro contain comments that provide moral support in the output code. \fwbeginmacro \fwmacroname{Programmer's Cheer}{1}\fwmany{}\fwequals \fwodef \fwbtx[ -- Shift to the left! -- Shift to the right! -- Pop up, push down! -- Byte! Byte! Byte! -- (From "The New Hacker's Dictionary"). ]fwetx=% \fwcdef \fwbeginmacronotes \fwusedin{This macro is invoked in definitions 6 and 8.} \fwendmacronotes \fwendmacro The next macro is similar but is distributed throughout the program. \fwbeginmacro \fwmacroname{Hacker's Cheer}{2}\fwplusequals \fwodef \fwbtx[ -- Pointer to the left ]fwetx=% \fwcdef \fwbeginmacronotes \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.} \fwusedin{This macro is invoked in definition 10.} \fwendmacronotes \fwendmacro \fwseca{3}{An Extremely Imperative Stack Abstraction} \fwsecb{3.1}{Define the Stack} \fwbeginmacro \fwmacroname{Hacker's Cheer}{3}\fwplusequals \fwodef \fwbtx[-- Pointer to the right ]fwetx=% \fwcdef \fwbeginmacronotes \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.} \fwusedin{This macro is invoked in definition 10.} \fwendmacronotes \fwendmacro \fwbeginmacro \fwmacroname{Stack Type}{4}\fwzero{}\fwequals \fwodef \fwbtx[type stack = record ... end;]fwetx=% \fwcdef \fwbeginmacronotes \fwusedin{This macro is NEVER invoked.} \fwendmacronotes \fwendmacro \fwsecb{3.2}{Push the Stack} \fwbeginmacro \fwmacroname{Hacker's Cheer}{5}\fwplusequals \fwodef \fwbtx[-- Hack that code ]fwetx=% \fwcdef \fwbeginmacronotes \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.} \fwusedin{This macro is invoked in definition 10.} \fwendmacronotes \fwendmacro \fwbeginmacro \fwmacroname{Push Procedure}{6}\fwzero{}\fwequals \fwodef \fwbtx[procedure push(var b:stack; v:value); ]fwetx=% \fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=% \fwcdef \fwbeginmacronotes \fwusedin{This macro is NEVER invoked.} \fwendmacronotes \fwendmacro \fwsecb{3.3}{Pop the Stack} \fwbeginmacro \fwmacroname{Hacker's Cheer}{7}\fwplusequals \fwodef \fwbtx[-- Tight! Tight! Tight! ]fwetx=% \fwcdef \fwbeginmacronotes \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.} \fwusedin{This macro is invoked in definition 10.} \fwendmacronotes \fwendmacro \fwbeginmacro \fwmacroname{Pop Procedure}{8}\fwzero{}\fwequals \fwodef \fwbtx[procedure pop(var b:stack); ]fwetx=% \fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=% \fwcdef \fwbeginmacronotes \fwusedin{This macro is NEVER invoked.} \fwendmacronotes \fwendmacro \fwsecb{3.4}{Rough the Stack Up a Bit} \fwbeginmacro \fwmacroname{Hacker's Cheer}{9}\fwplusequals \fwodef \fwbtx[-- (RNW, 04-Jan-1991). ]fwetx=% \fwcdef \fwbeginmacronotes \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.} \fwusedin{This macro is invoked in definition 10.} \fwendmacronotes \fwendmacro \fwbeginmacro \fwmacroname{Rough Procedure}{10}\fwzero{}\fwequals \fwodef \fwbtx[procedure rough(var b:stack); ]fwetx=% \fwmacroname{Hacker's Cheer}{2}\fwbtx[ {...}]fwetx=% \fwcdef \fwbeginmacronotes \fwusedin{This macro is NEVER invoked.} \fwendmacronotes \fwendmacro \fwbeginmacro \fwfilename{dummy.txt}{11}\fwequals \fwodef \fwbtx[dummy ]fwetx=% \fwcdef \fwbeginmacronotes \fwisafile{This macro is attached to an output file.} \fwendmacronotes \fwendmacro \bye %******************************************************************************* %* END OF AUTOMATICALLY GENERATED TEX FILE * %*******************************************************************************