diff options
Diffstat (limited to 'macros/lollipop/doc/manual/struct.tex')
-rw-r--r-- | macros/lollipop/doc/manual/struct.tex | 264 |
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 |