diff options
Diffstat (limited to 'doc/design/s5_1')
| -rw-r--r-- | doc/design/s5_1 | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/doc/design/s5_1 b/doc/design/s5_1 new file mode 100644 index 0000000..ab65bb9 --- /dev/null +++ b/doc/design/s5_1 @@ -0,0 +1,123 @@ +@SubSection + @Tag { galleys } + @Title { The galley abstraction } +@Begin +@PP +Let us take the footnote as a representative example. At some point in +the document, we wish to write +@ID @OneRow @Code { +"preceding text" +"@FootNote { footnote text }" +"following text" +} +and we expect the formatter to remove the footnote from this context and +place it at the bottom of the current page, possibly splitting some or +all of it onto a following page if space is insufficient. +@PP +An object appears in the final document at the point it is invoked, but +this basic property does not hold for footnotes: the point of +invocation and the point of appearance are different. In some way, the +footnote is attached to the document at both points, introducing a cross +linking (Section {@NumberOf genesis}) that cannot be described in purely +functional terms. +@PP +Since the interpretation of any object depends on an environment and +style inherited from the context, the first question must be whether +the footnote inherits them through the invocation point or through +the point(s) of appearance. +@PP +If symbols are to be interpreted statically as heretofore, then environments +must be inherited through the invocation point alone. Dynamic inheritance +through the point of appearance is enticing in some ways: it might +replace the body parameter, and it might help with automatic numbering, +since the number of a footnote is known only at the point of appearance; +but the implementation problems are severe, and static inheritance seems +much simpler and more comprehensible to the user. Style, at least its +available width and height part, must of necessity be inherited through +the point of appearance. For consistency, the entire style should be +inherited in this way. There is a suggestive analogy here with actual +parameters, which have a point of invocation from which they inherit an +environment, and a point of appearance within the body of the enclosing +definition, from which they inherit a style. It may be possible to treat +a footnote as the actual parameter of some symbol, therefore, although +the details seem very obscure. +@PP +But the most profound consequence of having two types of attachment +point is that it leads to two distinctive tree structures. Considering +invocation points only leads to static trees like this one: +@ID @I @Fig margin { 0.3c } { @Tree { +@Node @Ellipse { body text } +@LeftSub { @Node @Ellipse footnote } +@RightSub { + @Node @Ellipse figure + @FirstSub { @Node @Ellipse footnote } +} +}} +which shows that the body text contains a footnote and a figure, the +latter itself containing a footnote. Considering points of appearance +only gives a completely different, dynamic tree: +@ID @I @Fig margin { 0.3c } { @Tree { +@Node @Ellipse { sequence of pages } +@FirstSub { @Node @Ellipse { body text } } +@NextSub { @Node @Ellipse { footnote } } +@NextSub { @Node @Ellipse { figure } } +@NextSub { @Node @Ellipse { footnote } } +}} +The tree can be deeper, for example with sections appearing within +chapters which appear within the body text, which appears within the +final sequence of pages. Document formatting languages generally shirk +the issues raised by this dual tree structure, by making the dynamic +tree built-in, by limiting one or both trees to two levels, and so on, +providing a classic example of the impoverishing effect of failing to +permit language features to attain their natural level of generality. +@PP +We are thus led to propose a second abstraction for document formatting, +which we name the @I galley in recognition of its similarity to the +galleys used in manual typesetting. A galley consists of an object (such +as a footnote) together with a sequence of places where that object may +appear (such as the bottoms of the current and following pages). Splitting +occurs quite naturally when space at any place is insufficient to hold +the entire object. +@PP +In Lout, a footnote galley and its place of appearance are defined +as follows: +@ID @OneRow @Code { +"def @FootPlace { @Galley }" +"" +"def @FootNote into { @FootPlace&&following }" +" right x" +"{ x }" +} +The @Code "@FootPlace" symbol contains the special symbol {@Code "@Galley"}, +indicating that it is a point of appearance for a galley. By placing +invocations of @Code "@FootPlace" at the bottoms of pages, as in Section +{@NumberOf recursion}, we define the desired points of appearance for +footnotes. Symbols whose body contains @Code "@Galley" either directly +or indirectly are called receptive symbols, meaning receptive to +galleys, and they are expanded only on demand. The effect of the +@Code "into" clause is to make each invocation of @Code "@FootNote" a +galley whose object is the result of the invocation in the usual way, +and whose sequence of points of appearance is specified by the @Code "into" +clause; in this example, the sequence of all @Code "@FootPlace" symbols +following the invocation point. +@PP +Lout permits galleys to be invoked within other galleys to arbitrary +depth, so that one may have footnotes within figures within the body +text galley, for example, creating arbitrary static trees. Receptive +symbols like @Code "@FootPlace" may appear within any galley, creating +arbitrary dynamic trees as well. The root of the dynamic tree, which +would normally consist of the sequence of pages of the complete assembled +document, is considered to be a galley whose point of appearance is the +output file. Points of appearance may be @Code preceding or @Code following +the invocation point; entries in tables of contents are the main users +of {@Code preceding}. +@PP +The galley abstraction is adequate for all of the applications listed at +the beginning of this section, except that there is no provision for +sorting index entries and references. Sorting of galleys has been added +to Lout as a built-in feature, invoked by adding a special @Code "@Key" +parameter to the galleys, and using its value as the sort key. The author +was at a loss to find any other way, or any useful generalization of this +feature. Its implementation will be discussed in Section +{@NumberOf cross.impl}. +@End @SubSection |