% 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