diff options
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/extern.tex')
-rw-r--r-- | macros/plain/formats/lollipop/doc/manual/extern.tex | 428 |
1 files changed, 428 insertions, 0 deletions
diff --git a/macros/plain/formats/lollipop/doc/manual/extern.tex b/macros/plain/formats/lollipop/doc/manual/extern.tex new file mode 100644 index 0000000000..aff8e97d59 --- /dev/null +++ b/macros/plain/formats/lollipop/doc/manual/extern.tex @@ -0,0 +1,428 @@ +% extern.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[chap:referencing] +Referencing + +In manuals and scientific documents you often want to write something +like `see Chapter~4'. But what if you shuffle the chapters a bit? It +would be nice if the number would be updated automatically. With +\Lollipop, as with many other \TeX\ macro packages, this is easily +done. + +Here is an example to set the mood for the rest of this chapter. +The sort of thing that is referred to most is a heading. So suppose +you want to refer to a section number. + +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title + line:stop Stop +\TestSection[one:section?] First section\par +After this section will come section~\ref[other:section!]. + +\TestSection[other:section!] Another section\par +This is the section that came after section~\ref[one:section?]. +\ExampleStop + +\Section What and how do you reference? + +You can reference not only headings but everything that has a +counter. Thus all generic constructs can be referenced, and in +addition you can reference item numbers in a list (there are examples +of this latter possibility in section~\ref[sec:bib]). The simplest way +of referencing something is to put the key in square brackets behind +it: + +\Ver>\Section[this:section] The title of This Section<Rev +You can then reference the key by \refcs{ref}, or the page +where it appeared by~\refcs{pgref}: +\Ver>Section \ref[this:section] on page \pgref[this:section]<Rev + +As you may have guessed from the above examples, keys can contain all +sorts of characters. Only brackets, braces, and the hash sign are +excepted. You get an error message if you try to use the same key +twice. + +Another way of declaring a key is to use the command \refcs{label} +carrying the key +\Ver>\label[the:key]<Rev +This can be useful if you want to declare two keys for a single +reference. Make sure that the \cs{label} command is not part of the +title. Unexplained phenomena occur if you do that. Instead put the +label after the construct you want to reference: +\Ver>\Section Precautions and remedies + +\label[sec:precautions]\label[sec:remedies] +In this section ...<Rev + +\Section[sec:shape:reference] The shape of the reference + +By default, a reference consists of just the number of the thing you +reference. There are two ways in which you can change this, one +systematic, and one on-the-fly. + +\SubSection Defining the shape of the reference + +You can customize the way an object is +referenced by using the option \refopt{label} in its definition. For +instance, often you want things like parentheses around references. +Putting this information in the label definition saves you a lot of +work in case you change your mind later. + +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start ( TestSectionCounter ) label:stop Stop +\TestSection[one:section?2] First section\par +After this section will come section~\ref[other:section!2]. + +\TestSection[other:section!2] Another section\par +This is the section that came after section~\ref[one:section?2]. +\ExampleStop + +Another use of customized labels is including other counters in the +reference: + +\Example +\DefineHeading:TestChapter + line:start Style:bold TestChapterCounter / title line:stop Stop +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start TestChapterCounter . + TestSectionCounter label:stop Stop +\TestChapter First chapter\par +Pretty short chapter +\TestChapter Second chapter\par +\TestSection[one:section?3] First section\par +After this section will come section~\ref[other:section!3]. + +\TestSection[other:section!3] Another section\par +This is the section that came after section~\ref[one:section?3]. +\ExampleStop + +A more surprising application of explicit definition of labels is +inclusion of the title in the reference. +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start TestSectionCounter literal: Spaces:1 + Style:italic title label:stop Stop +\TestSection[one:section?4] First section\par +After this section will come section~\ref[other:section!4]. + +\TestSection[other:section!4] Another section\par +This is the section that came after section~\ref[one:section?4]. +\ExampleStop + +\SubSection[sec:exp-ref] Explicit specification of the reference + +For every specific object referenced you can specify the reference by +using an optional argument before the label key. Have a look at the +next example. + +\Example +\DefineHeading:TestSection counter:A + line:start Style:bold TestSectionCounter . Spaces:2 title line:stop + Stop +\TestSection[ref:one] Lalala\par +This is before section \ref[ref:two]. +\TestSection<`the Didi section'>[ref:two] Dididi\par +This is after section \ref[ref:one]. +\ExampleStop + +This mechanism is also used in lists, where it's mostly useful for +bibliographies generated by Bib\TeX; see section~\ref[sec:BibTeX]. + +\Section[sec:ref-local] Local references + +Some documents are +collated out of parts that were documents in themselves. +The \Lollipop\ command \cs{InputFile} facilitates in a number +of ways working with such a segmented file (see +section~\ref[sec:InputFile]). One of the problems with input files is +that in such a case it may happen that the same reference key is used +in more than one part of the document. This phenomenon is +not at all unknown in multiple authored documents. Ordinarily this +would result in incorrect references. + +To prevent such collisions \Lollipop\ can use local +references: the command \refcs{LocalReferences} has default \n{no}, +and specifying +\Ver>LocalReferences:yes<Rev +creates local \file{aux} files for each input file. + +\Section[sec:bib] Bibliography citations + +\Lollipop\ has an interface to Bib\TeX. However, since a bibliography +is just a list, referencing items in it is quite easy, even if you +don't use Bib\TeX. + +\SubSection Bibliographies without Bib\TeX + +This section doesn't tell you anything that cannot be found elsewhere +in this manual. The following two examples define a bibliography as +just a list, and by giving labels to the items you can refer to them. + +\Example +\DefineList:BibList item:left [ itemCounter ] item:stop + label:start [ itemCounter ] label:stop Stop +In this example we shall have occasion to refer to +\ref[Abee80] and~\ref[Ceede79].\par +\Indent:no Bibliography +\BibList \item[Ace55] C.D. Ace, Inscrutible title. +\item[Abee80] E.F. Abee, Worthless drivel. +\item[Ceede79] G.H. Ceede, Contractual obligation. +\> +\ExampleStop + +Here is a way to customize the label (if you need to refresh your +memory about description lists, see +section~\ref[sec:description:list]). + +\Example +\DefineList:BibList item:left [ itemCounter ] item:stop + label:start ( description ) label:stop Stop +In this example we shall have occasion to refer to +\ref[Abe80] and~\ref[Ceedee79].\par +\Indent:no Bibliography +\BibList \item[Aace55] Aace55 +C.D. Aace, Inscrutible title. +\item[Abe80] Abe80 +E.F. Abe, Worthless drivel. +\item[Ceedee79] Ceedee79 +G.H. Ceedee, Contractual obligation. +\> +\ExampleStop + +\SubSection[sec:BibTeX] Bibliographies with Bib\TeX + +\Lollipop has an interface to the popular Bib\TeX\ +bibliography database program, based on the `BtxMac' macros +by Karl Berry and Oren Patashnik. \Lollipop\ is set up for them, you +only have to \cs{input} the file \file{btxmac.tex}. (The version +of btxmac used to test this is \n{0.99h}.) You can find global +information about Bib\TeX\ in the \LaTeX\ book~{%\tracingmacros=2 +%\tracingcommands\tracingmacros +\bibref[La:book]}, +since Bib\TeX\ was +originally written for \LaTeX. + +Since there is some redefining going on between btxmac and \Lollipop\ +you have to load the btxmac file before the \cs{Start} command (see +section~\ref[sec:doc-start-stop]). + +Since the btxmac file already has a default way of formatting the +bibliography you can get away with just putting the lines + \Ver>\bibliography{ <bfile> } +\bibliographystyle{ <bstyle> }<Rev + in your file wherever you want the bibliography. + +If you want to define your own bibliography, you have to use +\refcs{DefineBBL} which is practically a synonym for +\ver>\DefineList:BBL>, so you can see in the `lists' chapter of this +manual what options apply. + +For example: + \Ver>\DefineBBL line:start Style:italic literal:Literature line:stop + item:left [ begingroup Style:bold itemCounter + endgroup ] item:stop + Stop<Rev + +You refer to a bibliography item by \refcs{bibref}, as in +\ver>\bibref[Knuth80]>. This command has a very simple definition + \Ver>\def\bibref[#1]{[\ref[#1]]\nocite{#1}}<Rev +so you can easily redefine it. For instance + \Ver>\def\supref[#1]{$^{\rm \ref[#1]}$\nocite{#1}}<Rev + will make your references into superscripts. +Make sure that +the call to \cs{nocite} appears, because that generates the request for +Bib\TeX. + +The \Lollipop\ command \ver>\WriteExtern:no> (see +section~\ref[sec:write-extern]) defines \cs{noauxfile} to prevent +regeneration of the bib entries in the \file{.aux} file. +You don't have to do that anymore. + +\Section Obscure details + +For the sake of efficiency, not all macros in Lollipop automatically +accept labels for referencing, only the ones that use the \n{label} +option, or that have a counter (remember, the default form of the +reference is just the counter). If you want a macro that has no +counter and no label specification to accept a label, use the option +\refopt{haslabel}. One reason for doing this is that you have access to +the label itself through the control sequence \refcs{RefLabel}. + +\Chapter[chap:external-files] External Files + +Some document require information to be collected during a run. Such +information typically is a table of contents or index, and it is +gathered in an external file. (The reason for gathering such +information in a file at all is that often some external manipulation, +for instance sorting of an index, is needed.) Since there are many +possibilities for external files (mathematical monographs may have a +list of definitions, or a list of notations) \Lollipop\ does not +predefine such files, but supplies all of the tools for creating them. + +External files involve four actions: +\Enumerate\item The file should be declared. +\item It should be specified what information is to be written to the +file. +\item The formatting of the contents of the file has to be specified. +\item The file has to be loaded. +\> + +You can have at most 15 external files per document. + +\Section[sec:write-extern] Declaring and loading an external file + +The first act, declaring the existence of the external file is very +easy with the command \refcs{DefineExternalFile}: + an internal name and a three-character file name extension have +to be given as parameters. +\Ver>\DefineExternalFile:contents=toc<Rev +With this definition, if the document is called \file{book.tex} then +the `contents' will be gathered in a file called \file{book.toc}. +(The declaration of an external file has to come before any calls +to \cs{ExternalItem} or any options \n{external} that write +to this file.) + +For each external file \n{Foo} there is a command to determine whether +that file will be regenerated in the next run of \TeX: +\refcs{WriteFoo} with values \n{yes}/\n{no} will allow or prevent the +file being regenerated. The value \opt{yes} is default. The +command \refcs{WriteExtern} (values \n{yes}/\n{no}) +can be used to prevent writing out any external files (including the +\file{.aux} file that keeps track of references). + +The final act, loading an external file, is as easy as declaring it: +use \refcs{LoadExternalFile} as in +\Ver>\LoadExternalFile:contents<Rev +This does not cause any page breaks or headings to be set over the +loaded material, so you have to do that explicitly. + +\Section[sec:ext-option] Generating external files + +Next, macros that write to the table of contents have to declare this +information. The \refopt{external} option is used for this. +Any counter that the construct has will be written out +automatically, and the style designer usually has to specify only +that the title will be written out. +\Ver>\DefineHeading:Section + [...] + external:contents title external:stop<Rev + +There is no objection to a construct writing information to more than +one external file. + +If you write more than just \n{title} to an external file, know that +any control sequence you specify is automatically protected from +expansion. See section~\ref[opt:csname] for an exception to this. + +Other titles can be included by specifying \opt{title:OtherThing}. +Using \opt{OtherThingTitle} would not work, because of the protection +of control sequences mentioned above. + +You can write arbitrary information to an external file, if you see a +reason to do so, by \refcs{ToExternalFile}, which takes a file name +and an text argument. The example below has an instance of this +command. In order to format this information you have to define an +external construct of type \cs{anon}. + +\Section[sec:ext-item] Formatting an external file + +The hardest part is declaring the formatting of an external file. For +this a separate generic construct exists: the `external item' with +defining command \refcs{DefineExternalItem}. For example, if +\cs{Section} writes to \n{contents}, than an external item \n{Section} +corresponding to this file has to be declared. The option +\refopt{file} is use to declare to which file the external item +belongs. This way the same name can be reused for more than one file. + +\Ver>\DefineExternalItem:Section file:contents + [...] Stop<Rev + +An external item is basically a list with just one item. Thus, the +option \refopt{item} is available. The elements of an external item are +the label (the counter value), the page number where the information +was generated, and the title. +For the label (say for a construct \cs{Foo}) +an option \refopt{FooLabel} is created. +Thus the typical formating looks like +\Ver>\DefineExternalItem:Chapter file:contents + item:left ChapterLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop<Rev +In fact, a control sequence \refcs{FooLabel} is created, which +can be used in other external items. + +Since an external item is a list in itself, you have to pull a +certain trick to get items for subsections to indent further than +those for sections. This is what the command \cs{PushIndentLevel} was +designed for. + +A typical indented item looks like: +\Ver>\DefineExternalItem:SubSection file:contents + PushIndentLevel PushIndentLevel + item:left SectionLabel . SubSectionLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop<Rev + +\Section Example + +The following example is for a typical table of contents that +records sections and subsections. In good old-fashioned style, the +subsections are indented with respect to the sections. +\endinput +\Example +\DefineExternalFile:TheContents=tct +\DefineHeading:TestChapter Style:bold + line:start TestChapterCounter Spaces:2 title line:stop + external:TheContents title external:stop Stop +\DefineExternalItem:TestChapter file:TheContents + item:left Style:bold TestChapterLabel item:stop title white:5pt + Page par Stop +\DefineHeading:TestSection Style:italic + line:start TestChapterCounter . TestSectionCounter + Spaces:2 title line:stop + external:TheContents title external:stop Stop +\GoverningCounter:TestSection=TestChapter +\DefineExternalItem:TestSection file:TheContents PushIndentLevel + item:left Style:bold TestChapterLabel . TestSectionLabel item:stop + title white:5pt Page par Stop +\DefineExternalItem:anon file:TheContents begingroup + Style:italic title white:5pt Page par Stop + +\LoadExternalFile:TheContents +\TestChapter First heading\par +\TestSection First subheading\par +Some text might be nice. +\TestSection Second subheading\par +Some more text. +\ToExternalFile:TheContents={Enclosed Graphics} +\TestChapter Second heading\par +\TestSection Third subheading\par +Yet more text. +\TestSection Fourth subheading\par +And again: text. +\ExampleStop + +\endinput + +% 92/11/26 BibTeX section |