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 / userman / u_ch0.tex next >
Text File  |  1992-05-27  |  8KB  |  198 lines
  1. %==============================================================================%
  2. %                                 Start of Ch0.tex                             %
  3. %==============================================================================%
  4. %
  5. % Copyright
  6. % ---------
  7. % Copyright (C) 1992 Ross N. Williams.
  8. % This file contains a chapter of the FunnelWeb User's Manual.
  9. % See the main TeX file for this manual for further information.
  10. %
  11. %==============================================================================%
  12.  
  13. \vbox{\relax}
  14. \vfill
  15.  
  16. \hrule
  17.  
  18. \medskip
  19.  
  20. Copyright \copyright{} 1992 Ross~N.~Williams.
  21. \xn{Ross}{Williams}\xx{copyright}{notice}
  22.  
  23. Permission is granted to make and distribute verbatim copies of this manual
  24. provided that the copyright notice and this permission notice are preserved
  25. on all copies.\note{This paragraph was copied from the GNU Emacs manual to
  26. avoid my having to get a legal opinion on something I could cook up.}
  27.  
  28. \medskip
  29.  
  30. \hrule
  31.  
  32. \newpage
  33.  
  34. %==============================================================================
  35.  
  36. \tableofcontents
  37.  
  38. \newpage
  39.  
  40. %==============================================================================
  41.  
  42. %I am not using LaTeX's figures and tables numbering so these are commented out.
  43. %\pseudochapter{List of Figures}
  44. %\pseudochapter{List of Tables}
  45.  
  46. %==============================================================================
  47.  
  48. % No forward.
  49. %\pseudochapter{Foreword}
  50. %\x{foreword}
  51.  
  52. %==============================================================================
  53.  
  54. \pseudochapter{Preface}
  55. \x{preface}
  56.  
  57. When, in 1986, I first read Donald Knuth's\xn{Donald}{Knuth}
  58. technical report on Web\paper{Knuth83},\x{Web} and
  59. tried Web out, I was simultaneously excited by Knuth's idea of literate
  60. programming, and disappointed by his implementation of it. I was excited
  61. because I could sense the potential for
  62. the literate style to transform the state of mind of the programmer, but was
  63. disappointed by Web's rigidity
  64. and lack of practicality, which seemed to betray this potential.
  65. The Web I used was Pascal-specific, \TeX{}-specific, and applied too
  66. many constraints to the programming process.
  67. In particular, it insisted on taking control of the
  68. program text, mangling the code in the Pascal output files,
  69. and imposing its own rather rigid ideas about indenting in the \TeX{} output.
  70. All this, combined with the complexity of the tool, led me
  71. to come to perceive Web as problem rather than solution. 
  72.  
  73. Despite all this, I was well and truly hooked on the idea of literate
  74. programming. The inevitable result was that I designed and implemented
  75. my own version of Web --- FunnelWeb!
  76.  
  77. FunnelWeb is not the most sophisticated literate programming tool available,
  78. but it is an extremely \i{practical} tool, striving for simplicity
  79. and portability in all areas. Not only is FunnelWeb language-independent,
  80. and to some extent typesetter independent, but its implementation also
  81. stresses portability, being written in~C, and currently operating on four
  82. major platforms (Sun, Vax, PC, Mac). FunnelWeb allows the
  83. programmer total control over the output file, making it suitable
  84. for use with all sorts of format-sensitive languages. It also allows
  85. control over its own source code, which has been released under a
  86. GNU license.\xx{GNU}{license}
  87. FunnelWeb is quite solid, having to pass
  88. a regression testing suite of over 200 tests
  89. before being released. Finally, FunnelWeb is well documented by this manual
  90. which provides a tutorial, advanced hints, and a language definition.
  91.  
  92. I would like to dedicate FunnelWeb and this manual to Donald Knuth
  93. and his literate programming tool Web.
  94. Although this manual is somewhat critical of some aspects of
  95. Web, this criticism is really a product of differing design goals.
  96. Knuth designed a paradigm (literate programming) and a tool
  97. (Web) aimed at the highest pitch of program presentation and typesetting.
  98. FunnelWeb aims lower, relaxing constraints, and making compromises
  99. in order to achieve simplicity, flexibility, and portability.
  100. The result is a practical tool which I hope will attract more people to
  101. the literate style.
  102.  
  103. \bigskip
  104.  
  105. \leftline{\b{Ross~N.~Williams}}
  106. \leftline{\b{Adelaide, Australia}}
  107. \leftline{\b{May~1992}}
  108.  
  109. %==============================================================================
  110.  
  111. \pseudochapter{Acknowledgements}
  112. \x{acknowledgements}
  113.  
  114. Many thanks to \b{David Hulse}\xn{David}{Hulse}
  115. (\p{dave@cs.adelaide.edu.au}) for
  116. translating the original version of FunnelWeb
  117. (FunnelWeb~V1) from Ada\x{Ada} into~C
  118. and getting it to work on Unix and a PC.
  119. The C code written by David (FunnelWeb~V2) formed
  120. the basis of FunnelWeb~V3, but was
  121. entirely rewritten during the intensive refinement and feature-injection
  122. period leading up to this release (FunnelWeb~V3 is about three times
  123. the size of FunnelWeb~V2).
  124. Nevertheless, without this important first translation step,
  125. I would probably not have found the motivation to develop FunnelWeb to its
  126. present state.
  127.  
  128. Thanks go to \b{Simon Hackett}\xn{Simon}{Hackett}
  129. (\p{simon@internode.com.au}) of Internode Systems
  130. Pty Ltd for the use of his Sun, Mac, and PC, for assistance in porting
  131. FunnelWeb to the Sun and PC, and for helpful discussions.
  132.  
  133. Thanks go to \b{Jeremy Begg}\xn{Jeremy}{Begg}
  134. (\p{jeremy@vsm.com.au}) of VSM Software Services
  135. for the use of his VAX, and for assistance with the VMS-specific code.
  136.  
  137. Thanks to \b{Barry Dwyer}\xn{Barry}{Dwyer} (\p{dwyer@cs.adelaide.edu.au})
  138. and \b{Roger Brissenden}\xn{Roger}{Brissenden} (\p{rjb@koala.harvard.edu})
  139. for trying out FunnelWeb Version~1 in 1987 and providing valuable feedback.
  140.  
  141. Thanks to Donald Knuth\xn{Donald}{Knuth}
  142. for establishing the idea of literate programming in the first place.
  143.  
  144. \bigskip
  145.  
  146. \leftline{\b{Ross~N.~Williams}}
  147. \leftline{\b{Adelaide, Australia}}
  148. \leftline{\b{May~1992}}
  149.  
  150. %==============================================================================
  151.  
  152. \pseudochapter{Presentation Notes}
  153. \x{presentation notes}
  154.  
  155. \thing{References:} All references are set in bold and are
  156. cited in square brackets in the form
  157. \b{[}$<$\i{firstauthor}$><$\i{year}$>$\b{]}.
  158. All references cited in the text appear in the reference list and the index.
  159.  
  160. \thing{Special terms:} New or important terminology has been set in bold
  161. face and appears in the index. A glossary appears as an appendix.
  162.  
  163. \thing{Typesetting:} This\x{typesetting}
  164. document was prepared by the author using Andrew
  165. Trevorrow's\xn{Andrew}{Trevorrow} (\p{akt150@cscgpo.anu.edu.au})\checked{}
  166. implementation (OzTeX\x{OzTeX}) of the
  167. \TeX{}/\LaTeX{}\paper{Knuth84}\paper{Lamport86}\x{TeX}\x{LaTeX}
  168. typesetting system running on a Macintosh-SE.\x{Macintosh}
  169.  
  170. \thing{Graphics:} All diagrams have been constructed out of text using
  171. the \LaTeX{} \p{verbatim} environment so as to allow this document to
  172. be disseminated electronically and printed using \LaTeX{} without access
  173. to the author's drawing tools.
  174.  
  175. %%%%Put this paragraph back again if I insert any \fix footnotes again.
  176. %\thing{Correction footnotes:} Footnotes\x{footnotes}
  177. %commencing with dots ($\bullet$) are
  178. %notes to remind the author about something in the document that must be
  179. %attended to.\fix{This is an example of such a footnote.} These footnotes
  180. %will be attended to and eliminated in later versions.
  181.  
  182. \thing{Known typesetting problems:} While every attempt has been made
  183. to give a good presentation within the
  184. time available, some shortcuts have had to be taken. In particular, the author
  185. has
  186. been unable to work out how to get \LaTeX{} to suppress blank pages at the
  187. start of chapters.
  188.  
  189. %==============================================================================
  190.  
  191. % No abstract.
  192. %\pseudochapter{Abstract}
  193. %\x{abstract}
  194.  
  195. %==============================================================================%
  196. %                                End of Ch0.tex                                %
  197. %==============================================================================%
  198.