home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / World_Of_Computer_Software-02-385-Vol-1of3.iso / f / funnel-x.zip / examples / ex13.tex < prev    next >
Text File  |  1992-05-27  |  19KB  |  500 lines
  1.  
  2. %*******************************************************************************
  3. %*                    START OF AUTOMATICALLY GENERATED TEX FILE                *
  4. %*******************************************************************************
  5. %*                                                                             *
  6. %* This TeX file was automatically generated by the FunnelWeb preprocessor.    *
  7. %* You can typeset this file to produce printed documentation by running it    *
  8. %* through the TeX typesetter using a command such as:                         *
  9. %*    tex thisfilename                                                         *
  10. %* The resultant file thisfilename.dvi can be printed using a command such as: *
  11. %*    lpr -Pcslw -d thisfilename.dvi                                           *
  12. %*                                                                             *
  13. %* FunnelWeb is a preprocessor that allows programmers to weave programs and   *
  14. %* their documentation together in a single document. The FunnelWeb program    *
  15. %* analyses such documents producing both program files and typeset            *
  16. %* documentation such as this TeX file.                                        *
  17. %* FunnelWeb was created by Ross Williams.                                     *
  18. %*                                                                             *
  19. %* For more information on FunnelWeb look in the following FTP archive:        *
  20. %*    Machine  : sirius.itd.adelaide.edu.au [IP=129.127.40.3].                 *
  21. %*    Directory: ~pub/funnelweb/                                               *
  22. %*               (or some other appropriately named directory).                *
  23. %* or email Ross Williams at ross@spam.adelaide.edu.au                         *
  24. %*                                                                             *
  25. %*******************************************************************************
  26.  
  27.  
  28. %===================== Start of FunnelWeb TeX Definitions ======================
  29.  
  30.  
  31. % Version
  32. % -------
  33. % This is FunnelWeb TeX Macro Library Version 1.0.
  34.  
  35.  
  36. % Copyright
  37. % ---------
  38. % This set of FunnelWeb TeX definitions was written by Ross Williams and was
  39. % originally Copyright (C) 1992 Ross N. Williams.  However, I, Ross Williams,
  40. % hereby forego any claim to Copyright in this set of FunnelWeb TeX definitions
  41. % and hereby authorize that the set of TeX definitions pass into the public
  42. % domain. -- Ross N. Williams, 3:41pm 07-May-1992, Adelaide, Australia.
  43.  
  44.  
  45. % Modification
  46. % ------------
  47. % Please record all modifications to these TeX definitions here. Unless
  48. % otherwise specified, all modified definitions fall in the public domain too.
  49. %
  50. % Programmers:
  51. %    RNW  Ross N. Williams  ross@spam.adelaide.edu.au
  52. %
  53. % Changes:
  54. %    07-May-1992  RNW  Prepared this work for public domain release.
  55. %
  56.  
  57.  
  58. % General Comments
  59. % ----------------
  60. % This set of TeX definitions exists for two reasons:
  61. %
  62. %    1. To shorten and neaten the FunnelWeb TeX output.
  63. %    2. To allow users to fiddle with the output format in their input files
  64. %       (by inserting redefining "\def"s) without having to resort to
  65. %       modifying the FunnelWeb code.
  66. %
  67. % The user is warned that these definitions may be changed from time to time
  68. % (but probably not much). The user should not be too sneaky. In particular,
  69. % users wishing to redefine some of these macros should do so in an explicitly
  70. % defined section at the top of their input file. This will mean that in the
  71. % event of problems, that section can simply be deleted or commented out to
  72. % allow the document to at least be typeset in the default format. Users should
  73. % limit themselves to redefining these macros in such a section and should
  74. % refrain from using the macros throughout their documents.
  75.  
  76.  
  77. % Environment Parameters
  78. % ----------------------
  79. % \tolerance tells TeX how tolerant it should be about making bad line and
  80. % page breaks. Here we set it to it's maximum, as
  81. %   1) Computer programs are likely to cause lots of bad breaks.
  82. %   2) In most cases the user would probably rather get the TeX file through
  83. %      TeX without any errors than fiddle with spacings for perfection.
  84. \tolerance=10000
  85.  
  86. % I don't like indentation as it makes the page look more busy. Instead,
  87. % paragraphs are separated by a little space (see next).
  88. \parindent=0pt
  89.  
  90. % In many cases, users will produce documents with long runs of paragraphs.
  91. % In order to space out these paragraphs, it is convenient to maintain a
  92. % prevailing non-zero \parskip (end-of-paragaph skip). The only trouble is
  93. % that the skip becomes a problem in macro definitions which require no skip
  94. % and so we have to turn the skip on and off. The following two macros
  95. % simplify this process.
  96. \def\fwparskipon{\parskip=\medskipamount}
  97. \def\fwparskipoff{\parskip=0pt}
  98. \fwparskipon
  99.  
  100. % Setting raggedbottom allows TeX to leave a bit of space at the bottom of the
  101. % page in order to better vertically align the rest of the page (e.g. skips
  102. % won't stretch as much). It also means that headings are less likely to be
  103. % isolated at the bottom of the page without any following text.
  104. \raggedbottom
  105.  
  106.  
  107. % Fonts
  108. % -----
  109. % Most of the typeset output is set in 10pt roman and 10pt tt font.
  110. % The major extra font needs spring from titles and headings.
  111. % For portability's sake we use only the following fonts:
  112. %    cmr10
  113. %    cmbx10
  114. %    cmtt10
  115. % and some enlargements of them. These fonts are all "standard" fonts
  116. % in Plain TeX. See The TeXbook p.350.
  117. \font\fwfontnote=cmr7
  118.  
  119. \font\fwfontnorm=cmr10
  120. \font\fwfontnorma=cmr10 scaled \magstep1
  121. \font\fwfontnormb=cmr10 scaled \magstep2
  122.  
  123. \font\fwfontbold=cmbx10
  124. \font\fwfontbolda=cmbx10 scaled \magstep1
  125. \font\fwfontboldb=cmbx10 scaled \magstep2
  126. \font\fwfontboldc=cmbx10 scaled \magstep3
  127. \font\fwfontboldd=cmbx10 scaled \magstep4
  128.  
  129.  
  130. % Macros for Stylistic Details
  131. % ----------------------------
  132. % This section contains all the fiddly little macros for setting the details
  133. % of each macro definition.
  134.  
  135. % Macro definitions are sandwiched by calls to these macros which can be used
  136. % to sort out the spacing before and after the macro definition.
  137. \def\fwbeginmacro{\fwparskipoff\bigskip}
  138. \def\fwendmacro{\fwparskipon\par}
  139.  
  140. % These macros deal with the macro name and definition line.
  141. \def\fwmacroname#1#2{{\sl #1\/}$\lbrack$#2$\rbrack$}
  142. \def\fwfilename#1#2{{\bf #1}$\lbrack$#2$\rbrack$}
  143. \def\fwzero#1{{\bf Z}}
  144. \def\fwmany#1{{\bf M}}
  145. \def\fwequals{ $\equiv$}
  146. \def\fwplusequals{ $+\equiv$}
  147.  
  148. % Now for the actual body of the definition. It looks nice to have the tt
  149. % code indented a little. Again, we use macros instead of writing direct TeX,
  150. % so as to allow the user to fiddle this stuff to taste without having to
  151. % modify the FunnelWeb C code.
  152. \def\fwodef{\parindent=15pt\vskip0pt$\lbrace$\parindent=20pt}
  153. \def\fwcdef{$\rbrace$\vskip0pt\parindent=0pt}
  154. \def\fwoquote{`}
  155. \def\fwcquote{'}
  156. \def\fwoparen{$($}
  157. \def\fwcomma{$,$}
  158. \def\fwcparen{$)$}
  159. \def\fwparam#1{$\diamond #1$}
  160. \def\fwparams#1{$(\diamond #1)$}
  161.  
  162. % These macros deal with the notes that are appended at the end of each
  163. % macro definition. Note that even though \fwisafile,\fwusedin, and \fwseealso
  164. % have the same definition, they are given different names so as to allow the
  165. % user to redefine these macros to typeset each kind of information differently
  166. % if desired.
  167. \def\fwbeginmacronotes{\begingroup\baselineskip=9pt\smallskip}
  168. \def\fwnote#1{{\fwfontnote #1}\par}
  169. \def\fwisafile#1{\fwnote{#1}}
  170. \def\fwusedin#1{\fwnote{#1}}
  171. \def\fwseealso#1{\fwnote{#1}}
  172. \def\fwendmacronotes{\endgroup}
  173.  
  174.  
  175. % Macros to Typeset Program Code Verbatim
  176. % ---------------------------------------
  177. % This is by far the hairiest and most difficult part of the typesetting task
  178. % because we have to turn off most of TeX's natural instincts in order to
  179. % typeset the program text exactly as it appears in the input file.
  180. % Two macros are defined to pull this off: \fwbtx and \fwverbatimgobble.
  181. % Their code was inspired by the following sections of "The TeXbook":
  182. %    Appendix D: Dirty Tricks, 3.Verbatim listing, p.380-382.
  183. %    Appendix E: Example Formats, p.421.
  184. % The \fwbtx[ (for "FunnelWeb Begin TeXt") macro does most of the hard work.
  185. % The liberal use of "%" is because I don't understand TeX well enough to
  186. % understand when an end of line will cause trouble, and I am playing it safe.
  187.  
  188. % Before defining the main \fwbtx macro, we have to stash away some definitions
  189. % in the hidden part of TeX's environment. Let's hope that these "hidden"
  190. % definitions don't affect anything except what is desired to be affected.
  191.  
  192. % The tt font in which we wish to set the text has two Latin lurking ligatures!
  193. % These are ?` and !`. To disable them, we define the left quote when ACTIVE
  194. % to be defined in such a way as to prevent ligatures. The main TeX text will
  195. % normally not be exposed to this definition because normally the leftquote
  196. % character is not active. The \fwbtx macro temporarily makes the left quote
  197. % character active thus activating the deactivation of left quote ligatures.
  198. % See The TeXbook p.381.
  199. {\catcode`\`=\active \gdef`{\relax\lq}}
  200.  
  201. % TeX is fairly carefree about spaces and so we have to make it more serious.
  202. % To do so we pull the same trick as above, setting up a definition for active
  203. % space, but only making space active during the span of the verbatim text.
  204. % In Plain TeX the active space is defined to be simply a space, but here we
  205. % define it to be a control space. This ensures that the space cannot
  206. % be gobbled up by one of TeX's mysterious mechanisms when activated.
  207. % See The TeXbook, p.381 and p.352.
  208. {\obeyspaces\global\let =\ }
  209.  
  210. % Here is the main \fwbtx verbatim text macro.
  211. % Note: The order in which all these pieces of business have to be done is
  212. % still a partial mystery to me. Don't fiddle with this stuff unless you
  213. % think you know what you are doing.
  214. \def\fwbtx[{%
  215. %
  216. % The funnies involved in getting verbatim output are safely housed inside
  217. % this \begingroup, and the \endgroup in \fwverbatimgobble. Groups are used
  218. % instead of curly braces because we have to be able to signal the end of
  219. % this macro with a curly brace.
  220. \begingroup%
  221. %
  222. % \pars at the end of empty lines in the verbatim text won't come out normally
  223. % because TeX is in vertical mode and they get gobbled up. To prevent this,
  224. % we force \par to exit vertical mode first. See The TeXbook p.381.
  225. \def\par{\leavevmode\endgraf}%
  226. %
  227. % Activate the leftquote character so as to avoid ligatures (see above).
  228. \catcode`\`=\active%
  229. %
  230. % The \obeylines macro simply defines end of line (^M) to be \par. This ensures
  231. % that TeX will treat each verbatim line as a new paragraph.
  232. \obeylines%
  233. %
  234. % To get verbatim output, we have to desex all the special characters. This
  235. % is explained in detail in The TeXbook p.380.
  236. \def\do##1{\catcode`##1=12 }\dospecials%
  237. %
  238. % Activate the space character so as to make TeX treat blanks seriously.
  239. % This activation invokes an eralier definition (see above).
  240. \obeyspaces
  241. %
  242. % Interparagraph skips do not help the cause.
  243. % Note: We have to preserve the indentation though, as the code is actually
  244. % indented in the final output. See \fwodef in an earlier section.
  245. \parskip=0pt%
  246. %
  247. % We typeset the verbatim text in tt font (courier on the Macintosh) for a
  248. % number of reasons:
  249. %    - tt font has the same horizontal spacing for each character.
  250. %    - tt font covers the ASCII character set.
  251. %    - tt font doesn't have many surprises (e.g. ligatures).
  252. %    - tt font looks much what you might see on a computer terminal screen.
  253. \tt%
  254. %
  255. % Having set up an environment for verbatim, we are ready to use it.
  256. % By invoking \fwverbatimgobble, this \fwbtx macro gobbles up text verbatim (as
  257. % part of the parameter of \fwverbatimgobble) until it sees the termination
  258. % string "]fwetx=" (the "=" was thrown in to add obscurity as this sequence
  259. % must never occur in the verbatim text).
  260. \fwverbatimgobble}
  261.  
  262. % The \fwverbatimgobble macro exists to allow \fwbtx to bracket verbatim text.
  263. \def\fwverbatimgobble#1]fwetx={#1\endgroup}
  264.  
  265.  
  266. % Table of Contents
  267. % -----------------
  268. % The five levels of table of contents that FunnelWeb supports are identified
  269. % by the five letters [A..E]. These are used throughout the following macros.
  270.  
  271. % The following macros are utilities to the TOC macros to follow.
  272. \def\fwrule{\medskip\hrule\medskip}
  273. \def\fwqh{\hskip1.5em\relax}
  274. \def\fwbeforesec{\penalty-200\bigskip\medskip\par}
  275.  
  276. % The following macros are used to typeset the table of contents.
  277. \def\fwtocstart#1{\fwrule\leftline{\fwfontbolda Table of Contents}\fwrule}
  278. \def\fwtoca#1#2{\leftline{{\bf #1 #2}}}
  279. \def\fwtocb#1#2{\leftline{\fwqh #1 #2}}
  280. \def\fwtocc#1#2{\leftline{\fwqh\fwqh #1 #2}}
  281. \def\fwtocd#1#2{\leftline{\fwqh\fwqh\fwqh #1 #2}}
  282. \def\fwtoce#1#2{\leftline{\fwqh\fwqh\fwqh\fwqh #1 #2}}
  283. \def\fwtocfinish#1{\fwrule}
  284.  
  285. % The following "library" macros define five different strengths of headings
  286. % which can be used later in the section macros.
  287. \def\fwliba#1#2{\vfill\eject{\fwfontboldc #1 #2}\penalty200\smallskip}
  288. \def\fwlibb#1#2{\fwbeforesec{\fwfontboldb #1 #2}\penalty200\smallskip}
  289. \def\fwlibc#1#2{\fwbeforesec{\fwfontnormb #1 #2}\penalty200\smallskip}
  290. \def\fwlibd#1#2{\fwbeforesec{\bf          #1 #2}\penalty200}
  291. \def\fwlibe#1#2{\fwbeforesec{\bf          #1 #2}}
  292.  
  293. % Here are the macros that actually typeset the section headings throughout
  294. % the document. The fwlib system has been employed so as to easily allow the
  295. % user to redefine the strengths of headings to taste. For example, the
  296. % user could insert in the input document a similar set of definitions to these
  297. % but with the b..e headings set to \fwlibc. This would tone down the output.
  298. \def\fwseca#1#2{\fwliba{#1}{#2}}
  299. \def\fwsecb#1#2{\fwlibb{#1}{#2}}
  300. \def\fwsecc#1#2{\fwlibc{#1}{#2}}
  301. \def\fwsecd#1#2{\fwlibd{#1}{#2}}
  302. \def\fwsece#1#2{\fwlibe{#1}{#2}}
  303.  
  304.  
  305. % Support for Explicit Typesetting
  306. % --------------------------------
  307. % FunnelWeb supports pragmas and other constructs that allow
  308. % typesetter-independent typesetting commands to be given. The
  309. % following macros support these features.
  310.  
  311. % The in-text literal @{sloth@} and emphasise @[walrus@] features.
  312. \def\fwlit#1{{\tt #1}}
  313. \def\fwemp#1{{\it #1}}
  314.  
  315. % The "@p new_page" pragma.
  316. \def\fwnewpage{\vfill\eject}
  317.  
  318. % The "@p vskip Nmm" pragma.
  319. \def\fwvskip#1{\null\vskip #1mm}
  320.  
  321. % The "@p title <font> <align> <text>" pragma.
  322. \def\fwfontnormal#1{{\fwfontnorm {#1}}}
  323. \def\fwfonttitle#1{{\fwfontboldd {#1}}}
  324. \def\fwfontsmalltitle#1{{\fwfontboldb {#1}}}
  325. \def\fwleftline#1{\leftline{#1}}
  326. \def\fwcenterline#1{\centerline{#1}}
  327. \def\fwrightline#1{\rightline{#1}}
  328.  
  329.  
  330. % Support for Old FunnelWeb
  331. % -------------------------
  332. % The following macros were used extensively in the first version of
  333. % FunnelWeb and are retained so that these older input files will still
  334. % typeset cleanly.
  335. \def\p#1{{\tt #1}}  % P for Program text.
  336. \def\flagpage#1#2{
  337.    \null
  338.    \vfill
  339.    \centerline{\fwfontboldd #1}
  340.    \vskip 1cm
  341.    \centerline{\fwfontboldd #2}
  342.    \vfill
  343.    \null
  344.    \vfill
  345. }
  346.  
  347. %====================== End of FunnelWeb TeX Definitions =======================
  348. EX13: This example is used to generate typeset documentation which is
  349.       discussed in the tutorial in the FunnelWeb user's manual.
  350.  
  351.  
  352. \fwseca{1}{Table of Contents}
  353.  
  354.  
  355. \fwtocstart{}
  356. \fwtoca{1}{Table of Contents}
  357. \fwtoca{2}{Macros for Moral Support}
  358. \fwtoca{3}{An Extremely Imperative Stack Abstraction}
  359. \fwtocb{3.1}{Define the Stack}
  360. \fwtocb{3.2}{Push the Stack}
  361. \fwtocb{3.3}{Pop the Stack}
  362. \fwtocb{3.4}{Rough the Stack Up a Bit}
  363. \fwtocfinish{}
  364.  
  365.  
  366. \fwseca{2}{Macros for Moral Support}
  367.  
  368. The following macro contain comments that provide moral support in the
  369. output code.
  370.  
  371. \fwbeginmacro
  372. \fwmacroname{Programmer's Cheer}{1}\fwmany{}\fwequals \fwodef \fwbtx[
  373. -- Shift to the left!
  374. -- Shift to the right!
  375. -- Pop up, push down!
  376. -- Byte! Byte! Byte!
  377. -- (From "The New Hacker's Dictionary").
  378. ]fwetx=%
  379. \fwcdef 
  380. \fwbeginmacronotes
  381. \fwusedin{This macro is invoked in definitions 6 and 8.}
  382. \fwendmacronotes
  383. \fwendmacro
  384.  
  385.  
  386. The next macro is similar but is distributed throughout the program.
  387. \fwbeginmacro
  388. \fwmacroname{Hacker's Cheer}{2}\fwplusequals \fwodef \fwbtx[
  389. -- Pointer to the left
  390. ]fwetx=%
  391. \fwcdef 
  392. \fwbeginmacronotes
  393. \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
  394. \fwusedin{This macro is invoked in definition 10.}
  395. \fwendmacronotes
  396. \fwendmacro
  397.  
  398.  
  399. \fwseca{3}{An Extremely Imperative Stack Abstraction}
  400.  
  401. \fwsecb{3.1}{Define the Stack}
  402. \fwbeginmacro
  403. \fwmacroname{Hacker's Cheer}{3}\fwplusequals \fwodef \fwbtx[-- Pointer to the right
  404. ]fwetx=%
  405. \fwcdef 
  406. \fwbeginmacronotes
  407. \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
  408. \fwusedin{This macro is invoked in definition 10.}
  409. \fwendmacronotes
  410. \fwendmacro
  411.  
  412. \fwbeginmacro
  413. \fwmacroname{Stack Type}{4}\fwzero{}\fwequals \fwodef \fwbtx[type stack = record ... end;]fwetx=%
  414. \fwcdef 
  415. \fwbeginmacronotes
  416. \fwusedin{This macro is NEVER invoked.}
  417. \fwendmacronotes
  418. \fwendmacro
  419.  
  420.  
  421. \fwsecb{3.2}{Push the Stack}
  422. \fwbeginmacro
  423. \fwmacroname{Hacker's Cheer}{5}\fwplusequals \fwodef \fwbtx[-- Hack that code
  424. ]fwetx=%
  425. \fwcdef 
  426. \fwbeginmacronotes
  427. \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
  428. \fwusedin{This macro is invoked in definition 10.}
  429. \fwendmacronotes
  430. \fwendmacro
  431.  
  432. \fwbeginmacro
  433. \fwmacroname{Push Procedure}{6}\fwzero{}\fwequals \fwodef \fwbtx[procedure push(var b:stack; v:value); ]fwetx=%
  434. \fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=%
  435. \fwcdef 
  436. \fwbeginmacronotes
  437. \fwusedin{This macro is NEVER invoked.}
  438. \fwendmacronotes
  439. \fwendmacro
  440.  
  441.  
  442. \fwsecb{3.3}{Pop the Stack}
  443. \fwbeginmacro
  444. \fwmacroname{Hacker's Cheer}{7}\fwplusequals \fwodef \fwbtx[-- Tight! Tight! Tight!
  445. ]fwetx=%
  446. \fwcdef 
  447. \fwbeginmacronotes
  448. \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
  449. \fwusedin{This macro is invoked in definition 10.}
  450. \fwendmacronotes
  451. \fwendmacro
  452.  
  453. \fwbeginmacro
  454. \fwmacroname{Pop Procedure}{8}\fwzero{}\fwequals \fwodef \fwbtx[procedure pop(var b:stack); ]fwetx=%
  455. \fwmacroname{Programmer's Cheer}{1}\fwbtx[ {...}]fwetx=%
  456. \fwcdef 
  457. \fwbeginmacronotes
  458. \fwusedin{This macro is NEVER invoked.}
  459. \fwendmacronotes
  460. \fwendmacro
  461.  
  462.  
  463. \fwsecb{3.4}{Rough the Stack Up a Bit}
  464. \fwbeginmacro
  465. \fwmacroname{Hacker's Cheer}{9}\fwplusequals \fwodef \fwbtx[-- (RNW, 04-Jan-1991).
  466. ]fwetx=%
  467. \fwcdef 
  468. \fwbeginmacronotes
  469. \fwseealso{This macro is defined in definitions 2, 3, 5, 7, and 9.}
  470. \fwusedin{This macro is invoked in definition 10.}
  471. \fwendmacronotes
  472. \fwendmacro
  473.  
  474. \fwbeginmacro
  475. \fwmacroname{Rough Procedure}{10}\fwzero{}\fwequals \fwodef \fwbtx[procedure rough(var b:stack); ]fwetx=%
  476. \fwmacroname{Hacker's Cheer}{2}\fwbtx[ {...}]fwetx=%
  477. \fwcdef 
  478. \fwbeginmacronotes
  479. \fwusedin{This macro is NEVER invoked.}
  480. \fwendmacronotes
  481. \fwendmacro
  482.  
  483.  
  484. \fwbeginmacro
  485. \fwfilename{dummy.txt}{11}\fwequals \fwodef \fwbtx[dummy
  486. ]fwetx=%
  487. \fwcdef 
  488. \fwbeginmacronotes
  489. \fwisafile{This macro is attached to an output file.}
  490. \fwendmacronotes
  491. \fwendmacro
  492.  
  493. \bye
  494.  
  495.  
  496. %*******************************************************************************
  497. %*                    END OF AUTOMATICALLY GENERATED TEX FILE                  *
  498. %*******************************************************************************
  499.  
  500.