2.3 Indentation

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 indented macro call and suggests three different alternatives for its expansion: no indentation, blank indentation, and text indentation. Here are examples of each kind of indentation. First the example problem.

@$@<Sloth@>==@{@-
Aardvark
Walrus@}

@O@<Output@>==@{@-
Zebra@<Sloth@>
Giraffe
@}

There are three ways that the second line of the Sloth macro can be indented in the product file.

No indentation:

     ZebraAardvark
     Walrus
     Giraffe

Blank indentation:

     ZebraAardvark
          Walrus
     Giraffe

Text indentation:

     ZebraAardvark
     ZebraWalrus
     Giraffe

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 --), and for prepending constructs such as a dollar sign at the start of each line in an OpenVMS DCL script command file.

The design questions are as follows:

1. Which of the three kinds of indentation should FunnelWeb support?
2. What should be the granularity of swapping between indentation modes?
3. Are particular indentation modes dangerous?
4. Is the presence of particular combinations of indentation modes confusing to the user?
5. How and when should the choice of indentation be specified?

After a lot of thought, it was decided that the factor that should determine the design is the clarity  in the user's mind of the indentation facility, and the danger  associated with misunderstanding it. Here are two examples that show how easily a misunderstanding about the indentation model can cause a serious semantic error:

--Misuse of blank (and no) indentation.
--@<Sloth@>

In this first example, the user has assumed that text indentation is in action and has placed an Ada comment symbol "--" before the invocation of the macro @<Sloth@> in the expectation that every line in the expansion of the macro will be prefixed by "--". Unfortunately, if no-indentation or blank-indentation is active, only the first statement of the expansion of macro @<Sloth@> will be commented out.

--Misuse of text indentation:
a++; @<Sloth@>

In this second example, the user has assumed no-indentation or blank-indentation and has placed the call to @<Sloth@> after the incrementing of variable a. Under a text-indentation mode, this will result in the statement "a++;" appearing at the start of each line in the macro expansion!

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 confusion  in the user's mind. If the user is confused between text or blank indenting, problems will arise.

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:

1. It actually introduces extra text which gives it an a priori potential for problems.
2. It is harder to implement and would slow down Tangle.

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.

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.

Decision: 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.