% 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 .
%
%
\Chapter Lists
Lists in Lollipop are defined by \refcs{DefineList}:
\Ver>\DefineList:Foo [...]
item:start [...] item:stop
[...] Stop\Foo
\item [ ..text.. ]
\item [ ... ]
\FooStop}.
\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 item:right [...] item:stop
\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\SetItemSign:6=m\SetItemCounterRepresentation:2=i
\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}
}
\def\@gen@open{\outer@start@commands
\begingroup \inner@start@commands}
\def\@gen@close{\inner@end@commands
\endgroup \outer@end@commands}
\def\outer@start@commands{%
\iftext@construct
\ifleft@embedded@construct
\nxp\bsp@hack
\else \nxp\leavehmode \nxp\bvwit{\the\@whitebefore}\fi
% 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
\fi
\ifhas@counter \nxp\StepCounter:\expandafter\@name\@space
% This sets the \current@label by default
\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
\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
}
\def\inner@start@commands{%
\nxp\Open@Group\CSname{\@class}\CSname{\@name}%
\install@stop
\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
}
\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}}, 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}{}}} 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}
\newif\if@implicitclose
\add@generic@default{\@implicitcloseyes}
\@GenericOption{noimplicitclose}{\@implicitcloseno}