summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/texsis/base/TXStags.doc
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/texsis/base/TXStags.doc')
-rw-r--r--Master/texmf-dist/doc/texsis/base/TXStags.doc212
1 files changed, 212 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/texsis/base/TXStags.doc b/Master/texmf-dist/doc/texsis/base/TXStags.doc
new file mode 100644
index 00000000000..768e4f1692f
--- /dev/null
+++ b/Master/texmf-dist/doc/texsis/base/TXStags.doc
@@ -0,0 +1,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 <<<