diff options
author | Norbert Preining <norbert@preining.info> | 2024-01-31 03:01:01 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2024-01-31 03:01:01 +0000 |
commit | 79e1bbc1ad6b308aa2074540b2afd43b6a72ce03 (patch) | |
tree | 32074e03eec88cf72e5973ddff176a0534c77dff /macros/lollipop/doc/manual/extern.tex | |
parent | 084f5d8435744b7ea7ef487ec111a7bfd100ed62 (diff) |
CTAN sync 202401310301
Diffstat (limited to 'macros/lollipop/doc/manual/extern.tex')
-rw-r--r-- | macros/lollipop/doc/manual/extern.tex | 428 |
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 |