[m-rev.] trivial diff: fix @xref/@pxref/@ref

[Fergus Henderson]

I noticed some formatting bugs with the use of @xref, @pxref, and @ref
in our TexInfo documentation.  The rule about when to use what is as follows:

	1. Use @xref at the start of a sentence.  Do *not* precede it with "See".

	2. Use @pxref in parentheses.  Do *not* precede it with "see".

	3. Use @ref in the middle or at the end of a sentence.  For @ref only,
	   *do* precede it with "see" or "in" or something similar.

----------

Estimated hours taken: 0.75
Branches: main, release

doc/reference_manual.texi:
doc/user_guide.texi:
	Fix some formatting errors in the use of @xref, @pxref, and @ref,
	to avoid problems such as occurrences of "see see section <whatever>"
	in the HTML and DVI output.

Workspace: /home/ceres/fjh/mercury
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.271
diff -u -d -r1.271 reference_manual.texi
--- doc/reference_manual.texi	12 Feb 2003 22:58:15 -0000	1.271
+++ doc/reference_manual.texi	20 Feb 2003 14:56:03 -0000
@@ -319,7 +319,7 @@
 except that as extensions we permit higher-order terms and the
 introduction of infix operators by the use of grave accents (backquotes),
 as described below,
-and we support an extended set of builtin operators. @xref{Builtin Operators}.
+and we support an extended set of builtin operators.  @xref{Builtin Operators}.
 Also, the constructor for list terms in Mercury is @code{[|]/2}, not
 @code{./2} as in Prolog.
 
@@ -574,7 +574,7 @@
 in a preceding @samp{pred} or @samp{func} declaration in this module.
 The @var{Result} (if any) and the arguments of the @var{Head} must
 be valid data-terms (optionally annotated with a mode qualifier;
-see @pxref{Different clauses for different modes}).
+see @ref{Different clauses for different modes}).
 
 A fact is equivalent to a rule whose body is @samp{true}.
 
@@ -593,7 +593,7 @@
 this module.
 The @var{Result} and the arguments of the @var{Head} must be
 valid data-terms (optionally annotated with a mode qualifier;
-see @pxref{Different clauses for different modes}).
+see @ref{Different clauses for different modes}).
 The @var{Body} must be a valid goal.
 
 @node Goals
@@ -4853,7 +4853,7 @@
 different types for its existentially typed arguments in different clauses
 (even mode-specific clauses) or in different subgoals of a single clause;
 however, the same effect can be achieved in other ways
-(see @pxref{Some idioms using existentially quantified types}).
+(@pxref{Some idioms using existentially quantified types}).
 
 For procedures involving calls to existentially-typed predicates or functions,
 the compiler's mode analysis must take account of the modes for type
@@ -5162,7 +5162,7 @@
 @end example
 
 The issue can also arise for mode-specific clauses
-(see @pxref{Different clauses for different modes}).
+(@pxref{Different clauses for different modes}).
 For instance, the following example is illegal:
 
 @example
@@ -5346,7 +5346,7 @@
 
 This chapter documents the new foreign language interface.
 This is intended as a successor to the existing C interface for Mercury,
-which is documented in @xref{C interface}.
+which is documented in @ref{C interface}.
 However, the new foreign language interface is not yet complete
 (it does not yet include equivalents to
 @samp{pragma import} and @samp{pragma export} in the C interface)
@@ -5543,7 +5543,7 @@
 @node C data passing conventions
 @subsection C data passing conventions
 
-This section is currently documented in @pxref{Passing data to and from C}.
+This section is currently documented in @ref{Passing data to and from C}.
 
 @node IL and C# data passing conventions
 @subsection IL and C# data passing conventions
@@ -5984,7 +5984,7 @@
 The input and output variables for a C# @samp{pragma foreign_proc} will
 have C# types corresponding to their Mercury types.  The exact rules
 for mapping Mercury types to C# types are described in
- at xref{IL and C# data passing conventions}.
+ at ref{IL and C# data passing conventions}.
 
 C# code in a @code{pragma foreign_proc} declaration
 for any procedure whose determinism indicates that it could fail
@@ -6185,7 +6185,7 @@
 @c set @code{success} to false (zero).
 
 Each of the head variables will be represented by the Common Language
-Runtime types as specified in @pxref{IL and C# data passing conventions}.
+Runtime types as specified in @ref{IL and C# data passing conventions}.
 
 @node Using pragma foreign_decl for IL
 @subsubsection Using pragma foreign_decl for IL
@@ -6333,7 +6333,7 @@
 This chapter documents the original C interface.
 In the long term we are planning to phase out support for this interface
 in favour of the new foreign language interface documented in
- at xref{Foreign language interface}.
+ at ref{Foreign language interface}.
 
 The Mercury distribution includes a number of examples of the
 use of the C interface that show how to interface C++ with Mercury
@@ -8474,7 +8474,7 @@
 @samp{supp_magic} is the default.
 There are restrictions on predicates to which the context transformation
 can be applied; these are described in @cite{Right-, left-, and multi-linear
-rule transformations that maintain context information.} @ref{[6]}.
+rule transformations that maintain context information.} @xref{[6]}.
 
 @example
 :- pragma naive(@var{Name}/@var{Arity}).
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.353
diff -u -d -r1.353 user_guide.texi
--- doc/user_guide.texi	5 Feb 2003 14:41:16 -0000	1.353
+++ doc/user_guide.texi	20 Feb 2003 14:47:36 -0000
@@ -3441,7 +3441,7 @@
 @end table
 
 It is also legal to press return without specifying a command.
-If there is a default answer (see @ref{Oracle questions}),
+If there is a default answer (@pxref{Oracle questions}),
 pressing return is equivalent to giving that answer.
 If there is no default answer,
 pressing return is equivalent to the skip command.
@@ -4544,7 +4544,7 @@
 Generate code that includes the specified level of execution tracing.
 The @var{level} should be one of
 @samp{none}, @samp{shallow}, @samp{deep}, @samp{rep} and @samp{default}.
-See @ref{Debugging}.
+ at xref{Debugging}.
 
 @item --trace-optimized
 @findex --trace-optimized
@@ -5208,7 +5208,7 @@
 @findex --debug
 @cindex Debugging
 Enables the inclusion in the executable of code and data structures
-that allow the program to be debugged with @samp{mdb} (see @ref{Debugging}).
+that allow the program to be debugged with @samp{mdb} (@pxref{Debugging}).
 This option is not yet supported for the @samp{--high-level-code} back-ends.
 
 @c XXX .decldebug isn't usefully different from .debug
@@ -5219,7 +5219,7 @@
 @c Enables the inclusion in the executable of code and data structures
 @c that allow the program to be debugged
 @c with the declarative debugging facilities of @samp{mdb}
- at c (see @ref{Debugging}).
+ at c (@pxref{Debugging}).
 @c This option is not yet supported for the @samp{--high-level-code} back-ends.
 
 @sp 1

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------