summaryrefslogtreecommitdiff
path: root/macros/lollipop/doc/manual/extern.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/lollipop/doc/manual/extern.tex')
-rw-r--r--macros/lollipop/doc/manual/extern.tex428
1 files changed, 0 insertions, 428 deletions
diff --git a/macros/lollipop/doc/manual/extern.tex b/macros/lollipop/doc/manual/extern.tex
deleted file mode 100644
index aff8e97d59..0000000000
--- a/macros/lollipop/doc/manual/extern.tex
+++ /dev/null
@@ -1,428 +0,0 @@
-% 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