diff options
Diffstat (limited to 'Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex')
-rw-r--r-- | Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex | 264 |
1 files changed, 264 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex new file mode 100644 index 00000000000..b390cff88d5 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex @@ -0,0 +1,264 @@ +% struct.tex copyright 1992 Victor Eijkhout +% copyright 2014 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 |