diff options
Diffstat (limited to 'macros/lollipop/doc/manual/list.tex')
-rw-r--r-- | macros/lollipop/doc/manual/list.tex | 442 |
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 |