summaryrefslogtreecommitdiff
path: root/web/funnelAC/userman/u_manual.toc
blob: b359e8fa3e9748ed49b136fbb4a29dc3b4c9e472 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
\contentsline {chapter}{Preface}{9}
\contentsline {chapter}{Acknowledgements}{11}
\contentsline {chapter}{Presentation Notes}{13}
\contentsline {chapter}{\numberline {1}A Tutorial Introduction}{15}
\contentsline {section}{\numberline {1.1}What is Literate Programming?}{15}
\contentsline {section}{\numberline {1.2}What is FunnelWeb?}{18}
\contentsline {section}{\numberline {1.3}The Name FunnelWeb}{19}
\contentsline {section}{\numberline {1.4}A FunnelWeb Tutorial}{19}
\contentsline {section}{\numberline {1.5}A Hello World Document}{20}
\contentsline {section}{\numberline {1.6}Macro Facilities}{22}
\contentsline {subsection}{\numberline {1.6.1}Simple Macros}{22}
\contentsline {subsection}{\numberline {1.6.2}Number of Times Called}{23}
\contentsline {subsection}{\numberline {1.6.3}Indentation}{25}
\contentsline {subsection}{\numberline {1.6.4}Additive Macros}{26}
\contentsline {subsection}{\numberline {1.6.5}Parameterized Macros}{28}
\contentsline {subsection}{\numberline {1.6.6}Macro Expansion}{30}
\contentsline {subsection}{\numberline {1.6.7}Include Files}{30}
\contentsline {section}{\numberline {1.7}Typesetting Facilities}{32}
\contentsline {subsection}{\numberline {1.7.1}Overview}{32}
\contentsline {subsection}{\numberline {1.7.2}Typesetter Independence}{34}
\contentsline {subsection}{\numberline {1.7.3}Hierarchical Structure}{34}
\contentsline {subsection}{\numberline {1.7.4}Understanding the Printed Documentation}{35}
\contentsline {subsection}{\numberline {1.7.5}Literals and Emphasis}{37}
\contentsline {subsection}{\numberline {1.7.6}Adding a Header Page}{37}
\contentsline {subsection}{\numberline {1.7.7}Comments}{37}
\contentsline {section}{\numberline {1.8}A Complete Example}{38}
\contentsline {section}{\numberline {1.9}Summary}{39}
\contentsline {chapter}{\numberline {2}FunnelWeb Hints}{41}
\contentsline {section}{\numberline {2.1}Macro Names}{41}
\contentsline {section}{\numberline {2.2}Quick Names}{42}
\contentsline {section}{\numberline {2.3}FunnelWeb the Martinet}{42}
\contentsline {section}{\numberline {2.4}Fiddling With End of Lines}{43}
\contentsline {section}{\numberline {2.5}Fudging Conditionals}{44}
\contentsline {section}{\numberline {2.6}Changing the Strength of Headings}{46}
\contentsline {section}{\numberline {2.7}Efficiency Notes}{47}
\contentsline {section}{\numberline {2.8}Interactive Mode}{47}
\contentsline {section}{\numberline {2.9}Setting Up Default Options}{49}
\contentsline {section}{\numberline {2.10}FunnelWeb and Make}{49}
\contentsline {section}{\numberline {2.11}The Dangers of FunnelWeb}{50}
\contentsline {section}{\numberline {2.12}Wholistic Debugging}{53}
\contentsline {section}{\numberline {2.13}Examples of FunnelWeb Applications}{53}
\contentsline {subsection}{\numberline {2.13.1}Analyzing the Monster Postscript Header File}{54}
\contentsline {subsection}{\numberline {2.13.2}Making Ada ADTs more A}{55}
\contentsline {subsection}{\numberline {2.13.3}Multiple Language Systems}{55}
\contentsline {subsection}{\numberline {2.13.4}The Case of the Small Function}{56}
\contentsline {subsection}{\numberline {2.13.5}When Comments are Bad}{57}
\contentsline {subsection}{\numberline {2.13.6}Documents That Share Text}{58}
\contentsline {subsection}{\numberline {2.13.7}Generics}{59}
\contentsline {section}{\numberline {2.14}Summary}{62}
\contentsline {chapter}{\numberline {3}FunnelWeb Definition}{63}
\contentsline {section}{\numberline {3.1}Introduction}{63}
\contentsline {section}{\numberline {3.2}Notation}{63}
\contentsline {section}{\numberline {3.3}Terminology}{63}
\contentsline {section}{\numberline {3.4}An Architectural Overview}{64}
\contentsline {section}{\numberline {3.5}Diagnostics}{65}
\contentsline {section}{\numberline {3.6}Typesetter Independence}{65}
\contentsline {section}{\numberline {3.7}Command Line Interface}{66}
\contentsline {subsection}{\numberline {3.7.1}Invoking FunnelWeb}{66}
\contentsline {subsection}{\numberline {3.7.2}Command Line Arguments}{67}
\contentsline {subsection}{\numberline {3.7.3}Options}{68}
\contentsline {section}{\numberline {3.8}File Name Inheritance}{70}
\contentsline {section}{\numberline {3.9}FunnelWeb Startup}{70}
\contentsline {section}{\numberline {3.10}Scanner}{71}
\contentsline {subsection}{\numberline {3.10.1}Basic Input File Processing}{71}
\contentsline {subsection}{\numberline {3.10.2}Special Sequences}{72}
\contentsline {subsection}{\numberline {3.10.3}Setting the Special Character}{74}
\contentsline {subsection}{\numberline {3.10.4}Inserting the Special Character into the Text}{74}
\contentsline {subsection}{\numberline {3.10.5}Inserting Arbitrary Characters into the Text}{74}
\contentsline {subsection}{\numberline {3.10.6}Comments}{75}
\contentsline {subsection}{\numberline {3.10.7}Quick Names}{76}
\contentsline {subsection}{\numberline {3.10.8}Inserting End of Line Markers}{76}
\contentsline {subsection}{\numberline {3.10.9}Suppressing End of Line Markers}{77}
\contentsline {subsection}{\numberline {3.10.10}Include Files}{77}
\contentsline {subsection}{\numberline {3.10.11}Pragmas}{78}
\contentsline {subsubsection}{\numberline {3.10.11.1}Indentation}{78}
\contentsline {subsubsection}{\numberline {3.10.11.2}Maximum Input Line Length}{79}
\contentsline {subsubsection}{\numberline {3.10.11.3}Maximum Output File Line Length}{79}
\contentsline {subsubsection}{\numberline {3.10.11.4}Typesetter}{80}
\contentsline {subsection}{\numberline {3.10.12}Freestanding Typesetter Directives}{81}
\contentsline {subsubsection}{\numberline {3.10.12.1}New Page}{81}
\contentsline {subsubsection}{\numberline {3.10.12.2}Table of Contents}{81}
\contentsline {subsubsection}{\numberline {3.10.12.3}Vertical Skip}{81}
\contentsline {subsubsection}{\numberline {3.10.12.4}Title}{82}
\contentsline {subsection}{\numberline {3.10.13}Scanner/Parser Interface}{82}
\contentsline {section}{\numberline {3.11}Parser}{82}
\contentsline {subsection}{\numberline {3.11.1}High Level Structure}{82}
\contentsline {subsection}{\numberline {3.11.2}Free Text}{83}
\contentsline {subsection}{\numberline {3.11.3}Typesetter Directives}{83}
\contentsline {subsubsection}{\numberline {3.11.3.1}Section}{83}
\contentsline {subsubsection}{\numberline {3.11.3.2}Literal Directive}{84}
\contentsline {subsubsection}{\numberline {3.11.3.3}Emphasis Directive}{85}
\contentsline {subsection}{\numberline {3.11.4}Macros}{85}
\contentsline {subsubsection}{\numberline {3.11.4.1}Names}{86}
\contentsline {subsubsection}{\numberline {3.11.4.2}Formal Parameter Lists}{86}
\contentsline {subsection}{\numberline {3.11.5}Expressions}{86}
\contentsline {subsection}{\numberline {3.11.6}Macro Calls}{86}
\contentsline {subsection}{\numberline {3.11.7}Formal Parameters}{87}
\contentsline {subsection}{\numberline {3.11.8}Macros are Static}{87}
\contentsline {section}{\numberline {3.12}Analyser}{88}
\contentsline {section}{\numberline {3.13}Tangle}{88}
\contentsline {section}{\numberline {3.14}Weave}{89}
\contentsline {subsection}{\numberline {3.14.1}Target Typesetter}{89}
\contentsline {subsection}{\numberline {3.14.2}Cross Reference Numbering}{89}
\contentsline {section}{\numberline {3.15}FunnelWeb Shell}{90}
\contentsline {subsection}{\numberline {3.15.1}Introduction}{90}
\contentsline {subsection}{\numberline {3.15.2}Return Statuses}{90}
\contentsline {subsection}{\numberline {3.15.3}Command Line Length}{91}
\contentsline {subsection}{\numberline {3.15.4}String Substitution}{91}
\contentsline {subsection}{\numberline {3.15.5}How a Command Line is Processed}{92}
\contentsline {subsection}{\numberline {3.15.6}Options}{92}
\contentsline {subsection}{\numberline {3.15.7}Shell Commands}{93}
\contentsline {subsubsection}{\numberline {3.15.7.1}Absent}{93}
\contentsline {subsubsection}{\numberline {3.15.7.2}Codify}{93}
\contentsline {subsubsection}{\numberline {3.15.7.3}Compare}{93}
\contentsline {subsubsection}{\numberline {3.15.7.4}Define}{94}
\contentsline {subsubsection}{\numberline {3.15.7.5}Diff}{94}
\contentsline {subsubsection}{\numberline {3.15.7.6}Diffsummary}{95}
\contentsline {subsubsection}{\numberline {3.15.7.7}Diffzero}{95}
\contentsline {subsubsection}{\numberline {3.15.7.8}Eneo}{95}
\contentsline {subsubsection}{\numberline {3.15.7.9}Execute}{96}
\contentsline {subsubsection}{\numberline {3.15.7.10}Exists}{96}
\contentsline {subsubsection}{\numberline {3.15.7.11}Fixeols}{96}
\contentsline {subsubsection}{\numberline {3.15.7.12}Fw}{97}
\contentsline {subsubsection}{\numberline {3.15.7.13}Help}{97}
\contentsline {subsubsection}{\numberline {3.15.7.14}Here}{98}
\contentsline {subsubsection}{\numberline {3.15.7.15}Quit}{98}
\contentsline {subsubsection}{\numberline {3.15.7.16}Set}{98}
\contentsline {subsubsection}{\numberline {3.15.7.17}Show}{98}
\contentsline {subsubsection}{\numberline {3.15.7.18}Skipto}{98}
\contentsline {subsubsection}{\numberline {3.15.7.19}Status}{99}
\contentsline {subsubsection}{\numberline {3.15.7.20}Tolerate}{100}
\contentsline {subsubsection}{\numberline {3.15.7.21}Trace}{100}
\contentsline {subsubsection}{\numberline {3.15.7.22}Write}{100}
\contentsline {subsubsection}{\numberline {3.15.7.23}Writeu}{100}
\contentsline {section}{\numberline {3.16}Concluding Remarks}{100}
\contentsline {chapter}{\numberline {4}FunnelWeb Installation}{101}
\contentsline {section}{\numberline {4.1}Obtaining a Copy of FunnelWeb}{101}
\contentsline {section}{\numberline {4.2}Establishing The Directory Tree}{102}
\contentsline {subsection}{\numberline {4.2.1}Admin Directory}{102}
\contentsline {subsection}{\numberline {4.2.2}Answers Directory}{102}
\contentsline {subsection}{\numberline {4.2.3}Hackman Directory}{103}
\contentsline {subsection}{\numberline {4.2.4}Results Directory}{103}
\contentsline {subsection}{\numberline {4.2.5}Scripts Directory}{103}
\contentsline {subsection}{\numberline {4.2.6}Sources Directory}{103}
\contentsline {subsection}{\numberline {4.2.7}Tests Directory}{104}
\contentsline {subsection}{\numberline {4.2.8}Userman Directory}{105}
\contentsline {section}{\numberline {4.3}Compiling FunnelWeb}{105}
\contentsline {section}{\numberline {4.4}Testing FunnelWeb}{105}
\contentsline {section}{\numberline {4.5}Installing FunnelWeb}{106}
\contentsline {section}{\numberline {4.6}Printing Manuals}{107}
\contentsline {section}{\numberline {4.7}Installation Problems?}{107}
\contentsline {chapter}{\numberline {5}FunnelWeb Administration}{109}
\contentsline {section}{\numberline {5.1}Introduction}{109}
\contentsline {section}{\numberline {5.2}The User's Commitment To FunnelWeb}{109}
\contentsline {section}{\numberline {5.3}Documentation}{110}
\contentsline {section}{\numberline {5.4}Registration}{110}
\contentsline {section}{\numberline {5.5}Support}{110}
\contentsline {section}{\numberline {5.6}Copyright}{112}
\contentsline {section}{\numberline {5.7}Nowarranty}{112}
\contentsline {section}{\numberline {5.8}Distribution}{113}
\contentsline {section}{\numberline {5.9}Modification}{113}
\contentsline {section}{\numberline {5.10}Versions}{114}
\contentsline {section}{\numberline {5.11}FTP Archive and Author}{114}
\contentsline {chapter}{\numberline {A}Glossary}{115}
\contentsline {chapter}{\numberline {B}References}{117}
\contentsline {chapter}{Index}{117}