aboutsummaryrefslogtreecommitdiffstats
path: root/doc/expert/exa_chap
blob: 51926c099086f82e451d3ea0b02d2a9f26657201 (plain) (blame)
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
@Section
   @Title { Chapters and sections }
   @Tag { chapters }
@Begin
@PP
The definitions of chapters and sections from the DocumentSetup package
chapters. @Index { Chapters and sections }
of Version 2 (in Version 3, the BookSetup extension of DocumentSetup)
form the subject of this section.  They allow a chapter to be entered
like this:
document.layout.chapters @SubIndex { chapters and sections }
@ID @Code {
"@Chapter"
"    @Title { ... }"
"    @Tag { ... }"
"@Begin"
"    ..."
"@End @Chapter"
}
Within the chapter a sequence of sections may be included by writing
@ID @Code {
"@BeginSections"
"@Section { ... }"
"..."
"@Section { ... }"
"@EndSections"
}
These are numbered automatically, and an entry is made for each in a
table of contents.
@PP
The user of the DocumentSetup package can find the number of the chapter or
section with a given tag by writing @Code "@NumberOf tag" at any point
in the document.  This feature is based on the following definitions:
numberof.example @Index { @Code "@NumberOf" example }
@ID @Code {
"export @Tag"
"def @NumberMarker right @Tag { @Null }"
""
"def @NumberOf right x"
"{  @NumberMarker&&x @Open { @Tag }  }"
}
Each chapter and section will contain one invocation of
{@Code "@NumberMarker"}; a full explanation will be given later.
@PP
A sequence of places for receiving chapters is easily defined:
@ID @Code {
"export @Tag"
"def @ChapterList right @Tag"
"{"
"    @Galley"
"    //@ChapterGap  @ChapterList @Next @Tag"
"}"
}
@Code "@ChapterGap" will usually be {@Code "1.1b"}, ensuring that each
chapter begins on a new page.  The @Code "@Chapter" galley itself is
defined as follows:
chapter.example @Index { @Code "@Chapter" example }
@IndentedList
@LI @Code {
"export @FootNote @BeginSections @EndSections @Section"
"def @Chapter force into { @ChapterList&&preceding }"
"    named @Tag {}"
"    named @Title {}"
"    named @RunningTitle { dft }"
"    body @Body"
"{"
"    def @FootNote right x { @ColFootNote x }"
""
"    def @BeginSections ..."
"    def @EndSections ..."
"    def @Section ..."
}
@LI @Code {
"    def @ChapterTitle"
"    {"
"        @ChapterNumbers @Case {"
"            {Yes yes}  @Yield  { Chapter {@NumberOf @Tag}.  |2s  @Title }"
"            else  @Yield  @Title"
"        }"
"    }"
""
"    def @ChapterNum"
"    {"
"        @ChapterNumbers @Case {"
"            {Yes yes}  @Yield  { Chapter {@NumberOf @Tag} }"
"            else  @Yield @Null"
"        }"
"    }"
}
@LI @Code {
"        ragged @Break @BookTitleFormat @ChapterTitle"
"    //  @NumberMarker {"
"            @ChapterList&&@Tag @Open { @Tag }"
"        }"
"    //  @ChapterList&&preceding  @Tagged @Tag"
"    //  @NumberMarker&&preceding @Tagged @Tag"
"    //  @PageMarker&&preceding   @Tagged @Tag"
"    //  { @ChapterTitle } @MajorContentsEntry {@PageOf @Tag}"
"    //  @Runner"
"            @FootEven { |0.5rt 0.8f @Font @B @PageNum }"
"            @FootOdd  { |0.5rt 0.8f @Font @B @PageNum }"
"    //  @Body"
"    //@SectionGap @ChapRefSection"
"    //  @Runner"
"            @TopEven { @B @PageNum |1rt @I @ChapterNum }"
"            @TopOdd  { @I {@RunningTitle @OrElse @Title} |1rt @B @PageNum }"
"}"
}
@EndList
We will see the symbols for sections shortly.  Notice how their use has
been restricted to within the right parameter of {@Code "@Chapter"}, by
nesting them and using a body parameter.
@PP
The meaning of @Code "@FootNote" within @Code "@Chapter" has been set
to {@Code "@ColFootNote"}, which produces a footnote targeted to
{@Code "@ColFootList"} (see Section {@NumberOf pagelayout}).  In other
words, footnotes within chapters go at the foot of the column, not at
the foot of the page.  (Of course, in single-column books this
distinction is insignificant.)  @Code "@ChapterTitle" and
@Code "@ChapterNum" are trivial definitions which vary depending on
whether the user has requested numbered chapters or not.
@PP
Each invocation of @Code "@Chapter" has its own unique {@Code "@Tag"},
either supplied by the user or else inserted automatically by Lout.  We
now trace the cross referencing of chapter numbers on a hypothetical
third chapter whose tag is {@Code "euclid"}.
@PP
@Code "@ChapterList&&preceding @Tagged euclid" attaches @Code "euclid"
as an extra tag to the first invocation of @Code "@ChapterList"
preceding itself in the final printed document.  But this
@Code "@ChapterList" must be the target of the chapter, and so
@ID @Code "@ChapterList&&euclid @Open { @Tag }"
is 3, the number of the chapter ({@Code "@Tag"} refers to the parameter
of {@Code "@ChapterList"}, not the parameter of {@Code "@Chapter"}).
 Consequently the invocation of
@Code "@NumberMarker" within the chapter is equal to
{@Code "@NumberMarker 3"}.
@PP
@Code "@NumberMarker&&preceding @Tagged euclid" attaches @Code "euclid"
to {@Code "@NumberMarker 3"} as an extra tag, and so
{@Code "@NumberOf euclid"}, which expands to
@ID @Code "@NumberMarker&&euclid @Open { @Tag }"
must be equal to 3, as required.  This scheme could be simplified by
placing the invocation of @Code "@NumberMarker" within
@Code "@ChapterList" rather than within {@Code "@Chapter"}, but it turns
out that that scheme does not generalize well to sections and subsections.
@PP
There is a trap for the unwary in the use of @Code preceding and
{@Code following}.  Suppose that the invocation of @Code "@NumberMarker"
within @Code "@Chapter" is replaced by the seemingly equivalent
@ID @Code "@NumberMarker { @ChapterList&&preceding @Open { @Tag } }"
Now suppose that @Code "@NumberOf euclid" appears somewhere within
Chapter 7.  It will expand to
@ID @Code "@NumberMarker&&euclid @Open { @Tag }"
which would now be equal to
@ID @Code "@ChapterList&&preceding @Open { @Tag }"
whose value, evaluated as it is within Chapter 7, is 7, not 3.  Use of
@Code preceding or @Code following within the parameter
of a symbol, rather than within the body, is likely to be erroneous.
@PP
Much of the remainder of the definition of @Code "@Chapter" is fairly
self-explanatory:  there is a heading, a tag sent to mark the page on
which the chapter begins, a @Code "@ContentsEntry" galley sent to the
table of contents, galleys for the figures and tables of the chapter to
collect in, @Code "@Body" where the body of the chapter goes, and
@Code "@ChapRefSection" to hold a concluding list of references.  This
leaves only the two invocations of @Code "@Runner" to explain.
@PP
The first @Code "@Runner" is just below the heading.  It will be the target
of the @Code "@Runner&&following" cross reference at the beginning of the
first page of the chapter (see Section {@NumberOf pagelayout}), which
consequently will have null running headers and the given footers.
@PP
The second @Code "@Runner" appears at the very end of the chapter, hence
on its last page.  Since no invocations of @Code "@Runner" lie between
it and the first {@Code "@Runner"}, it will be the target of
@Code "@Runner&&following" on every page from the second page of the
chapter to the last, inclusive, and will supply the format of their
headers and footers.
@PP
The interested reader might care to predict the outcome in unusual
cases, such as when the heading occupies two pages, or when a chapter
occupies only one, or (assuming a change to the gap between chapters)
when a chapter starts halfway down a page.  Such predictions can be made
with great confidence.
@PP
The expression @Code "@RunningTitle @OrElse @Title" appearing in the second
@Code "@Runner" returns the value of the @Code "@RunningTitle" parameter
of @Code "@Chapter" if this is not equal to the default value
{@Code "dft"}, or @Code "@Title" otherwise:
orelse.example @Index { @Code "@OrElse" example }
@ID @Code {
"def @OrElse"
"    left x"
"    right y"
"{"
"    x @Case {"
"        dft  @Yield  y"
"        else  @Yield  x"
"    }"
"}"
}
This produces the effect of
@ID @Code {
"named  @RunningTitle  {  @Title  }"
}
which unfortunately is not permissible as it stands, because @Code "@Title"
is not visible within the default value of {@Code "@RunningTitle"}.
@PP
Finally, the definitions for sections omitted earlier are as follows:
section.example @Index { @Code "@Section" example }
@IndentedList
@LI @Code {
"def @EndSectionsPlace { @Galley }"
"def @EndSections force into { @EndSectionsPlace&&preceding } {}"
"macro @BeginSections { //@SectionGap @SectionList 1 // @EndSectionsPlace // }"
}
@LI @Code {
"def @Section force into { @SectionList&&preceding }"
"    named @Tag {}"
"    named @Title {}"
"    named @RunningTitle { dft }"
"    body @Body"
"{"
"    def @SectionTitle"
"    {"
"        @SectionNumbers @Case {"
"            {Yes yes} @Yield { {@NumberOf @Tag}.  |2s  @Title }"
"            else      @Yield @Title"
"        }"
"    }"
""
"        @Heading @Protect @SectionTitle"
"    //  @NumberMarker {"
"            {@ChapterList&&@Tag @Open { @Tag }}.{"
"             @SectionList&&@Tag @Open { @Tag }}"
"        }"
"    //  @ChapterList&&preceding  @Tagged @Tag"
"    //  @SectionList&&preceding  @Tagged @Tag"
"    //  @NumberMarker&&preceding @Tagged @Tag"
"    //  @PageMarker&&preceding   @Tagged @Tag"
"    //  { &3f @SectionTitle } @ContentsEntry {@PageOf @Tag}"
"    //0io @Body"
"}"
}
@EndList
The @Code "@BeginSections" macro invokes {@Code "@SectionList"},
preceded by the appropriate gap and followed by an @Code "@EndSectsPlace"
for closing the list of sections when the @Code "@EndSections" symbol is
found.  @Code "@Section" itself is just a copy of @Code "@Chapter" with
slight changes to the format.  The parameter of @Code "@NumberMarker" is
a simple generalization of the one within {@Code "@Chapter"}.  Notice
that we have taken care that the value of this parameter be
a juxtaposition of simple words:  although
@ID @Code {
"{@ChapterList&&@Tag @Open { @Tag }}. &"
"{@SectionList&&@Tag @Open { @Tag }}"
}
is formally equivalent, @Code "&" was not permitted within a
@Code "@Tag" parameter until recently.
@PP
The DocumentSetup package also contains definitions for subsections in the
same style.  They raise the question of whether Lout is capable of
producing subsections should the user place {@Code "@BeginSections"},
{@Code "@Section"}, and {@Code "@EndSections"} within a {@I section},
and whether such nesting could proceed to arbitrary depth.  Arbitrary
nesting of sections within sections is available now, although the
numbering would of course be wrong.  The author has worked out
definitions which provide correct numbering to arbitrary depth, with an
arbitrary format for each level.  These were not incorporated into
DocumentSetup because the author considers sub-subsections to be poor
style, and he prefers separate names for the symbols at each level.
@End @Section