FunnelWeb Tutorial Manual

FunnelWeb Tutorial Manual Version 3.2d (9 Jan 2000) for FunnelWeb V3.2 THIS TUTORIAL MANUAL provides a friendly introduction to the FunnelWeb literate programmingReference preprocessor Developer This Tutorial Manual does not provide a definitive description of FunnelWeb, so if you have a specific technical question, you Tutorial should refer to the FunnelWeb Reference Manual, which is 1 Introduction definitive. To perform a keyword search of the Reference 2 Macros Manual and/or this Tutorial manual, click on SEARCH in the 3 Typesetting margin. 4 Example 1 Introduction5 Hints 6 Examples 1.1 What Is Literate Programming? 7 Webmaking 1.2 What Is FunnelWeb? 1.3 The Name FunnelWeb SEARCH 1.4 Using These Tutorials 1.5 A Hello World Document 2 Macro Facilities Tutorial 2.1 Simple Macros 2.2 Number of Times Called 2.3 Indentation 2.4 Additive Macros 2.5 Parameterized Macros 2.6 Library Macros 2.7 Macro Expansion 2.8 Include Files 3 Typesetting Facilities Tutorial 3.1 Overview 3.2 Typesetter Independence 3.3 Hierarchical Structure 3.4 Understanding the Printed Documentation 3.5 Literals and Emphasis 3.6 Adding A Header Page 3.7 Comments http://www.ross.net/funnelweb/tutorial/index.html (1 of 3) [3/3/2000 9:38:03 PM]FunnelWeb Tutorial Manual 4 A Complete Example 5 FunnelWeb Hints 5.1 Macro Names 5.2 Quick Names 5.3 FunnelWeb the Martinet 5.4 Fiddling With End of Lines 5.5 Fudging Conditionals 5.6 Changing the Strength of Headings 5.7 Efficiency Notes 5.8 Interactive Mode 5.9 Setting Up Default Options 5.10 FunnelWeb and Make 5.11 The Dangers Of FunnelWeb 5.12 Wholistic Debugging 5.13 TABs 5.14 HTML Style 5.15 A FunnelWeb Mode For Emacs 6 Examples of FunnelWeb Applications 6.1 Analyzing the Monster Postscript Header File 6.2 Making Ada ADTs More Abstract 6.3 Multiple Language Systems 6.4 The Case of the Small Function 6.5 When Comments are Bad 6.6 Documents That Share Text 6.7 Generics 7 Making Webs With FunnelWeb 7.1 Introduction 7.2 Getting Started 7.3 Replacing Messy HTML Constructs 7.4 Avoiding Errors And Inconsistencies 7.5 Defining A Consistent Style 7.6 Defining Macro Libraries 7.7 Parameterizing Entire Webs 7.8 Hints And Conventions Webmaster Copyright © Ross N. Williams 1992,1999. All rights reserved. http://www.ross.net/funnelweb/tutorial/index.html (2 of 3) [3/3/2000 9:38:03 PM]1 Introduction 1 Introduction 1.1 What Is Literate Programming? 1.2 What Is FunnelWeb? 1.3 The Name FunnelWebReference 1.4 Using These Tutorials 1.5 A Hello World DocumentDeveloper Tutorial 1 Introduction Webmaster Copyright © Ross N. Williams 1992,1999. All rights2 Macros reserved.3 Typesetting 4 Example 5 Hints 6 Examples 7 Webmaking SEARCH http://www.ross.net/funnelweb/tutorial/intro.html [3/3/2000 9:38:16 PM]1.1 What Is Literate Programming? 1.1 What Is Literate Programming? A traditional computer program consists of a text file containing program code. Scattered in amongst the program code are comments which describe the various parts of the code.Reference In literate programming the emphasis is reversed. Instead of writing code Developer containing documentation, the literate programmer writes documentation containing code. No longer does the English commentary injected into a Tutorial program have to be hidden in comment delimiters at the top of the file, or under 1 Introduction procedure headings, or at the end of lines. Instead, it is wrenched into the daylight and made the main focus. The "program" then becomes primarily a2 Macros document directed at humans, with the code being herded between "code3 Typesetting delimiters" from where it can be extracted and shuffled out sideways to the4 Example language system by literate programming tools. 5 Hints 6 Examples The effect of this simple shift of emphasis can be so profound as to change one's whole approach to programming. Under the literate programming paradigm, the7 Webmaking central activity of programming becomes that of conveying meaning to other intelligent beings rather than merely convincing the computer to behave in aSEARCH particular way. It is the difference between performing and exposing a magic trick. In order to program in a literate style, particular tools are required. The traditional approach (used in the FunnelWeb system) is to have some sort of text-file-in/text-file-out utility that reads a literate program (containing a program commentary peppered with scraps of program text) and writes out a file containing all the program code and a file containing typesetter commands representing the entire input document, documentation, code, and all. See the diagram below. +-----------------------------------------+ | File containing the program description | | peppered with scraps of program code. | | This is what the programmer works on. | | (e.g. sloth.web) | | v o---------------------------o | Literate Programming Tool | http://www.ross.net/funnelweb/tutorial/intro_what.html (1 of 4) [3/3/2000 9:44:55 PM]1.1 What Is Literate Programming? +------------+-------------+ | | v v +------------------+ +--------------------------+ | Traditional | | Documentation file | | Computer Program | | (e.g. sloth.tex) | | (e.g. sloth.c) | | (e.g. sloth.html) | Traditional architecture of literate programming tools. Literate programming tools could be organized in a number of ways. However, to fit in with current file and command line based environments, most tools conform to the traditional architecture shown here in which the user feeds in a file containing a literate program, and the literate programming utility generates program files and a documentation file. Given the coming age of hypertext systems, this is probably not the best approach. However, it does mesh beautifully with current text files and command line interfaces, the expectation of linear presentations in the documents we read, and the particular requirements of current programming languages and typesetting systems. It is certainly not a bad approach. With this structure in place, the literate programming system can provide far more than just a reversal of the priority of comments and code. In its full blown form, a good literate programming facility can provide total support for the essential thrust of literate programming, which is that computer programs should be written more for the human reader than for the compiler. In particular, a literate programming system can provide: Re-ordering of code: Programming languages often force the programmer to give the various parts of a computer program in a particular order. For example, the Pascal programming language[BSI82] imposes the ordering: constants, types, variables, procedures, code. Pascal also requires that procedures appear in an order consistent with the partial ordering imposed by the static call graph (but forward declarations allow this to be bypassed). In contrast, the literate style requires that the programmer be free to present the computer program in any order whatsoever. The facility to do this is implemented in literate programming tools by providing text macros that can be defined and used in any order. Typeset code and documentation: Traditionally program listings are dull affairs consisting of pages of fan-form paper imprinted with meandering coastlines of structured text in a boring font. In contrast, literate programming systems are capable of producing documentation that is superior in two ways. First, because most of the documentation text is fed straight to the typesetter, the programmer can make use of all the power of the underlying http://www.ross.net/funnelweb/tutorial/intro_what.html (2 of 4) [3/3/2000 9:44:55 PM]1.1 What Is Literate Programming? typesetter, resulting in documentation that has the same presentation as an ordinary typeset document. Second, because the literate programming utility sees all the code, it can use its knowledge of the programming language and the features of the typesetting language to typeset the program code as if it were appearing in a technical journal. It is the difference between: while sloth