diff options
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/comm.tex')
-rw-r--r-- | macros/plain/formats/lollipop/doc/manual/comm.tex | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/macros/plain/formats/lollipop/doc/manual/comm.tex b/macros/plain/formats/lollipop/doc/manual/comm.tex new file mode 100644 index 0000000000..2876acf959 --- /dev/null +++ b/macros/plain/formats/lollipop/doc/manual/comm.tex @@ -0,0 +1,642 @@ +% comm.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 Commands + +\Section[sec:counters] Counters + +Counters can be declared explicitly by the user, but more often they +are defined automatically in some generic construct: + +The \cs{Foo} defined by +\Ver>\DefineBar:Foo ... + counter:i ... + Stop<Rev + +will have a counter that counts in roman lowercase, and which is +accessible as \refcs{FooCounter}. Everytime \cs{Foo} is used, this +counter is increased by one. + +The use of the \opt{counter} option is described +in~\ref[sec:opt:counter]. +Here are the commands for explicit manipulation of counters. + +\SubSection[sec:counter:repr] Allocation and representation + +A counter is created by for instance +\Ver>\NewCounter:Things<Rev +This will create control sequence \cs{ThingsCounter} that will print +the value of the counter. +The counter will usually be printed as an Arabic numeral, but other +counter representations can be specified by +\refcs{CounterRepresentation}. Here are their codes: \Description +\item 1 +numeric +\item a +lowercase character +\item A +uppercase character +\item i +lowercase roman +\item I +lowercase roman +\> +for instance +\Ver>\CounterRepresentation:Things=i<Rev +will cause \cs{ThingsCounter} to print a lowercase Roman numeral. + +However, a call such as +\Ver>\CounterRepresentation:Theorem=Lemma<Rev +will make the \cs{TheoremCounter} a synonym of an earlier created +\cs{LemmaCounter} + +\SubSection Counter manipulation + +The following commands can be used to manipulate counters, both when +they are created by hand using \refcs{NewCounter} and when they were +generated automatically in some generic construct: + +With \refcs{StartCounter} reset the counter to one: + \Ver>\StartCounter:things<Rev + +With \refcs{StepCounter} increase the counter by one: + \Ver>\StepCounter:things<Rev + +With \refcs{BackStepCounter} decrease the counter by one: + \Ver>\BackStepCounter:things<Rev + +With \refcs{SetCounter} set the counter to some specified value: + \Ver>\SetCounter:things=5<Rev + +With \refcs{AddToCounter} increase the counter by some +specified value: + \Ver>\AddToCounter:things=7<Rev + +The last two commands accept names of numerical parameters, for +instance the value of a counter: + \Ver>\NewCounter:Favourite +\AddToCounter:things=FavouriteValue<Rev +More about this `value' thing in the next section. + +\SubSection What do you get when you define a counter? + +After you define a counter as \Ver>\NewCounter:MyThings<Rev there are +two commands that it is important to distinguish between. First of +all, \cs{MyThingsCounter} gives the {\it printed\/} value of the +counter. This is the command that you will use mostly. It uses +whatever representation you have specified for the counter, or plain +Arabic numerals if haven't specified anything. + +Secondly, \cs{MyThingsValue} gives the value of the counter. You can +not use this command on its own: you will get a `number expected' +error. + +\SubSection Counter hierarchies + +Often counters are related to each other. For instance, when a new +section begins, the subsection counter has to be reset. The same may +be true for equation counters. In Lollipop such a relation is +indicated by a call to \refcs{GoverningCounter}, for instance + +\Ver>\GoverningCounter:SubSection=Section<Rev + +All of the counter manipulation commands applied to a governing +counter will cause all governed counters to be reset. Such a reset +also occurs if the counter was created in some generic construct. + +For examples, see section~\ref[sec:head:examples]. + +\SubSection Referencing counters + +All counters that are declared as part of a generic construct, or +explicitly through \refcs{NewCounter} automatically become the current +reference when they are altered. Thus \ver>\label[bar]> will make +\ver>\ref[bar]> refer to the value of the counter most recently +changed. The way the counter is referenced can be altered by the +\opt{label} option in generic constructs; see +section~\ref[sec:opt:label]. + +For generic constructs with a counter no explicit \refcs{label} commands +need to be given; such commands take an optional argument with the +label key: +\Ver>\Section[sec:examples] Examples<Rev + +\SubSection Adaptive counters + +It may happen that you want to compute a value during one run of +\TeX, and use it in the next. An example is the fact that this manual +states the total number of pages on the title page. For this you can +use \refcs{AdaptiveCounter} + \Ver>\AdaptiveCounter:LastPage<Rev +which is like \cs{NewCounter}, except that the value of this counter +gets written to the \file{.aux} file. + +There are two ways of setting an adaptive counter: you can simply use +it in some construct (for instance through a counter synonym; +section~ref[sec:counter:repr]), or you can set it explicitly, for +instance as + \Ver>\SetCounter:LastPage=PageValue<Rev +See how this manual does it. + +\SubSection Examples of counter usage + +Items start at the value of one, so if a starting value of zero is +necessary, the following will work +\Ver> +\Enumerate \SetCounter:item=-1 +\item ...<Rev + + +\Section[sec:font] Font selection + +In \Lollipop, choosing a font is done through three parameters: +\Description\item Typeface +A collection of related styles and sizes. The typeface is set by the +command \refcs{Typeface}. +\item Style +Italic, bold, roman, typewriter. You know. The style is set by the +command \refcs{Style}. +\item PointSize +The size of a font in typographical points ($72.27$ per inch). +The pointsize is set by the command \refcs{PointSize}. +\> + +The most common change of font is a change in style. Therefore, +issuing a command such as \Ver>\Style:bold<Rev immediately changes +the font to the bold of the current typeface in the current pointsize. + +However, issuing a command such as \Ver>\Typeface:GoudyOldStyle<Rev +or \Ver>\PointSize:28<Rev will not change the font, since such +changes are usually accompanied by a change in style. In case that an +immediate switch is necessary, the command +\refcs{SetFont} can be given. +This evaluates the current value of the typeface, style, and +pointsize commands, and sets the font accordingly. + +A number of typeface names have been predefined in \Lollipop, +however, in order to print them your printer (software) must have them +available. + +\Example +\SerifFace \PointSize:12 +\Style:roman This \Style:italic sentence \PointSize:10 has +\SetFont way \SansFace \Style:roman too \SetFont many +\PointSize:12 \SetFont font \Style:bold changes. +\ExampleStop + +(The commands \cs{SerifFace} and \cs{SansFace} are defined in +the master file of this manual, and serve to make this manual +formattable on any system.) + +\SubSection Relative size changes + +Apart from setting the pointsize explicitly, it is also possibly to +make size changes relative to the current size. For instance, +\refcs{PointSizeLarger} and \refcs{PointSizeSmaller} with an optional +argument indicating the size of the change can be used. These +commands are not cumulative. + +\Example +\SerifFace +\PointSize:9 \SetFont Every once in a while,\SaveFont +\PointSizeLarger[2] shouting \PointSizeLarger helps. +\PointSizeSmaller[2]But most of the times it doesn't. +\RestoreFont Unfortunately. +\ExampleStop + +Similar to the changes in mathematics mode to script and scriptscript +size, the same relative changes are available in text mode through +the control sequences \refcs{script} and \refcs{scriptscript}. +The control +sequence \refcs{normal} can be used to restore the default size. + +Here is one application of such relative changes: +\Ver> +L\kern -.3em\raise .35ex\hbox {\script A}\kern -.1em\TeX<Rev +which gives definition of the \LaTeX\ logo that is independent +of typeface, size and style. + +The relative sizes of script and scriptscript fonts are by default at +$70\%$ and $50\%$, but they can be set explicitly by +\Ver>\PointSizeScriptSizes:10=10,7,5<Rev +This also gives the possibility to have the \cs{normal} size to be +different from the surrounding pointsize. + +\SubSection Typeface definition + +Defining a typeface means telling \Lollipop\ how the external font +name, that is, the name of the \n{tfm} file, is to be constructed from +the internal parameters. The command \refcs{DefineTypeface} takes four +parameters and an optional fifth. The parameters are in sequence +\Enumerate\item The internal name of the typeface: the name that is +given to the \cs{Typeface} command. +\item The root of the external file name. It is assumed that all +font names of different styles and sizes are constructed by appending +characters to this base. +\item Suffixes corresponding to the styles that are available. +\item Suffixes corresponding to the sizes that are available. +\> + +Here is the definition of the Computer Modern typeface: + +\Ver> +\DefineTypeface{ComputerModern}{cm} + {roman:r; slant:sl; italic:ti; mitalic:mi; bold:bx; typewriter:tt; + default:r;} + {<6:5; <7:6; <8:7; <9:8; <10:9; <11:10; + <12:10 \scaled\magstephalf; + <14:10 \scaled\magstep1; <16:10 \scaled\magstep2; + <20:10 \scaled\magstep3; >19:10 \scaled\magstep4; + default:10;}<Rev + +Actually, not all combinations of styles and sizes are available. +That's where the optional argument comes in. This argument can be +used to specify with \TeX\ conditionals exceptional style/size +combinations. Here some trickery is needed: internally the size is +stored in \cs{Fsize}, and in order to use this parameter we need to +make the at-sign a letter temporarily. + +\Ver>\makeatletter +\DefineTypeface{Compu ... + ... + default:10;} + [\ifStyle:italic \ifnum\Fsize<7 ti7\fi\fi + \ifStyle:typewriter \ifnum\Fsize<8 tt8\fi\fi]<Rev + +You may have noticed that this scheme is not all-powerful. Thus +I~found it easier to move all Computer Modern sans serif fonts into a +new typeface: \n{ComputerSans}. + +For other typefaces specifying the size suffix may be much easier +than for Computer Modern. For instance, here is the definition of the +PostScript Helvetica typeface. + +\Ver>\makeatletter +\DefineTypeface{psHelvetica}{helv} + {roman:; italic:i; mitalic:i; bold:b; default:;} + {default: at \Fsize pt;} +\makeatother<Rev + + +\SubSection Math fonts + +Switching styles in math mode should be possible: +$${\Style:bold x\Style:roman y}z$$ + +\SubSection Other font matters + +The combination \refcs{SaveFont} with a subsequent +\refcs{RestoreFont} can +be used to save and restore the current font. + +An abbreviation for a font can be defined by +\Ver>\DefineFont:name=face,size,style<Rev +This has the same effect as +\Ver>\def\name{\TypeFace:face \PointSize:size \Style:style }<Rev +but it takes considerable less processing inside \TeX. + +Even if you don't use Computer Modern as your main typeface, the +typewriter style is not bad, so a control sequence +\Ver> +\def\tt{\Typeface:ComputerModern \Style:typewriter }<Rev +has been given that makes \refcs{tt} always refer to the +\n{cmtt} fonts. You're at liberty to change this, of course. + +\Section Baselineskip + +Corresponding to a font size usually the baseline skip has to change. +By default a fixed ratio of~$1.2$ for this is taken, for instance +using a 12~point baseline skip for 10~point fonts. Changing the ratio +can be done by +\Ver>\BaselineSkipPointSizeRatio:1.3<Rev + +If only for some specific size the baseline skip has to deviate from +the default ratio, then this can be set by +\Ver>\SetPointSizeBaselineSkip:9=12<Rev + +\Section[sec:indent:control] Indentation Control + +\SubSection To indent or not to indent + +In most documents there is a general rule that all paragraphs indent +unless a certain condition, or that they do not indent unless certain +special conditions hold. For \Lollipop\ documents this is determined +by the command \refcs{AlwaysIndent}, with values \n{yes}/\n{no}. + +To override this default setting a command \refcs{Indent} +(with values \n{yes}/\n{no}) exists, but that is mostly useful as an +option in generic constructs, and even there it will not be used much. +See section~\ref[sec:opt:indent] for options relating to indentation. + +Important: never set \cs{parindent} to zero. Preventing indentation +globally should be done through \ver>\AlwaysIndent:no>. + +\SubSection[sec:basic-indent] Basic indent + +There is a quantity \refcs{basicindent} that is used on the first +indentation level (see the next section for an explanation of these +levels). At the start of a document it is set to the then current +value of \cs{parindent}. You can override that by +\refcs{BasicIndentIsSet}: give +\Ver>\BasicIndentIsSet:no<Rev before the \cs{Start} command. + +This way, setting \cs{parindent} in the style definition controls the +indentation in the whole document. + +\SubSection Indentation levels; indentation size + +When \Lollipop\ decides that text should be indented, it refers to a +list of indentations for the exact amount. This list contains +indentation amounts for each `level' of indentation: initially the +level is one, and if you nest constructs that indent (for instance +using a list inside a list) the level goes up one step per nested +construct. + +By +default the indentation on different levels is a fraction of the +\cs{basicindent}. Thus you can regulate the indentation on +all levels simultaneously by resetting the \cs{basicindent}. + +\Example +\Distance:basicindent=15pt +\DefineList:TestList item:left itemCounter item:stop Stop +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\Distance:basicindent=25pt +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\ExampleStop + +The amount of +indentation on a certain level can be set explicitly with +\refcs{LevelIndent}. + +\Example +\Distance:basicindent=15pt +\LevelIndent:2=20pt +\DefineList:TestList item:left itemCounter item:stop Stop +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\ExampleStop + +In fact, sometimes you may want to know the name of the indentation +on a certain level. This is a control sequence such as +\refcs{levelindentii} for the second level. You get the idea. + +\SubSection Manipulating the indentation level + +Every once in a while it can be useful to move to a next indentation +level, or to return to a previous level. For this +the two commands \refcs{PushIndentLevel} and \refcs{PopIndentLevel} are +available. One application is for `interrupted lists': + +\Example +\Itemize\item One +{\par\PopIndentLevel Interrupted text!\par} +\item Two\> +\ExampleStop + +See chapter~\ref[chap:external-files] for examples of the use of +\cs{PushIndentLevel} + +\Section Margins + +By default, \Lollipop\ tries to keep straight margins. You can change +its mind about that by \refcs{FlushRight} and \refcs{FlushLeft} +which are tests: +\Ver>\FlushRight:no \FlushLeft:no<Rev +If the margins are not flush, the stretchable white space used +is \refcs{rightmarginstretch} and \refcs{leftmarginstretch}, +which can be set by \cs{Distance}. + +You have to set the amount of stretch {\it before} specifying that +the margins will not be flush. The \cs{FlushRight/Left} commands take +the current value whenever they are called. + +\Section White Space + +White space can be indicated by \refcs{hwhite} and \refcs{vwhite}. +They are often useful in style definitions. Use: +\Ver>\vwhite:15pt<Rev +or \Ver>\hwhite:{15pt minus 3pt}<Rev +for stretch and shrink. The command \refcs{white} is independent +of the mode, and it expands to \cs{hwhite} or \cs{vwhite} +depending on the prevailing mode of \TeX. + +The command \refcs{fillup} is mostly useful in style definitions: +it tries to fill up as much white space as is possible. +For instance +\Ver> line:start litteral:foo fillup litteral:bar line:stop<Rev +will push \n{foo} and \n{bar} as far apart as is possibly +within the margins. + +\ImpNote +All three control sequences \cs{white}, \cs{hwhite}, \cs{vwhite} +have internal equivalents, for instance +\Ver>\def\white:#1 {\@white{#1}}<Rev +\ImpNoteStop + +\Section[sec:com:distance] Distances + +The command \refcs{Distance} can be used +to declare a name for a certain +distance, or in more correct \TeX nical lingo, for a certain piece of +glue. For instance, declaring that + \Ver>\Distance:oneline=15pt<Rev +means that you can specify in some constructs +\Ver>\DefineFoo:Bar whitebefore:oneline whiteafter:oneline<Rev +If you change your mind later about the value of \n{oneline} you only +need to change one line in the style definition. + +Since the second parameter of \cs{Distance} is bounded by a space (or +the line end, whatever comes first), you can specify stretchable +distances by enclosing \n{plus} and \n{minus} parts in braces: +\Ver>\Distance:oneline={15pt plus 2pt minus 3pt}<Rev + +The effect of \cs{Distance} is global. Let me know if you don't +like it. + +\SubSection Distance synonyms + +Another use of \cs{Distance} is to define one distance as a synonym +of another. This may come in handy if you use some basic distance, +such as \n{oneline} for several purposes. Example: if you specify +\Ver>\Distance:whitebefore=oneline<Rev +than the whitespace before a construct will be taken to be +\n{oneline} if you don't use the \opt{whitebefore} option explicitly. + +\SubSection[sec:adapt-distance] Adaptive distances + +Suppose you want to declare a section heading as + \Ver>\DefineHeading:Section ... + block:start [...] fillupto:widelabel title<Rev +where \cs{widelabel} is the width of the widest label that +occurs in your document. This requires just a tad of \TeX\ +programming. Just copy the details from the example below, which is +the definition of \cs{Section} in this manual. + +By declaring something a \refcs{AdaptiveDistance} instead of just +\cs{Distance} its value gets written to the \file{.aux} file at the +end of the run, and restored in the next run. The second argument is +simply the default value, in case you don't have an auxiliary file +yet. + +\Ver>\AdaptiveDistance:WidestLabel=15pt +\def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel + \global\WidestLabel\BlockWidth\fi} +\DefineHeading:Section + whitebefore:{20pt plus 2pt} whiteafter:14pt + line:start PointSize:14 Style:italic + block:start block:start ChapterCounter . SectionCounter + Spaces:1 block:stop MeasureLabel + fillupto:WidestLabel + title line:stop + external:contents title external:stop + label:start ChapterCounter . SectionCounter label:stop + Stop<Rev + +Note how two nested blocks are used: the first is to measure the +label, and the width is written to the adaptive distance by means of +a small macro; the second block is to fill out the white space. + +If you want the paragraph indentation to depend on this adaptive +width, you can give + \Ver>\StartCommand{\Distance:parindent=WidestLabel }<Rev +to set \cs{parindent} at the start of the document. +See section~\ref[sec:doc-start-stop] and~\ref[sec:basic-indent]. + +\Section[sec:InputFile] Input Files + +Parts of a document can be loaded by +\Ver>\InputFile:parta +\InputFile:partb<Rev +et cetera. A~document part loaded by \refcs{InputFile} always starts +on a new page. In section~\ref[sec:ref-local] it was already +explained how local references for such files can be created. + +Perhaps most importantly, loading files this way provides a form of +error checking; \Lollipop\ checks at the end of such a file whether all +used constructs are balanced properly. + + +\Section[sec:tests] Tests + +Users can define tests: +\Ver>\DefineTest:SomethingTheMatter<Rev +which are set like any other test: +\Ver>\SomethingTheMatter:yes<Rev +or \Ver>\SomethingTheMatter:no<Rev + +Tests can be used as \Ver>\ifSomethingTheMatter ... \else ... \fi<Rev +Like any other conditional, test can be used inside constructs. +\Ver>\DefineFoo:Bar [...] + ifSomethingTheMatter [...] fi + [...] Stop<Rev + +\Section Goodies + +\SubSection List commands + +Lollipop does a lot of list processing internally, and a few +of the commands have been made available to the user. + +\Description\item \refcs{NewList} +creates a list, and sets it to empty: + \Ver>\NewList:mylist<Rev + \item \refcs{EmptyList} +just empty a list. + \item \refcs{TheList} +inserts the list. This will typeset the contents of it. + \Ver>\TheList:mylist<Rev + \item \refcs{AppendToList} +adds data to a list. \Ver>\AppendToList:mylist={my data}<Rev +The data are terminated by a space or line end, hence the braces. +\> + +\SubSection Programming Tools + +A few commands are useful for the Lollipop style designer who wants +to write more sophisticated macros (see for instance the address book +macros in the last chapter). + +\Description\item \refcs{UndefinedCS} +is a test on control sequences. + \Ver>\if\UndefinedCS{testcs} ... \else ... \fi<Rev + \item \refcs{EqualString} +tests equality of strings. + \Ver>\if\EqualString{one}{two} ... \else ... \fi<Rev + \item \refcs{EqualStringX} +tests equality of strings, using only expansion. + \Ver>\if\EqualStringX{one}{two} ... \else ... \fi<Rev + \item \refcs{StringBefore} +tests lexicographic ordering of strings. The string are not supposed +to contain characters with char codes~0, 127,~255. + \Ver>\if\StringBefore{one}{two} ... \else ... \fi<Rev + \item \refcs{NextChar} +chooses between two actions, based on the next character. + \Ver>\if\NextChar[{\macro}{\macro[default]} ...<Rev + \item \refcs{IsEmptyList} +can test whether an argument is empty. + \Ver>\if\IsEmptyList{#1} ...<Rev +is true for calls such as \ver>\macro{}>. + \item\refcs{loop} +can be used for repeated execution of statements. (Users of plaing +\TeX\ may recognize this macro; it is slightly extended here +to include the \cs{else} case.) It is +used as: + \Ver>\loop ... \if ... \repeat<Rev +of \Ver>\loop ... \if ... \else ... \repeat<Rev + + + \> + +\SubSection[sec:everypar] \cs{everypar} + +The \TeX\ primitive \cs{everypar} should not be used any more. +Instead use the command \refcs{EveryParagraph} as if you are setting +a token list: + \Ver>\EveryParagraph{ ... }<Rev + +\SubSection[sec:everymath] \cs{everymath} + +The \TeX\ primitive \cs{everymath} should not be used any more. +Instead use the command \refcs{EveryMath} as if you are setting +a token list: + \Ver>\EveryMath{ ... }<Rev + +\SubSection[sec:everydisplay] \cs{everydisplay} + +The \TeX\ primitive \cs{everydisplay} should not be used any more. +Instead use the command \refcs{EveryDisplay} as if you are setting +a token list: + \Ver>\EveryDisplay{ ... }<Rev + +\SubSection Allocation + +The commands \refcs{SaveAlloc} and subsequent \refcs{RestoreAlloc} save and +reset the internal \TeX\ allocation counters. + +\endinput + +% 2014/04/13 Added some notes about \EveryMath, and +% \EveryDisplay. Also the wrong spelling of `note' changed +% to `not' in `sec:everypar'. +% 2014/04/11 Changed \n{tty} style to \n{typewriter} style +% 92/11/18 Adaptive distances explained +% 92/11/20 Adaptive counters explained +% 93/05/13 changes in font macros |