% 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