summaryrefslogtreecommitdiff
path: root/macros/plain/formats/lollipop/doc/manual/list.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/list.tex')
-rw-r--r--macros/plain/formats/lollipop/doc/manual/list.tex442
1 files changed, 442 insertions, 0 deletions
diff --git a/macros/plain/formats/lollipop/doc/manual/list.tex b/macros/plain/formats/lollipop/doc/manual/list.tex
new file mode 100644
index 0000000000..24df43a61b
--- /dev/null
+++ b/macros/plain/formats/lollipop/doc/manual/list.tex
@@ -0,0 +1,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 \ No newline at end of file