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