summaryrefslogtreecommitdiff
path: root/macros/plain/formats/lollipop/doc/manual/list.tex
blob: 24df43a61bdb217e3c16a175018ae05dfbcaca34 (plain)
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
% list.tex copyright 1992 Victor Eijkhout
%              copyright 2014--2016 Vafa Khalighi
%
%
%    This program is free software: you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation, either version 3 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
% 
\Chapter Lists

Lists in Lollipop are defined by \refcs{DefineList}:

\Ver>\DefineList:Foo [...]
    item:start [...] item:stop
    [...] Stop<Rev
and the resulting list is used as
\Ver>\Foo
\item [ ..text.. ]
\item [ ... ]
\FooStop<Rev
where the closing command can be abbreviated as~\cs{>}.

\Section Label alignment

In general there is a default position for labels; 
either aligning with the
left or the right side of the margin over which the list is indented.
The two ways are indicated with the option \refopt{item}:
\Ver>    item:left [...] item:stop<Rev
and \Ver>    item:right [...] item:stop<Rev respectively.
Specifying \opt{item:start} gives the default left aligning position.

\Example
\DefineList:enumerate
    item:start itemCounter ) item:stop Stop
\DefineList:enumerateright
    item:right ( itemCounter ) Spaces:1 item:stop Stop
\enumerate\item Some item
\item And another
\enumerateright\item First nested item
\item Next nested item\>
\item And back to the original list.\>
\ExampleStop

\Section List indentation

The amount over which the text of a list (excluding the item labels)
is indented is controled by a list of indentations. This is explained
in section~\ref[sec:indent:control]. The indentation amount is most of
the time also equal to the value of the paragraph indentation outside
that list.

In the rare case where the indentation of a list has to be controlled
explicitly, there is an option \refopt{indentation} with one value.
\Ver>\DefineList:SomeList indentation=30pt [...] Stop<Rev


\Section Label style

Every list that uses the \refopt{itemsign} option is an `itemize' list,
no matter what it's name, and there is a counter in Lollipop that
keeps track of how deep you are in itemize lists. Similarly, every
list that uses \refopt{itemCounter} is an `enumerate' lists, and these
are counted too.

On every next level a new style of item sign or counter is used. For
item signs this is in sequence: $\bullet$, $\circ$, --, and $\cdot$
for all higher levels. The style of sign can be changed by
\refcs{SetItemSign}: \Ver>\SetItemSign:6=m<Rev where the letter
indicating the sign is interpreted as: \n b~$\bullet$ (bullet), \n
c~$\circ$ (circle), \n d~$\diamond$ (diamond), \n m~--- (em-dash), \n
n~-- (en-dash), \n .~$\cdot$.

Similarly, the counter style can be set by
\refcs{SetItemCounterRepresentation}:
\Ver>\SetItemCounterRepresentation:2=i<Rev where the letter
representing the style is interpreted as: 1~Arabic, I~uppercase roman,
i~lowercase roman, A~uppercase characters, a~lowercase characters.

\Section Label width

The default width for a label is at most the width of the margin over
which the list is indented. Using \opt{item:left} or \opt{item:right}
will have the label pushed to the left or right side of this margin
respectively. Now what if the label material is wider than this
margin? Usually you want the label then to expand to the right, and
that is indeed what happens, unless you specify
\refopt{labeloverflow} with value \n{left}, in which case the right
boundary of the label will not budge, and the label will start
protruding into the outer margin.

\Section[sec:description:list] Description lists

A common type of list is the type where each item label consists of a
piece of text. Such a list is called a `description' list in
\Lollipop, and it recognized by the occurrence of the option
\refopt{description} in its definition. A~description list can also use
the item sign or the item counter, of course.

Using a description list, the description text is everything that
follows the command \cs{item}, up to the end of the line.

\Example
\DefineList:TestList 
 item:left Style:bold itemCounter . Spaces:1 description
      Spaces:2 item:stop Stop
\TestList\item Do
A deer, a female deer.\item Re
According to mr. Fowler only a legal term.
\item Mimi Jett
The owner/founder of ETP\>
\ExampleStop

As you can see, the problem of label overflow can easily occur with
description lists. Thus it is a good idea to end the item material
with some white space, as in the above example.

 Exceptional situation:
if you use an empty description text, you should write \ver>\item{}>.

\Section Suspended lists

Occasionally the is a need to resume an enumerate list, that is,
after a piece of text that is not part of the list an enumerate list
should start counting from the previous value on. In \Lollipop\ this
phenomenon can be realized by never ending the enumerate list, and
simply moving the text one indentation level back with
\refcs{PopIndentLevel}.

\Example
\DefineList:enumerate item:left itemCounter item:stop Stop
\enumerate\item First some item\par
{\PopIndentLevel \Indent:no
This text seems to be outside the list. Don't you believe it.\par}
\item And another item\>
\ExampleStop

Note that the `popped' text has to be in a group (otherwise the
subsequent items will also be popped back), and it has to be
separated from the preceding and following text by \cs{par}; the
trailing \cs{par} has to be in the group.

\Section Item counter manipulation

The item counter can be manipulated explicitly. This is necessary for
instance for starting a list at another value than one. What you need
to realize here is that the command \cs{item} starts by incrementing
the counter. Furthermore, the only way to access the item counter is
through the commands for counters; see section~\ref[sec:counters].

\Example
\DefineList:enumerate item:left itemCounter item:stop Stop
\enumerate \SetCounter:item=-1
\item Escape: usually the backslash.
\item Begin Group.\>
\ExampleStop

\Section List titles and list tails

Lists can have titles. The title follows the command that invokes the
list, in the usual manner. Material to follow the list can also be
specified: anything following the option \refopt{text} is considered to
be trailing material.

\Example
\DefineList:TestList hrule line:start Style:bold title line:stop
 item:left Style:italic itemCounter item:stop
 text vwhite:3pt hrule Stop
\TestList In the last fiscal year, have you:\par
\item Eaten peanuts? \item Walked the dog?
\item Bought a Frank Zappa record?\>
\ExampleStop

In case you wonder what happens with textual material after
\opt{item:stop} and before any \opt{text}, well, that is taken to be
inserted immediately after each item label.

\Section Between the items

There are special list options controlling what happens in between
items. \Lollipop\ has an option \refopt{breakbetween}, analogous to
\opt{breakbefore} and \opt{breakafter}; see
section~\ref[sec:opt:penalties]. This item be default has a
value of~\n{$-50$}, implying that breaks in between items
should be preferred slightly over breaks in between the
lines of an item.

Similarly, there is an option \refopt{whitebetween}
controlling the amount of white space in between items that is
analogous to \opt{whitebefore} and \opt{whiteafter}. Like these two
options, it can also be set by the \cs{Distance} command
(section~\ref[sec:com:distance]).

\Section Indentation in lists

An item can be considered to be consisting of at least one paragraph.
That paragraph is never indented. For the behaviour of any next
paragraph within the same item, the option \refopt{indentinside} can be
used. This option has values yes/no. In case paragraphs inside an
item indent, the indentation amount is level-controlled; see
section~\ref[sec:indent:control].

\Chapter[chap:text:block] Text Blocks

The `text block' is a way of treating a moderate sized chunk of text
in a different  way from the surrounding text. Text blocks are
created by \refcs{DefineTextBlock}. Here is a small example.

\Example
\DefineTextBlock:Quote 
 PushIndentLevel PointSize:9 SetFont text Stop
\Indent:no In some context it has been written that
\Quote No man is an island.\QuoteStop
In another:
\Quote Run don't walk to the nearest island.\>
Sometimes one would wish women weren't so logical.
\ExampleStop

Note that the text block has an explicit closing command,
consisting of the name of the block followed by \opt{Stop},
and that implicit closing by \cs{>} is possible.
 
\Section The \opt{text} option

Text blocks have only one specific option: \refopt{text}. This option
is used to separate material heading the block from material trailing
the block. Example:

\Example
\DefineTextBlock:DisplayEq 
 whitebefore:abovedisplayskip whiteafter:belowdisplayskip
 line:start white:parindent $ displaystyle text $ line:stop Stop
The formula
\DisplayEq e^{\pi i}+1=0\>
contains nature's five most interesting constants.
\ExampleStop

Here one dollar comes before the text, and one after, so the first is
inserted by \cs{DisplayEq} and the second by the corresponding
closing command.

Material before and after the text should usually not be broken.
Hence \cs{nobreak} is automatically inserted. See the \cs{Example}
macro for this manual: pages should not be broken after rules, or
around the text `example~xyz'.

\Section More examples

A text block can encompass more than one paragraph, so the options
\opt{indentinside} and \opt{indentfirst} are particularly useful here.

\Example
\AlwaysIndent:no
\DefineTextBlock:TestBlock PushIndentLevel
 indentafter:yes indentfirst:no indentinside:yes 
 text unskip hfill $ bullet $ par Stop
One paragraph.\par The next paragraph
\TestBlock Inside the block one paragraph.\par
Inside the block the next paragraph.\>
Outside the following paragraph.\par And the last paragraph.
\ExampleStop
 
\ImpNote 
\iSection[imp:gen:open:close] The environment in generic constructs

The text block is just about the purest use of the \Lollipop\
environment mechanism. Here is how a text block is defined:
\Ver>
\def\@DefineTextBlock{
    \csarg\edef{\@name}{\@gen@open
        \the\before@coms
        }
    \@DefineStopCommand{\the\after@coms \@gen@close}
    }<Rev

The \cs{before@coms} and \cs{after@coms} are two token lists with
the heading and trailing commands.

It is important to note that the definition of the control sequence
of the block is defined by \cs{edef}. This first of all unwraps the
token lists, but it also has an important effect on
\cs{@gen@open/close}. These control sequences contain a lot of
conditionals which, in combination with the \cs{edef} give a really
dynamic definition of generic constructs in \Lollipop.

First of all, the opening and closing commands induce a group
so that various quantities can be set locally.
\Ver>
\def\@gen@open{\outer@start@commands 
    \begingroup \inner@start@commands}
\def\@gen@close{\inner@end@commands 
    \endgroup \outer@end@commands}<Rev

The outer start commands concern global actions such as backspacing
previous skips, incrementing counters and setting references.
\Ver>
\def\outer@start@commands{%
    \iftext@construct
        \ifleft@embedded@construct
              \nxp\bsp@hack
        \else \nxp\leavehmode \nxp\bvwit{\the\@whitebefore}\fi<Rev
The `embedded construct' tests are only true if the construct
can be embedded in a paragraph. A~rare occurence most of the time.
\Ver>
        % backspace previous white space while it's visible
        \nxp\if@headed\nxp\else
            \ifforced@break@before\@beforepenalty
            \else\nxp\ifnum\lastpenalty=\z@
                         \@beforepenalty\nxp\fi
            \fi
        \nxp\fi<Rev
A subtle point: a preceding heading will have placed \cs{nobreak} 
followed by a skip. It is dangerous to place any sort of penalty
after this because it might induce a page break.

Now the counter, title, and stuff connected to that.
\Ver>
    \fi
    \ifhas@counter \nxp\StepCounter:\expandafter\@name\@space
        % This sets the \current@label by default<Rev
Since this is used inside an \cs{edef} we can use some trickery
to get the space token after the argument to \cs{StepCounter}.
\Ver>
        \ifhas@marks \edef\nxp\cs@e
               {\nxp\nxp\nxp\refresh@mark@item
                {\@name Counter}{\CSname{\@name Counter}}}%
            \nxp\cs@e      
        \fi
        \fi
    \iflabel@defined 
        \global\current@label={\the\@labelcoms}\fi
    \ifhas@title \install@title@code<Rev
This title business is explained in~\ref[imp:install:title].
This piece of code also refreshes the title in the mark structure.
This has to be done after any page break for the benefit
of headers/footers.
\Ver>
    \fi
    \ifhas@marks\nxp\ifnin{\nxp\place@mark}\fi
        %otherwise IniTeX'ing Lollipop will output a page
    \nxp\xx@label\the\extern@toks\penalty\@M
        % also subtle: if this white space would be higher, it would
        % be invisible because of marks et cetera.
        % insert nobreak after marks/writes to prevent page breaks.
    \iftext@construct
        \ifleft@embedded@construct
              \else \nxp\@vwhite{\the\@whitebefore}\fi
    \fi
    }<Rev

Inner start commands are concerned with setting local values.
\Ver>
\def\inner@start@commands{%
    \nxp\Open@Group\CSname{\@class}\CSname{\@name}%<Rev
The \cs{Open@Group} call makes it possible to track down groups
that have inadvertendly been left open. Since we now know the
name we can give helpful error msgs.
\Ver>
    \install@stop<Rev
Install the right implicit closing, see~\ref[sec:implicit:close]
and~\ref[imp:implicit:close].
\Ver>
    \ifleft@embedded@construct
    \else \nxp\hold@parskip 
        \nxp\@defaulteverypar
        \ifwhiteleft@defined \advance\leftskip \the\@whiteleft \relax \fi
        \ifwhiteright@defined \advance\rightskip \the\@whiteright \relax \fi
        \nxp\let\nxp\par=\nxp\@par %explain to me again why this is necessary...
        \inside@indent \first@indent
    \fi
    \advance\nest@depth\@ne<Rev
The nest depth is used for determining indentation levels.
\Ver>
    }<Rev

End commands set up some conditions, most of which will be tested
by the start of any next construct.
\Ver>
\def\inner@end@commands{%
    \nxp\Close@Group\CSname{\@class}\CSname{\@name}%
    \ifright@embedded@construct \else \nxp\leavehmode \fi
    \@afterpenalty
    \ifright@embedded@construct \else \nxp\@vwhite{\the\@whiteafter}\fi
    }
\def\outer@end@commands{%
    \the\after@toks
    \ifright@embedded@construct 
        \nxp\@headedno \nxp\esp@hack
    \else
        \after@indent \nxp\dono@parskip
    \fi}<Rev

\iSection[imp:implicit:close] Implicit closing

Constructs with an explicit closing command, lists and text blocks,
can be closed by~\cs{>}, which simply closes the current
construct. A~more drastic version, \cs{>]}, closes all currently
open constructs.
\Ver>
\def\outer@stop@command{\Emessage{Vacuous group closing}}
\let\default@stop@command\outer@stop@command
\def\>{\default@stop@command%[fool the editor
    \ifNextChar]{%
        \ifx\default@stop@command\outer@stop@command
            \xp\take@one
        \else \xp\>\fi}{}}<Rev
The \cs{outer@stop@command} is meant to give an error msg if the
user attempts to close a group while none is open.

The current meaning of~\cs{>} is installed in
\cs{inner@start@commands}:
\Ver>
\def\install@stop{\if@implicitclose
        \def\nxp\default@stop@command
               {\CSname{\stop@command}}%
    \else \let\nxp\default@stop@command
              \nxp\outer@stop@command 
    \fi}<Rev

By default, constructs can be closed implicitly, but there is an
option \refopt{noimplicitclose} to disable this.
\Ver>
\newif\if@implicitclose
\add@generic@default{\@implicitcloseyes}
\@GenericOption{noimplicitclose}{\@implicitcloseno}<Rev
This option is for instance used in the examples in this manual.
Otherwise closing a construct in the example would also close the
example itself.

\ImpNoteStop

\endinput