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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.
***********************************************************************
-->
<HEAD>
<TITLE>2.10 Document Structure Vs Macro Structure</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
BGCOLOR="#FFFFFF"
TEXT="#000000"
VLINK="#660000"
LINK="#FF0000"
ALINK="#CC0000">
<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
<FONT SIZE="2">
<BR>
<A HREF="http://www.ross.net/"
TARGET="rosshome"
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/rossnet_logo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="RossNet"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<A HREF="../index.shtml"
TARGET="funnelweb"
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
<IMG SRC="binary/linklogo.gif"
WIDTH="64" HEIGHT="32"
BORDER="0" ALT="FunnelWeb"
HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../reference/index.html"
TARGET="funnelwebreference"
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<BR>
<A HREF="../tutorial/index.html"
TARGET="funnelwebtutorial"
onClick="window.open('','funnelwebtutorial','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<A HREF="compile.html"><FONT COLOR="#FFFFFF">1 Compile</FONT></A><BR>
<A HREF="design.html"><FONT COLOR="#FFFFFF">2 Design</FONT></A><BR>
<A HREF="implement.html"><FONT COLOR="#FFFFFF">3 Implement</FONT></A><BR>
<A HREF="modify.html"><FONT COLOR="#FFFFFF">4 Modify</FONT></A><BR>
<A HREF="misc.html"><FONT COLOR="#FFFFFF">5 Misc</FONT></A><BR>
<A HREF="gpl.html"><FONT COLOR="#FFFFFF">6 Licence</FONT></A><BR>
<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>
</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">
<A HREF="index.html"><IMG SRC="binary/title.gif"
WIDTH="316" HEIGHT="24"
BORDER="0" ALT="FunnelWeb Developer Manual"
HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">2.10 Document Structure Vs Macro Structure</FONT><BR>
<P>Once the decision was made to adopt five levels of
headings as a document structure, the next issue was to
decide how this document structure would relate to the macro
structure. The issues to be addressed were as follows:
<P>
<UL>
<LI> How should the hierarchical structure connect to the macro structure?
<LI> How can backwards compatibility be achieved? Should it?
<LI> Should the macros be cross referenced by section or by definition?
<LI> Should nameless sections inherit macro names as headings?
<LI> Should TeX macros be used to structure the document?
</UL>
<P>This page contains some thoughts on these issues:
<P><BR><FONT SIZE="4"><STRONG>TeX File Document Basis</STRONG></FONT><BR>
<P>One idea is to make the
FunnelWeb input file an actual TeX <SAMP>.tex</SAMP> file
which is directly typesettable, and use FunnelWeb to
extract code from the TeX file to generate the product files.
This approach was rejected because it is too typesetter
dependent. Instead, the separate FunnelWeb format was adopted.
<P><BR><FONT SIZE="4"><STRONG>Hierarchical Heading Numbering</STRONG></FONT><BR>
<P>WEB and FunnelWeb V1 used two levels of section
headings, but numbered them all sequentially. This is
unacceptable in a fully hierarchical document which should
have hierarchical section numbers such as 3.2.4. So
FunnelWeb V3 uses hierarchical numbering for its
headings in the documentation file.
While hierarchical numbering is
good for headings, it is messy and confusing when applied to
macro names. In FunnelWeb V1's typeset output, each
macro call has appended in square brackets the number of the
section in which the macro is defined. However, hierarchical
numbering would be somewhat messy. For example, in the
typeset documentation, a macro call might look like.
<P><PRE>
Write out the output[6.7.4.3]
</PRE>
<P>Similarly, cross reference lists would be messy:
<P>
<PRE>
This macro is used in 3.4.5, 1.2, 7.8.9, 7.4, 2.2.1.1.
</PRE>
<P>These problems were solved by numbering headings
hierarchically and numbering the macros sequentially
and independently.
<P><BR><FONT SIZE="4"><STRONG>Input Format Matters Most</STRONG></FONT><BR>
<P>In terms of legacy commitment, the critical issue is
not how FunnelWeb formats programs for printing, but how the
FunnelWeb <SAMP>.fw</SAMP> input file should be formatted. The
typeset output can always be changed simply by fiddling with
FunnelWeb's Weave module. However, as soon as the input
syntax is defined, it will be used in dozens or hundreds of
documents and it will be very difficult indeed to change it.
Therefore, the important thing is to provide as sensible and
expressive a <SAMP>.fw</SAMP> format as possible.
<P>Thus, the issue of how to number headings and macros
in the typeset documentation is not a serious architectural
issue.
<P><BR><FONT SIZE="4"><STRONG>Naming Sections</STRONG></FONT><BR>
<P>How should sections be named? In many cases (especially
in the case of high-level sections) the writer will provide
an explicit name for a section. In other cases, provision of
such a name will merely duplicate the name of the macro
contained within the section. It therefore makes sense to
allow the user to omit the name from a section, allowing Weave
to name the section after the first macro definition in the
section. If a macro is unnamed and there is no macro in the
section, an error can be generated.
<P><BR><FONT SIZE="4"><STRONG>Summary</STRONG></FONT><BR>
<P>All these thoughts lead to the following scheme:
<P>
<UL>
<LI> Documents will be hierarchically structured using <SAMP>@A</SAMP>, <SAMP>@B</SAMP> etc.
<LI> Each section can be given a name <SAMP>@<...></SAMP>.
<LI> Sections that do not have names inherit the name of their first macro.
<LI> If a section does not have a name or a macro, it is erroneous.
<LI> Sections will be numbered hierarchically either by FunnelWeb or by TeX.
<LI> Macro body parts will be numbered sequentially by FunnelWeb and cross
referenced by these numbers.
</UL>
<P>All this results in a system which:
<P>
<UL>
<LI> Provides a hierarchical document structuring capability.
<LI> Is typesetter independent.
<LI> Does not require duplication between heading and macro names.
<LI> Separates the heading and macro systems so that Weave can be configured
at a later date to cross reference in different ways without requiring
input files to be reworked.
</UL>
<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left" VALIGN="bottom"><A HREF="design_numinst.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="design.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right" VALIGN="bottom"><A HREF="design_diagnostics.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
</TR>
</TABLE>
<P>
<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>
</FONT>
</TD>
</TR>
</TABLE>
</BODY>
<!-- *********************************************************************** -->
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
<!-- *********************************************************************** -->
</HTML>
|
