[latexrefman-commits] r481 - in /trunk: ChangeLog latex2e.texi

[jhefferon at domain.hid]

Author: jhefferon
Date: Sun Nov 29 17:58:52 2015
New Revision: 481

URL: http://svn.gna.org/viewcvs/latexrefman?rev=481&view=rev
Log:
Cross references

Modified:
    trunk/ChangeLog
    trunk/latex2e.texi

Modified: trunk/ChangeLog
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/ChangeLog?rev=481&r1=480&r2=481&view=diff
==============================================================================
--- trunk/ChangeLog	(original)
+++ trunk/ChangeLog	Sun Nov 29 17:58:52 2015
@@ -1,3 +1,8 @@
+2015-11-29  Jim Hefferon  <jhefferon at domain.hid>
+
+	* latex2e.texi (Cross references)  Add examples, and description of
+	forward references.
+
 2015-11-28  Jim Hefferon  <jhefferon at domain.hid>
 
 	* latex2e.texi (Counters)  Adjust wording and add examples

Modified: trunk/latex2e.texi
URL: http://svn.gna.org/viewcvs/latexrefman/trunk/latex2e.texi?rev=481&r1=480&r2=481&view=diff
==============================================================================
--- trunk/latex2e.texi	(original)
+++ trunk/latex2e.texi	Sun Nov 29 17:58:52 2015
@@ -1895,8 +1895,37 @@
 
 @cindex cross references
 
-One reason for numbering things like figures and equations is to refer
-the reader to them, as in ``See Figure 3 for more details.''
+One reason for numbering things such as figures and equations is to
+refer the reader to them, as in ``See Figure~3 for more details.''
+
+Including the figure number in the source is poor practice since if that
+number changes as the document evolves then you must remember to update
+this reference by hand. Instead, @LaTeX{} has you write something like
+ at code{\label at domain.hid@}} and refer to it with @code{See
+equation~\ref at domain.hid@}}.
+
+ at LaTeX{} writes the information from the labels to a file with the same
+name as the file containing the @code{\label@{...@}} but with an
+ at file{.aux} extension.  (The information has the format
+ at code{\newlabel at domain.hid}@}@}}
+where @var{currentlabel} is the current value of the macro
+ at code{\@@currentlabel} that is usually updated whenever you call
+ at code{\refstepcounter at domain.hid}@}}.)
+
+ at cindex forward reference
+ at cindex reference, forward
+The most common side effect of the prior paragraph happens when your
+document has a @dfn{forward reference}, a @code{\ref at domain.hid}@}} that
+appears earlier than the associated @code{\label at domain.hid}@}}; see the
+example in the @code{\pageref@{...@}} description.  @LaTeX{} gets the
+information for references from the @file{.aux} file.  If this is the
+first time you are running the document then you will get a message
+ at code{LaTeX Warning: Label(s) may have changed. Rerun to get
+cross-references right.} and in the output the reference will appear as
+two question marks at domain.hid{??}, in boldface.  Or, if you change some
+things so the references change then you get the same warning and the
+output contains the old reference information.  The solution in either
+case is just to compile the document a second time.
 
 @menu
 * \label::      Assign a symbolic name to a piece of text.
@@ -1916,37 +1945,22 @@
 \label at domain.hid}@}
 @end example
 
-A @code{\label} command appearing in ordinary text assigns to
- at domain.hid} the number of the current sectional unit; one appearing
-inside a numbered environment assigns that number to @var{key}.  The
-assigned number can be retrieved with the @code{\ref at domain.hid}@}}
-command (@pxref{\ref}).
-
-Thus, in the example below the key @code{sec:test} holds the number of
-the current section and the key @code{fig:test} that of the figure.
-(Incidentally, labels must appear after captions in figures and
-tables.)
-
- at domain.hid
-\section at domain.hid name@}
-\label at domain.hid@}
-This is Section~\ref at domain.hid@}.
-\begin at domain.hid@}
-  ...
-  \caption at domain.hid text@}
-  \label at domain.hid@}
-\end at domain.hid@}
-See Figure~\ref at domain.hid@}.
- at domain.hid example
+Assign a number to @var{key}.  In ordinary text
+ at code{\label at domain.hid}@}} assigns to @var{key} the number of the
+current sectional unit. Inside an environment with numbering, such as a
+ at code{table} or @code{theorem} environment, @code{\label at domain.hid}@}}
+assigns to @var{key} the number of that environment.  Retrieve the
+assigned number with the @code{\ref at domain.hid}@}} command
+(@pxref{\ref}).
 
 A key name can consist of any sequence of letters, digits, or common
 punctuation characters.  Upper and lowercase letters are
 distinguished, as usual.
 
-Although the name can be more or less anything, a common convention is
-to use labels consisting of a prefix and a suffix separated by a colon
-or period.  This helps to avoid accidentally creating two labels with
-the same name.  Some commonly-used prefixes:
+A common convention is to use labels consisting of a prefix and a suffix
+separated by a colon or period.  This helps to avoid accidentally
+creating two labels with the same name, and makes your source more
+readable.  Some commonly-used prefixes:
 
 @table @code
 @item ch
@@ -1961,8 +1975,25 @@
 for equations
 @end table
 
-Thus, a label for a figure would look like @code{fig:test} or
- at domain.hid}.
+Thus, @code{\label at domain.hid@}} is a label for a figure with a portrait
+of the great man.
+
+In this example below the key @code{sec:test} will get the number of the
+current section and the key @code{fig:test} will get the number of the
+figure.  (Incidentally, put labels after captions in figures and
+tables.)
+
+ at example
+\section at domain.hid name@}
+\label at domain.hid@}
+This is Section~\ref at domain.hid@}.
+\begin at domain.hid@}
+  ...
+  \caption at domain.hid text@}
+  \label at domain.hid@}
+\end at domain.hid@}
+See Figure~\ref at domain.hid@}.
+ at end example
 
 
 @node \pageref
@@ -1978,9 +2009,21 @@
 \pageref at domain.hid}@}
 @end example
 
-The @code{\pageref}@{@var{key}@} command produces the page number of
-the place in the text where the corresponding
+Produce the page number of the place in the text where the corresponding
 @code{\label}@{@var{key}@} command appears.
+
+In this example the @code{\label at domain.hid@}} is used both for the
+formula number and for the page number.  (Note that the two references
+are forward references, so this document would need to be compiled twice
+to resolve those.)
+
+ at example
+The main result is formula~\ref at domain.hid@} on page~\pageref at domain.hid@}.
+  ...
+\begin at domain.hid@} \label at domain.hid@}
+   \mathbf at domain.hid@}
+\end at domain.hid@}
+ at end example
 
 
 @node \ref
@@ -1999,10 +2042,23 @@
 \ref at domain.hid}@}
 @end example
 
-The @code{\ref} command produces the number of the sectional unit,
+Produces the number of the sectional unit,
 equation, footnote, figure, @dots{}, of the corresponding
 @code{\label} command (@pxref{\label}).  It does not produce any text,
 such as the word `Section' or `Figure', just the bare number itself.
+
+In this example, the @code{\ref at domain.hid@}} produces @samp{2}.  Note
+that it is a forward reference since it comes before
+ at code{\label at domain.hid@}}.
+
+ at example
+The most widely-used format is item number~\ref at domain.hid@}.
+\begin at domain.hid@}
+\item Plain \TeX
+\item \label at domain.hid@} \LaTeX
+\item Con\TeX t
+\end at domain.hid@}
+ at end example
 
 
 @node Environments
@@ -5507,7 +5563,7 @@
 
 @example
 \newfont at domain.hid at 11pt@}
-\newfont at domain.hid scaled 11pt@}
+\newfont at domain.hid scaled 1100@}
 \testfontat abc
 \testfontscaled abc
 @end example