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, 0 insertions, 264 deletions
diff --git a/macros/lollipop/doc/manual/struct.tex b/macros/lollipop/doc/manual/struct.tex
deleted file mode 100644
index 7590b5a365..0000000000
--- a/macros/lollipop/doc/manual/struct.tex
+++ /dev/null
@@ -1,264 +0,0 @@
-% 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