1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2
"http://www.w3.org/TR/REC-html40/loose.dtd">
6
***********************************************************************
7
FUNNELWEB MANUAL WEB PAGE
8
=========================
9
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.
11
Permission is granted to redistribute and use this manual in
12
any medium, with or without modification, provided that all
13
notices (including, without limitation, the copyright
14
notice, this permission notice, any record of modification,
15
and all legal notices) are preserved on all copies, that all
16
modifications are clearly marked, and that modified versions
17
are not represented as the original version unless all the
18
modifications since the manual's original release by Ross N.
19
Williams (www.ross.net) consist of translations or other
20
transformations that alter only the manual's form, not its
21
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
22
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
23
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
24
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
25
LAW THERE IS ABSOLUTELY NO WARRANTY.
27
***********************************************************************
31
<TITLE>2.3 Indentation</TITLE>
32
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
34
<BODY BACKGROUND="binary/background.gif"
43
<TD WIDTH="130" VALIGN="top">
44
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>
49
<A HREF="http://www.ross.net/"
51
onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
53
<IMG SRC="binary/rossnet_logo.gif"
54
WIDTH="64" HEIGHT="32"
55
BORDER="0" ALT="RossNet"
56
HSPACE="0" VSPACE="1"></A><BR>
59
<A HREF="../index.shtml"
61
onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
63
<IMG SRC="binary/linklogo.gif"
64
WIDTH="64" HEIGHT="32"
65
BORDER="0" ALT="FunnelWeb"
66
HSPACE="0" VSPACE="1"></A><BR>
68
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
69
<A HREF="../reference/index.html"
70
TARGET="funnelwebreference"
71
onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
72
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
74
<A HREF="../tutorial/index.html"
75
TARGET="funnelwebtutorial"
76
onClick="window.open('','funnelwebtutorial','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
77
><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
79
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
80
<A HREF="compile.html"><FONT COLOR="#FFFFFF">1 Compile</FONT></A><BR>
81
<A HREF="design.html"><FONT COLOR="#FFFFFF">2 Design</FONT></A><BR>
82
<A HREF="implement.html"><FONT COLOR="#FFFFFF">3 Implement</FONT></A><BR>
83
<A HREF="modify.html"><FONT COLOR="#FFFFFF">4 Modify</FONT></A><BR>
84
<A HREF="misc.html"><FONT COLOR="#FFFFFF">5 Misc</FONT></A><BR>
85
<A HREF="gpl.html"><FONT COLOR="#FFFFFF">6 Licence</FONT></A><BR>
88
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
94
<TD WIDTH="360" VALIGN="top">
98
<A HREF="index.html"><IMG SRC="binary/title.gif"
99
WIDTH="316" HEIGHT="24"
100
BORDER="0" ALT="FunnelWeb Developer Manual"
101
HSPACE="0" VSPACE="0"></A>
102
<P><FONT SIZE="5">2.3 Indentation</FONT><BR>
107
<P>How should FunnelWeb insert the text of macros that are
108
not called in column one? A macro call that does not appear
109
at the left margin is called an <STRONG>indented macro
110
call</STRONG> and suggests three different alternatives for
111
its expansion: <STRONG>no indentation</STRONG>,
112
<STRONG>blank indentation</STRONG>, and <STRONG>text
113
indentation</STRONG>. Here are examples of each kind of
114
indentation. First the example problem.
118
@$@<Sloth@>==@{@-
122
@O@<Output@>==@{@-
129
<P>There are three ways that the second line of the
130
<SAMP>Sloth</SAMP> macro can be indented in the product file.
133
<STRONG>No indentation:</STRONG>
141
<STRONG>Blank indentation:</STRONG>
149
<STRONG>Text indentation:</STRONG>
156
<P>No indentation is useful where the user wishes to view
157
the output as a pure byte stream. Blank
158
indentation is useful when the user wishes to generate
159
indented computer programs. Text indentation is useful where
160
the user wishes to prefix each line of an entire macro
161
invocation with a string. This can be useful for commenting
162
out code (e.g. in Ada using <SAMP>--</SAMP>), and for
163
prepending constructs such as a dollar sign at the start of each
164
line in an OpenVMS DCL script command file.
166
<P>The design questions are as follows:
170
<LI> Which of the three kinds of indentation should FunnelWeb support?
171
<LI> What should be the granularity of swapping between indentation modes?
172
<LI> Are particular indentation modes dangerous?
173
<LI> Is the presence of particular combinations of indentation modes
174
confusing to the user?
175
<LI> How and when should the choice of indentation be specified?
178
<P>After a lot of thought, it was decided that the factor
179
that should determine the design is the <I>clarity</I> in
180
the user's mind of the indentation facility, and the
181
<I>danger</I> associated with misunderstanding it. Here
182
are two examples that show how easily a misunderstanding about
183
the indentation model can cause a serious semantic error:
187
--Misuse of blank (and no) indentation.
191
<P>In this first example, the user has assumed that text
192
indentation is in action and has placed an Ada comment
193
symbol "<TT>--</TT>" before the invocation of the macro
194
<SAMP>@<Sloth@></SAMP> in the expectation that every
195
line in the expansion of the macro will be prefixed by
196
"<TT>--</TT>". Unfortunately, if no-indentation or
197
blank-indentation is active, only the first statement of the
198
expansion of macro <SAMP>@<Sloth@></SAMP> will be
203
--Misuse of text indentation:
207
<P>In this second example, the user has assumed
208
no-indentation or blank-indentation and has placed the call
209
to <SAMP>@<Sloth@></SAMP> after the incrementing of
210
variable <SAMP>a</SAMP>. Under a text-indentation mode, this
211
will result in the statement "<TT>a++;</TT>" appearing at
212
the start of each line in the macro expansion!
214
<P>These examples show that confusion about the
215
indentation model could cause a serious semantic problem in
216
a program written using FunnelWeb. In particular, the
217
examples above pose a dilemma because they are symmetric.
218
One cannot simply pin the blame on one particular
219
indentation form. A little thought reveals that the greatest
220
danger lies in <I>confusion</I> in the user's mind. If the
221
user is confused between text or blank indenting, problems
224
<P>There seems to be two ways to solve the problem. The
225
first is to ban all macro calls that are preceded by
226
non-blank text. This is not a good option because there are
227
so many cases where it is desirable to expand more than one
228
single line macro on the same line. A second option is to
229
eliminate one of the two forms so as to reduce the potential
230
for confusion in the user's mind. I choose the latter
231
option. Of the three forms, the clear choice for elimination
232
is text indenting for the following reasons:
236
<LI> It actually introduces extra text which gives it an a priori
237
potential for problems.
238
<LI> It is harder to implement and would slow down Tangle.
241
<P>The only other decision is the level of granularity of
242
choice between the remaining options: no indentation and
243
blank indentation. FunnelWeb V1 allowed this choice to
244
be made in the command line, but this was a bad choice
245
because it made the user responsible for a portion of the
246
file's semantics. A better system, used in FunnelWeb V3,
247
is to allow the user to specify the indentation mode in the
250
<P>Again, to avoid confusion, it seems sensible to allow
251
the user only one indentation mode per FunnelWeb input file.
252
In most cases, the user will be happy with blank indentation
253
(the default) and there will be no need for change anyway.
255
<P><B>Decision:</B> Implement only "no
256
indentation" and "blank indentation". Make the
257
choice of indentation a static attribute of a particular
258
FunnelWeb run that is specified in the input file.
264
<TD ALIGN="left" VALIGN="bottom"><A HREF="design_motivation.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
265
<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>
266
<TD ALIGN="right" VALIGN="bottom"><A HREF="design_syntax.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
275
<A HREF="mailto:webmaster@ross.net">Webmaster</A>
276
<A HREF="copyright.html">Copyright © Ross N. Williams 1992,1999. All rights reserved.</A><BR>
287
<!-- *********************************************************************** -->
288
<!-- End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/) -->
289
<!-- *********************************************************************** -->
added
removed
developer/design_indentation.html
