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