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
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
|
<!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.3 Indentation</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.3 Indentation</FONT><BR>
<P>How should FunnelWeb insert the text of macros that are
not called in column one? A macro call that does not appear
at the left margin is called an <STRONG>indented macro
call</STRONG> and suggests three different alternatives for
its expansion: <STRONG>no indentation</STRONG>,
<STRONG>blank indentation</STRONG>, and <STRONG>text
indentation</STRONG>. Here are examples of each kind of
indentation. First the example problem.
<P>
<PRE>
@$@<Sloth@>==@{@-
Aardvark
Walrus@}
@O@<Output@>==@{@-
Zebra@<Sloth@>
Giraffe
@}
</PRE>
<P>There are three ways that the second line of the
<SAMP>Sloth</SAMP> macro can be indented in the product file.
<P>
<STRONG>No indentation:</STRONG>
<PRE>
ZebraAardvark
Walrus
Giraffe
</PRE>
<P>
<STRONG>Blank indentation:</STRONG>
<PRE>
ZebraAardvark
Walrus
Giraffe
</PRE>
<P>
<STRONG>Text indentation:</STRONG>
<PRE>
ZebraAardvark
ZebraWalrus
Giraffe
</PRE>
<P>No indentation is useful where the user wishes to view
the output as a pure byte stream. Blank
indentation is useful when the user wishes to generate
indented computer programs. Text indentation is useful where
the user wishes to prefix each line of an entire macro
invocation with a string. This can be useful for commenting
out code (e.g. in Ada using <SAMP>--</SAMP>), and for
prepending constructs such as a dollar sign at the start of each
line in an OpenVMS DCL script command file.
<P>The design questions are as follows:
<P>
<OL>
<LI> Which of the three kinds of indentation should FunnelWeb support?
<LI> What should be the granularity of swapping between indentation modes?
<LI> Are particular indentation modes dangerous?
<LI> Is the presence of particular combinations of indentation modes
confusing to the user?
<LI> How and when should the choice of indentation be specified?
</OL>
<P>After a lot of thought, it was decided that the factor
that should determine the design is the <I>clarity</I> in
the user's mind of the indentation facility, and the
<I>danger</I> associated with misunderstanding it. Here
are two examples that show how easily a misunderstanding about
the indentation model can cause a serious semantic error:
<P>
<PRE>
--Misuse of blank (and no) indentation.
--@<Sloth@>
</PRE>
<P>In this first example, the user has assumed that text
indentation is in action and has placed an Ada comment
symbol "<TT>--</TT>" before the invocation of the macro
<SAMP>@<Sloth@></SAMP> in the expectation that every
line in the expansion of the macro will be prefixed by
"<TT>--</TT>". Unfortunately, if no-indentation or
blank-indentation is active, only the first statement of the
expansion of macro <SAMP>@<Sloth@></SAMP> will be
commented out.
<P>
<PRE>
--Misuse of text indentation:
a++; @<Sloth@>
</PRE>
<P>In this second example, the user has assumed
no-indentation or blank-indentation and has placed the call
to <SAMP>@<Sloth@></SAMP> after the incrementing of
variable <SAMP>a</SAMP>. Under a text-indentation mode, this
will result in the statement "<TT>a++;</TT>" appearing at
the start of each line in the macro expansion!
<P>These examples show that confusion about the
indentation model could cause a serious semantic problem in
a program written using FunnelWeb. In particular, the
examples above pose a dilemma because they are symmetric.
One cannot simply pin the blame on one particular
indentation form. A little thought reveals that the greatest
danger lies in <I>confusion</I> in the user's mind. If the
user is confused between text or blank indenting, problems
will arise.
<P>There seems to be two ways to solve the problem. The
first is to ban all macro calls that are preceded by
non-blank text. This is not a good option because there are
so many cases where it is desirable to expand more than one
single line macro on the same line. A second option is to
eliminate one of the two forms so as to reduce the potential
for confusion in the user's mind. I choose the latter
option. Of the three forms, the clear choice for elimination
is text indenting for the following reasons:
<P>
<OL>
<LI> It actually introduces extra text which gives it an a priori
potential for problems.
<LI> It is harder to implement and would slow down Tangle.
</OL>
<P>The only other decision is the level of granularity of
choice between the remaining options: no indentation and
blank indentation. FunnelWeb V1 allowed this choice to
be made in the command line, but this was a bad choice
because it made the user responsible for a portion of the
file's semantics. A better system, used in FunnelWeb V3,
is to allow the user to specify the indentation mode in the
input file itself.
<P>Again, to avoid confusion, it seems sensible to allow
the user only one indentation mode per FunnelWeb input file.
In most cases, the user will be happy with blank indentation
(the default) and there will be no need for change anyway.
<P><B>Decision:</B> Implement only "no
indentation" and "blank indentation". Make the
choice of indentation a static attribute of a particular
FunnelWeb run that is specified in the input file.
<P>
<TABLE WIDTH="100%">
<TR>
<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>
<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_syntax.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>
|
