summaryrefslogtreecommitdiff
path: root/macros/plain/formats/lollipop/doc/manual/opt.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/opt.tex')
-rw-r--r--macros/plain/formats/lollipop/doc/manual/opt.tex408
1 files changed, 408 insertions, 0 deletions
diff --git a/macros/plain/formats/lollipop/doc/manual/opt.tex b/macros/plain/formats/lollipop/doc/manual/opt.tex
new file mode 100644
index 0000000000..1d0b5d7959
--- /dev/null
+++ b/macros/plain/formats/lollipop/doc/manual/opt.tex
@@ -0,0 +1,408 @@
+% 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'
+