diff options
Diffstat (limited to 'macros/lollipop/doc/manual/opt.tex')
| -rw-r--r-- | macros/lollipop/doc/manual/opt.tex | 408 |
1 files changed, 0 insertions, 408 deletions
diff --git a/macros/lollipop/doc/manual/opt.tex b/macros/lollipop/doc/manual/opt.tex deleted file mode 100644 index 1d0b5d7959..0000000000 --- a/macros/lollipop/doc/manual/opt.tex +++ /dev/null @@ -1,408 +0,0 @@ -% opt.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 Options - -This chapter discusses the various options that are common to all -\Lollipop\ constructs. - -\Section Titles - -Any construct can have a title, although of course it is most useful -for headings. -A construct has a title if the option \refopt{title} appears. -Example: -\Ver> -\DefineHeading:Section [...] - Style:bold title - [...] Stop<Rev - -will define a \cs{Section} macro that has a title. -The macro is then used as -\Ver> -\Section The title of this section - -Some text in this section.<Rev -that is, the title is delimited by an empty line. - -The title is actually available as a macro \refcs{FooTitle}, so that you -can write a macro, for instance -\Ver> -\def\ComplicatedTitle{ .. \hrule ... - \vrule ... \vbox \bgroup ... - \FooTitle ... - }<Rev -and use this macro instead of the \opt{title} option -\Ver>\DefineBar:Foo ... - ComplicatedTitle - ... Stop<Rev -However, since the option \opt{title} now doesn't appear anymore, it -becomes necessary to specify explicitly that there is a title. -This can be done with the \refopt{HasTitle} option. For instance, -you define -\Ver>\DefineBar:Foo ... - HasTitle - ComplicatedTitle - ... Stop<Rev -where \cs{ComplicatedTitle} is a macro that formats the title. - -\SubSection Short titles - -The option \opt{HasTitle} can have a parameter \n{short}, denoting that -the title is not delimited by an empty line (or \cs{par}) but by the -line end. For an example see section~\ref[sec:address]. - -\Section[sec:opt:counter] Counters - -There are three ways for Lollipop to figure out that a generic -construct has a counter. First of all, in -\Ver>\DefineFoo:Bar [...] - BarCounter [...]<Rev -the \cs{BarCounter} will be defined automatically. - -Additionally there is the option \refopt{counter}, which can be used -to declare the representation of the option, for instance -\opt{counter:i} allocated a counter that is printed in lowercase roman -numerals. For the available representations, -see~\ref[sec:counter:repr]. - -Finally, if the counter is only used in a macro, the -option \refopt{HasCounter} will cause the counter to be created anyhow. -This is analogous to the \opt{HasTitle} option. - -\SubSection Counter synonyms - -Every once in a while you may want different constructs to use the same -counter. For instance, if your book has definitions, theorems, lemmas, -corollaries and notations, it may confuse the reader if they all have -their own counter. The numbering would seem to jump all over the place. - -A `counter synonym' can be declared in \Lollipop\ by a slight abuse of -the \opt{counter} option. -\Example -\DefineTextBlock:Theorem counter:1 begingroup Style:bold - literal:Theorem Spaces:1 TheoremCounter Spaces:2 endgroup - text Stop -\DefineTextBlock:Corollary counter:Theorem begingroup Style:italic - literal:Corollary Spaces:1 CorollaryCounter Spaces:2 endgroup - text Stop -\DefineTextBlock:Definition counter:Theorem begingroup Style:roman - literal:Definition Spaces:1 DefinitionCounter Spaces:2 endgroup - text Stop -\Definition We define a {\it Foo} to be an arbitrary object\> -\Theorem Foos have arbitrary properties\> -\Corollary Foos are extremely valuable\> -\Corollary Foos are extremely worthless\> -\Theorem Foos don't exist\> -\ExampleStop - -You can only declare a counter to be synonym for something that has -already been created. In the above example you cannot define the -\cs{Theorem} after the \cs{Corollary}. - -\ImpNote -At the start of defining the construct, \cs{BarCounter} is defined to -be an option: -\Ver>\add@generic@default{\has@counterno - \def\counter@repr{1} - \csarg\def{\gen@option@name{\@name Counter}}{% - \@add@toks{\@name Counter}\global\has@counteryes}}<Rev - -Then, -\Ver>\add@generic@stop@default{\ifhas@counter - \xp\expandafter\xp\install@counter - \xp\counter@repr\@space\fi}<Rev - - -The counter is stepped, and the new value is stored in a mark item, -in \cs{outer@start@commands}: - -\Ver> - \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<Rev -\ImpNoteStop - -\Section Chunks of text - -Especially in headings, short chunks of text may need a special -treatment. For instance, the number may have to be filled to a certain -width, or a line may have to be drawn of the exact length of the -title. Lollipop have various general options (so they can also be used -in other contexts than headings) for handling pieces of text. - -\SubSection[sec:opt:block] The \opt{block} option\label[opt:block] - -The \refopt{block} option takes up a piece of text and fits it on one -line. It can measure the text, or set the size. Also there are a number -of ways of placing a block. - -Basic usage: -\Ver> block:start [...] block:stop<Rev -This takes the enclosed text, and reproduces it. This is mostly -interesting in combination with \opt{textcolumn}, -see~\ref[sec:opt:textcolumn]. -\Ver> block:hang [...] block:stop<Rev -The resulting block is dropped until its top touches the baseline. -For uniformity of appearance, the resulting width of the block can be -specified: -\Ver> block:start [...] fillupto:20pt<Rev -The name of a \cs{Distance} parameter can be used here. - -\Example -\DefineHeading:TestHeading - line:start block:hang PointSize:8 SetFont - TestHeadingCounter fillupto:20pt - block:hang PointSize:14 SetFont title block:stop - line:stop Stop -\TestHeading Top Aligning the Title - -\endExample - -The block is usually in between the margins of the text, but it can be -made to stick out into the margin, by closing it with the option -\refopt{stickout}. For the left margin this done as - \Ver> block:start [...] stickout:left<Rev -and for the right margin - \Ver> block:start [...] stickout:right<Rev -The size of the box can be specified, for instance as - \Ver> block:start [...] stickout:left=20pt<Rev -For a left box the material in it is pushed to the left edge, for a -right sticking box it is shifted to the right. - -\SubSection[sec:blockwidth] Block Measuring - -All blocks are immediately measured when they are placed. This makes it -possible for instance to underline a title exactly. After a block has -been placed, its width is available as \refcs{BlockWidth}. - \Example -\def\rulespecs{height 1pt width \BlockWidth\relax} -\DefineHeading:TestHeading Style:bold - line:start block:start TestHeadingCounter . Spaces:2 stickout:left - block:start title block:stop line:stop - vwhite:2pt hrule rulespecs vwhite:10pt Stop -\TestHeading The Title Is Underlined - -The text follows. -\ExampleStop -Observe how a control sequence \cs{rulespecs} is used to sneak the -height and width of the rule into the definition. This is necessary -because control sequences are not allowed in a construct definition. - -\SubSection[sec:opt:line] The \opt{line} option - -The option \refopt{line} is used to create a single strip of text that -fits exactly in between the margins of the page. Most of the time, titles -will be in a line. - -\Example -\DefineHeading:TestHeading - line:start block:start TestHeadingCounter Spaces:1.5 stickout:left - title line:stop Stop -\TestHeading A Title - -\endExample - -Another example was above. Here is another use of a line: - -\Example -\DefineHeading:TestHeading - line:start TestHeadingCounter fillup title line:stop Stop -\TestHeading The title - -\endExample - -\SubSection[sec:opt:textcolumn] The \opt{textcolumn} option - -In the examples above all titles fit on one line comfortably. If this -is not the case, the title can be put in a \refopt{textcolumn} which can -span several lines. - -\Example -\DefineHeading:TestHeading - line:start block:start TestHeadingCounter Spaces:2 block:stop - textcolumn:topline title textcolumn:stop - line:stop Stop -\TestHeading A very very very very very very very very very very very -very very very very very very very very very very very very very -very very very very very very very very long title - -\endExample - -This option is mostly interesting in combination with others such as -\opt{block} and \opt{line}. As is apparent from the above example: a -block placed in the same line as a text column will detract from the -latter's width. - -(In fact it is the other way around: \Lollipop\ sets -the line with a text column of width zero to determine the remaining -space. Then the line is set again. This may give problems if you -manipulate parameters inside the line, because the line is in effect -typeset twice. Also make sure not to have other \cs{vbox}-es in the -line than the text column.) - -\SubSection[sec:opt:traps] Traps - -It is a bad idea to have material in headings and such that is not -inside a block, textcolumn, or line. For instance: - -\Example -\DefineHeading:TestHeading - block:start TestHeadingCounter Spaces:2 block:stop - title Stop -\TestHeading Where does the title go? - -\endExample - -\Section[sec:opt:label] Labels - -References to any counter will always be correct, no matter if that -counter has changed after retypesetting the document, if symbolic -references are used. Referencing is explained in detail in -chapter~\ref[chap:referencing]. - -The way a symbolic reference is formatted can be altered from the -default (just give the counter) by using the \refopt{label} option. -\Ver>\DefineHeading:TestSection - line:start Style:italic TestSectionCounter Spaces:2 title line:stop - label:start ( TestSectionCounter ) label:stop Stop<Rev -See further section~\ref[sec:shape:reference]. - - -\Section[sec:opt:penalties] Break before / after - -The options \refopt{breakbefore} and \refopt{breakafter} control how -eager \TeX\ will be to break the page before or after a construct. These -options take one value, a so-called `penalty' value, meaning that the -higher the value you specify, the higher the penalty is, and -therefore the less likely it is that the page will be broken there. - -Numerical values are typically in the tens or hundreds; any value -of \n{10$\,$000} or more means that there will never be a break at -that point; a value of \n{-10$\,$000} or less means a guaranteed -break. If you don't want to remember these rules, values of \n{yes} -and \n{no} mean a guaranteed break, and no break respectively. - -\WizNote -A further exceptional value is \n{breakbefore/after:0}, this will -cause no penalty to be placed. The reason for this is highly \TeX -nical. -\> - -\Section[sec:opt:indent] Indentation - -The option \refopt{indentafter} controls the behaviour of the first -paragraph after a generic construct., \refopt{indentinside}, -\refopt{indentfirst}. - -\Section Rules - -There is an option \refopt{hrule}. You should not write -\Ver>\def\rulemacro{\hrule height [...] } -\DefineHeading [...] rulemacro [...] Stop<Rev -because then \Lollipop\ cannot prevent page breaks around the rule. -Instead write -\Ver>\def\rulespecs{ height [...] } -\DefineHeading [...] hrule rulespecs [...] Stop<Rev -so that the option \opt{hrule} is used. See -section~\ref[sec:blockwidth] for an example. - -\Section Embedded constructs - -Most generic constructs will be vertically separated from the -surrounding text. However, in rare cases (and for unusual applications) -it be desired to have a construct that is part of a paragraph. For this -the option \refopt{embedded} exists. - -This option has the following values. -\Ver> embedded:no<Rev -This is the default. -\Ver> embedded:left<Rev -The construct continues an already started paragraph, but after the -construct a vertical break follows. -\Ver> embedded:right<Rev -After the construct a paragraph can continue, but the construct is -separated vertically from preceding text. -\Ver> embedded:yes<Rev -The construct is both left and right embedded. - -Embedding a construct has an interesting application to generating -indexes. (See chapter~\ref[chap:external-files] for general information -about external files.) This can be done by having embedded headings -that write their title to the index file. - -\Example -\DefineExternalFile:tIndex=tix -\DefineHeading:NewWord embedded:yes - block:start Style:bold title block:stop - external:tIndex title external:stop Stop -\def\introword#1{\NewWord #1\par} -In this sentence two \introword{flubrious} words are -\introword{stinselsed}. -\ExampleStop - -Cute, ain't it? - -A word of warning though. Headings and such generate \TeX\ `marks' -which take up main memory. You only need these if you are going -to be referring to that object with \cs{LastPlaced} or such; see -section~\ref[sec:head/foot]. Embedded headings used as above -usually don't need these marks, so you can prevent \TeX\ overflow by -putting the option \opt{nomarks} in their definition. - -\Section Obscure options - -\SubSection Arguments - -In case you want to interface to other macro packages, you may want to -let a construct generate a call to the other package. For this, the -\Lollipop\ macro should be able to produce sequences such as -\ver>\begin{itemize}>. The problem here is the braces. The option -\refcs{arg} produces a braced expression. - -For instance -\Ver>\DefineTextBlock:LaTeXlist begin arg:{itemize} text - end arg:{itemize} Stop<Rev -makes it possible to use call \LaTeX\ macros from \Lollipop. - -\SubSection[sec:implicit:close] Implicit closing - -The control sequence \refcs{>} closes the current group, and \refcs{>]} -closes all currently open groups. Every once in a while this is too -drastic. Hence there is an option \refopt{noimplicitclose} that can be -used to prevent a construct from being closed implicitly. Using \cs{>]} -inside such a construct will close all enclosed constructs. - -See the definition of \cs{EExample} in this manual for an example. - -\Section[sec:opt:test] Testing - -There is an option \opt{test}. - -\endinput - -% 92/11/10 \BlockWidth discussed in 'block' section -% 92/11/15 counter:othercounter discussed -% 92/11/21 option 'arg' - |