diff options
Diffstat (limited to 'macros/lollipop/doc/manual/comm.tex')
-rw-r--r-- | macros/lollipop/doc/manual/comm.tex | 642 |
1 files changed, 0 insertions, 642 deletions
diff --git a/macros/lollipop/doc/manual/comm.tex b/macros/lollipop/doc/manual/comm.tex deleted file mode 100644 index 2876acf959..0000000000 --- a/macros/lollipop/doc/manual/comm.tex +++ /dev/null @@ -1,642 +0,0 @@ -% 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 |