summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/otherformats/texsis/base/TXStags.doc
blob: 768e4f1692f26bba3aa5d2282da614ca0ac16c6f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
%% file: TXStags.doc - Tags and Labels - TeXsis version 2.18
%% @(#) $Id: TXStags.doc,v 18.1 1999/07/30 18:34:24 myers Exp $
%======================================================================*
% (C) Copyright 1989, 1992, 1997 by Eric Myers and Frank E. Paige
% This file is a part of TeXsis.  Distribution and/or modifications
% are allowed under the terms of the LaTeX Project Public License (LPPL).
% See the file COPYING or ftp://ftp.texsis.org/texsis/LPPL
%======================================================================*
\ifx\undefined\meta \texsis\input TXSdocM.doc\draft\input Manual.aux\fi


\section{Labels and Tags                \label{sect.labels}}

One of the most useful features of \TeXsis\ is that it automatically
numbers things like equations and references and lets you refer to
these things by means of symbolic names or ``labels.'' 
This section explains how to get the most use out of this labeling
mechanism. 

\subsection{Tagging}

 Here is a rough outline of how labeling or ``tagging'' works.
\TeXsis\ keeps track of numbers for equations, figures, tables,  and
other useful things in counters.  Whenever you create a new equation,
figure, table or reference the appropriate counter is incremented.  At
the same time, a new macro instruction is defined, with the label
incorporated into the name, and the definition of this macro is
simply the (new) value of the counter.  Thus if you create a displayed
equation and label it ``Newton'' then a macro called ``|\Eq.Newton|'' is
created and it is automatically defined to be whatever the next number
is for the equation.

      The actual mechanism is somewhat more subtle. Normally you can
only use letters in macro names, but \TeXsis\ uses \cs{csname} |...|
\cs{endcsname} to allow numbers and punctuation to be used in
labels.
Also, an extra |@| is added at the beginning and end of each macro
name.
If this were not done then, for example, using ``|end|'' as a label
(using \CS{tag}) could redefine \cs{end}, and you would not be able to
get out of \TeX!
So the macro containing the equation number for the equation named
``Newton'' actually ends up being named ``|\@Eq.Newton@|''.

      Once a label macro is defined you can use it to refer to the
thing it labels, and it will yield the proper number.
In the case of the equation called ``Newton,'' saying |\Eq{Newton}| is
really saying |Eq.~(\@Eq.Newton@)|.
(Again, since punctuation is not allowed in names, \TeXsis\ actually
uses \cs{csname} |...| \cs{endcsname} in the definition.)
References, equations, figures, tables, etc., all produce their
numbers in this way.

      Each of the \TeXsis\ macros which uses labels attaches to
the label a unique prefix identifying the kind of object labeled.
These objects and the corresponding prefixes are shown in
\Tbl{labels}.  
Because of these prefixes the same label can be used for different
kinds of objects.
For example, the name ``Witten'' can be used as a label for an
equation and as a reference, since their internal labels are
|Eq.Witten| and |Ref.Witten|, respectively (and in reality the names
are bracketed by |@| characters).
The prefixes are automatically inserted by \TeXsis\ macros like
\cs{Eq} and \cs{cite}.

      At the most primitive level you can always associate a label with
some value by saying \CS{tag}\arg{label\/}\arg{value}.  You can then
reference the value, whatever it is, by its name using the command
\CS{use}\arg{label\/}.  In this case if there is to be a prefix in the
label you must put it in explicitly.  Thus to say just the number of the
equation labeled ``Newton'' without any parentheses or anything you
would say |\use{Eq.Newton}|.  To get the number of the reference labeled
``Knuth'' you would say |\use{Ref.Knuth}|, which produces
``\use{Ref.Knuth}'' because ``Knuth'' is the label of the first document
we referenced in this manual and ``Ref'' is the prefix used for
references.

\table{labels}
\caption{Prefixes for labels and the corresponding counters for
various objects.}
\def\CS#1{{\tt\char92{#1}}}
\def\\{\hfill}
\ruledtable
Entity        \\| Tag Prefix    | Counter            \CR
Corollary     \\| {\tt Cor.}    | \CS{corollarynum}  \\\cr
Definition    \\| {\tt Df.}     | \CS{definitionnum} \\\cr
Equation      \\| {\tt Eq.}     | \CS{eqnum}         \\\cr
Figure        \\| {\tt Fg.}     | \CS{fignum}        \\\cr
Lemma         \\| {\tt Lem.}    | \CS{lemmanum}      \\\cr
Reference     \\| {\tt Ref.}    | \CS{refnum}        \\\cr
Table         \\| {\tt Tb.}     | \CS{tabnum}        \\\cr
Theorem       \\| {\tt Thm.}    | \CS{theoremnum}    \\
\endruledtable
\endtable

   One particularly useful way to use \CS{tag} and \CS{use} is to
refer to a topic which is discussed on some other page in the
document.
On the page you want to reference you could define the tag
``page.cool'' to be the page number by saying
\CS{tag}|{page.cool}{|\cs{folio}|}|.  
Then somewhere else in the document if you want to refer to the
information on that page you could do so with
\CS{use}|{page.cool}|, as in ``This difficulty is discussed in
more detail on page |\use{page.cool}|.''
Then even if the document is rearranged so that the page numbers
change, the page number you referred to will come out correct.

Here is another useful example.
Suppose you want to state the number of questions at the begining of
an examination (or similarly, the number of chapters in a book).
A count of the questions could be kept in |\Qcount|, but it won't be
set correctly until the end of the job.
Even so, when the count is known we can tag it with a name like ``NQ''
and use it in the text with |\use{NQ}|.
The first time this is encountered it will display as an undefined tag
and an error message will appear in the log.
But at the end of the document we say
\TeXexample
\tag{NQ}{\Qcount}
|endTeXexample to assign the final value of |\Qcount| to the
tag~``NQ''.
The next time the job is run saying |\use{NQ}| will be defined as the
value from the previous run.
Unless you've recently changed things (by adding or removing a
question) then this will be the correct count.


   Knowing about \CS{use} and the prefixes in \Tbl{labels} also lets you
change how the macros that refer to these objects work.  For example, to
refer to figure~\use{Fg.Penguin} in section~\use{sect.figs} you would
normally say \cs{Fig}|{Penguin}|.  This produces
``Fig.~\use{Fg.Penguin},'' but suppose you want it to say the full word
``figure'' instead of just ``Fig.''  You can make this change throughout
the document simply by changing the definition of \cs{Fig} to:
\TeXexample
\def\Fig#1{figure~\use{Fg.#1}}
|endTeXexample
\noindent
Then ``\cs{Fig}|{Penguin}|'' would produce ``figure~\use{Fg.Penguin}.''


\bigskip

      Whenever you create any of the objects listed in \Tbl{labels} a
label is automatically created.  However, chapters, sections, and
subsections are not automatically labeled because their values are not
ordinarily changed.  If you want to remember the number of a chapter or
section of your document to be able to refer to it somewhere else, put
\CS{label}\arg{label\/} in the text of the title of the chapter or
section. \CS{label}\arg{label\/} is the same as
\CS{tag}\arg{label\/}\arg{counter}, where \meta{counter} is the current 
section or chapter number, as appropriate.  For example you might have:
\TeXexample 
\section{Supersymmetry and Supergravity \label{sect.SUSY}}
|endTeXexample  
\noindent
To refer to that section later on you would say |\use{sect.SUSY}|.
Note that \CS{label} does not insert any prefix in front of the label,
so you must include it explicitly if you want one.
We suggest ``sect'' for sections, ``chapt'' for chapters, and so
forth, but you are free to use whatever you want.


%==================================================*
\pagecheck{0.33\vsize}

\subsection{Forward References}

If you label an equation or a figure or a section you can refer to
the number of that object later in the text, but what if you want to
refer to the thing before it has been tagged?  Then the label won't
exist yet.  This is called making a forward reference. To allow for
this \TeXsis\ also writes the definition of every label to an auxiliary
file, which has a name ending in |.aux|. The label will still be
undefined the first time you make the forward reference, but the next
time you run the document through \TeXsis\ it will automatically read in
the auxiliary file at the beginning of the job and define the label.
Thus on the second pass the label will already be defined when it is
called for.  Having to make a second pass may sound like extra work, 
but when you are editing a document and putting the finishing
touches on it you will find you end up making the extra pass without
thinking about it. Just don't delete the |.aux| file between runs.
\index{forward references}

        If you try to reference a label that does not exist you'll be
told so at the end of the run (when you say \cs{bye}) and another pass
will be suggested.  Undefined references are also noted in the log file
when they occur, and the label itself is inserted into the output text
in boldface to make it easier for you to track down the problem.  In
\cs{draft} mode the mark ``{\tt UNDEF}''  is also put in the right
margin to help you find the problem.

% Describe \twopass here, if we ever decide to publicize it



%==================================================*
\pagecheck{0.33\vsize}

\subsection{Hypertext \label{sect.hypertext}}

(Documentation for Hypertext linking will go here)







%>>> EOF TXStags.doc <<<