% struct.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 The structure of Lollipop

Lollipop provides tools for realizing the style or layout of a
document. Some of these tools are macros ready to be used by the end
user; they concern for instance selection of fonts.
Others, the `generic constructs', are for the style designer so that
she can use them to program the macros for the user.

\Section[sec:doc-start-stop] Lollipop Files

Any Lollipop document has to have a \cs{Start} and \cs{Stop} command.
Before the \cs{Start} there can be style definition commands, but no
text. For a number of reasons it is advisable to put as much of the
style definition before the \cs{Start} command as possible. You can
do that easily by loading the style as an input file, or by first
dumping it as a format (see section~\ref[sec:style-dump]).

\ImpNote
Before the \cs{Start} command, \cs{everypar} contains an error
message. The start command installs the default value for
\cs{everypar}.
\ImpNoteStop

Both the start and the stop file load the \file{.aux} auxiliary file.
None of this should concern you, really. Expert users who want to
have certain actions performed at the start of the document may want
to use \refcs{StartCommand} to specify what they wish done. See
section~\ref[sec:adapt-distance] for an example.

\Section Generic Constructs

\label[generic:construct]\label[option:macro]
There are five `generic constructs': headings, lists, text blocks, page
grids, and external items. For each construct type there is a defining
command, for instance \cs{DefineHeading}
which is followed a list of `options', terminated by the word `Stop'.

Options (possibly with values) have to be separated by a
space or a line end; the keyword \opt{Stop} has to be followed by a
space or a line end.
Options may have zero, one or two values; if there are values, then
the first one is separated from the option by a colon, the second is
separated from the first by an equals sign.

\Ver>\DefineFoo:Bar optiona optionb optionc:value
    optiond:valuea=valueb optione
    optionf Stop<Rev

 As a result of this definition, a command
\cs{Bar} is created. If the \con{Foo} construct was a \con{List} or
\con{TextBlock}, an additional command \cs{BarStop} is created.
 
This command can then be used in the ordinary way, for instance
after \ver>\DefineHeading:Foo> you can type
\Ver>\Foo The title<Rev and after \ver>\DefineList:Foo> you can type
\Ver>\Foo
\item One item
\item And another
\FooStop<Rev

\ImpNote
Actually, this `Stop' business can be customized for other languages.
The file \file{tools} has the following lines:
\Ver>
\def\stop@command@suffix{Stop}
\def\stop@command{\@command\stop@command@suffix}<Rev
\ImpNoteStop

\Section Options

Options are mostly used to specify how a construct will look. Some
options, for instance \opt{title}, indicate material that will appear
on the page. Other options are interpreted as commands, for instance
\opt{IndentAfter:yes} in the definition of a heading indicates that
the first paragrah after such a heading will indent.

In addition to keywords that only exist as options, commands can
be used as options. Also, single characters are accepted as options.
For instance a definition of a subsection heading can contain: 

\Ver>\DefineHeading:SubSection 
    [...]
    SectionCounter . SubSectionCounter
    [...] Stop<Rev
(Here and later the \n{[...]} will denote arbitrary omitted text.)
This definition contains the commands \cs{SectionCounter} and
\cs{SubSectionCounter} and the \n{.} character.

If a number of options appears together in a number of constructs it
is convenient to have an abbreviation for them. This can be done with the command
\refcs{OptionsMacro} as follows. The options that appear together are
given a common name
 \Ver>\OptionsMacro:baz=optiona optionb:value optionc
    Stop<Rev
(be sure to leave
no spaces around the equals sign) and this name is then used as
 \Ver>    macro:baz<Rev
in the option list wherever the options are needed. 

This is for
instance a good way of specifying identical white space around all
sorts of constructs without duplicating the typing each time.
However, it is only for your convenience: it doesn't save any \TeX\
resources or processing time.

\Section[sec:error-msg] Popular error messages. Not!

Lollipop is a macro package on top of an existing program, \TeX.
Therefore it is inevitable that you will get \TeX\ error messages
every once in a while. Some of these may confuse you.

Here are a few of the errors that I~keep making.

\SubSection Missing \cs{endcsname} inserted

If you forget the second parameter in a \cs{Distance} or
\cs{SetCounter} command, writing for instance
 \Ver>\Distance:TheWidth<Rev
instead of \Ver>\Distance:TheWidth=15pt<Rev
 \TeX\ will scan
forward, and it can easily bump into something that is highly
unexpected given the context. If this is a \cs{def} or \cs{Define...}
command, a `missing \cs{endcsname}' results. If a blank line follows
the incomplete declaration, the following section applies.

\SubSection  Paragraph ended before something was complete

\TeX\ has found a blank line (or a~\cs{par} command) where this was
not expected. See for instance the previous section.

\SubSection Missing number

You have used something that you thought was the name of a control
sequence, but it wasn't. Example:
\Ver>\Distance:parskip=parundent<Rev
Since \cs{parundent} is undefined, \Lollipop\ thought you were
writing something like
 \Ver>\Distance:parskip=5pt<Rev

And yes, the message refers to `number' even though what is missing
is a distance.

\ImpNote
\iSection Defining Generic Constructs

The \cs{Define...} commands are not defined explicitly, instead they
are generated by a call such as
\Ver>    \@GenericConstruct{Heading}<Rev
Full definition:
\Ver>\def\@GenericConstruct#1{<Rev
to be used as \ver>\@GenericConstruct{Foo}>;
\Ver>    \append@to@list{@gencons}{\\#1;}<Rev
book keeping of existing generic constructs;
\Ver>    \csarg\newtoks{#1@defaults}
    \csn #1@defaults\ecs{}<Rev
default commands to be executed whenever 
an instance of this construct
is defined;
\Ver>    \csarg\def{add@#1@default}##1%
             {\append@to@list{#1@defaults}{##1}}<Rev
the command \cs{add@Foo@default}
to add defaults for this construct;
\Ver>    \Install@Noops{#1}<Rev
possibility to generate error msgs for the use of an option that is
not allowed for this type of construct;
\Ver>    \csarg\def{Define#1}:##1 {<Rev
instances of this construct will be defined
by a statement like \ver>\DefineFoo:Bar>;
\Ver>        \def\@name{##1}\def\@class{#1}
        \Tmessage[def]{Defining a #1: ##1}<Rev
\ver>DefineFoo:Bar> leads to \cs{@name} begin \n{Bar},
\cs{@class} being \n{Foo};
\Ver>        \the\generic@defaults
        \csarg\the{#1@defaults}<Rev
unpack token lists of generic and specific default actions;
\Ver>        \Get@Items}<Rev
start recursive processing of list of options. This ends the
definition of \cs{DefineFoo}; the definition of 
\cs{@GenericConstruct} ends with
\Ver>    \csarg\def{@#1Option}##1%
       {\csarg\def{#1@##1}####1####2}<Rev
which defines the \cs{@FooOption} macro; see~\ref[imp:option].
\Ver>    }<Rev

\iSection Items Processing

Processing the list of items is recursive; at the end some concluding
actions have to be taken, mostly the actual definition of the
construct.

First we have to filter out empty arguments, which can be caused by
the use of option macros (\ref[option:macro], \ref[imp:option:macro]).

\Ver>\def\Get@Items#1 {\if\EmptyList{#1}\let\get@next@item\Get@Items
    \else\def\get@next@item{\@Get@Items#1 }\fi
    \get@next@item}<Rev

Next, check if the argument is \opt{Stop} (defined by
\ver>\NewDummy{Stop}>, \ref[imp:new:dummy]), in which case you
have reached the end of a generic definition, and can start performing
the final rites. Otherwise, dissect this option item 
and go on with the rest
of the options.
\Ver>
\def\@Get@Items#1 {\let\get@next@item=\Get@Items
    \csarg\ifx{#1}\Stop
          \the\generic@stop@defaults
          \let\get@next@item=\relax
    \else \Item@or@Macro#1::. \fi \get@next@item}<Rev

The \n{::.} concluding \cs{Item@or@Macro} accomodates one,
possibly empty, argument.

\iSection Options\label[imp:option]\label[imp:option:macro]

Options can either be specific, defined as
\Ver>\@FooOption{Bar}{ [...] }<Rev
in which case the option \opt{Bar} can only be used inside
a call to \cs{DefineFoo},
or they can be generic, defined as
\Ver>\@GenericOption{Bar}{ [...] }<Rev
For both definitions, the definition text can use up to two parameters.
Parameters are given to the options as
\Ver>    optiona:par1 optionb:par1=par2<Rev

Specific options are defined by the line
\Ver>
    \csarg\def{@#1Option}##1%
         {\csarg\def{#1@##1}####1####2}<Rev
in \cs{@DefineGenericConstruct}; a call
\Ver>\@FooOption{Bar}{ ... }<Rev
expands to
\Ver>\def\Foo@Bar#1#2{ ... }<Rev
Generic options are defined by the
following command:
\Ver>\def\@GenericOption#1{
    \append@to@list{@GenericOptions}{\\#1;}
    \csarg\def{Option@#1}##1##2}<Rev
A call
\Ver>\@GenericOption{Bar}{ ... }<Rev
expands to
\Ver>\def\Option@Bar#1#2{ ... }<Rev

\ImpNoteStop

\endinput