summaryrefslogtreecommitdiff
path: root/macros/plain/formats/lollipop/doc/manual/extern.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/extern.tex')
-rw-r--r--macros/plain/formats/lollipop/doc/manual/extern.tex428
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