diff: improvements to documentation of C interface

[Fergus Henderson]

This change is in response to a suggestion by Peter Schachte.

doc/reference_manual.texi:
	Improve the documentation of the C interface:
	show how to use `pragma c_code' to define functions,
	and also make a few other minor improvements.

Here's the diff to the generated plain-text.

--- reference_manual.text.old	Fri Sep 19 10:45:51 1997
+++ reference_manual.text	Fri Sep 19 10:56:17 1997
@@ -2128,13 +2128,20 @@
      :- pragma c_code(PRED(VAR1::MODE1, VAR2::MODE2, ...),
              may_call_mercury, C_CODE).
 
-results in any calls to PRED with variables in modes (MODE1, MODE2,
-...) being replaced by the C code given in C_CODE.
+or
+
+     :- pragma c_code(FUNC(VAR1::MODE1, VAR2::MODE2, ...) = (VAR::MODE),
+             may_call_mercury, C_CODE).
 
-   If there is a `pragma c_code' declaration for a mode of a predicate,
-then that mode of the predicate may not be `multi' or `nondet', there
-must not be any clauses for that predicate, and there must be a `pragma
-c_code' goal for every mode of the predicate.
+means that any calls to the specified mode of PRED or FUNC will be
+replaced by the C code given in C_CODE.  The C code fragment may refer
+to the specified variables (VAR1, VAR2, ..., and VAR) directly by name.
+
+   If there is a `pragma c_code' declaration for a mode of a predicate
+or function, then that mode of the predicate may not have determinism
+`multi' or `nondet', there must not be any clauses for that predicate
+or function, and there must be a `pragma c_code' goal for every mode of
+the predicate or function.
 
    For example, the following piece of code gives a predicate,
 `c_write_string/3', which has a similar effect to the Mercury library
@@ -2148,18 +2155,15 @@
              "puts(S); IO = IO0;").
 
    If the C code does not recursively invoke Mercury code, as in the
-above example, then you can use a declaration of the form
-
-     :- pragma c_code(PRED(VAR1::MODE1, VAR2::MODE2, ...),
-             will_not_call_mercury, C_CODE).
-
-   This allows the compiler to use a more efficient calling convention.
-(If you use this form, and the C code *does* invoke Mercury code, then
-the behaviour is undefined -- your program may misbehave or crash.)
+above example, then you can use `will_not_call_mercury' in place of
+`may_call_mercury' in the declarations above.  This allows the compiler
+to use a slightly more efficient calling convention.  (If you use this
+form, and the C code *does* invoke Mercury code, then the behaviour is
+undefined -- your program may misbehave or crash.)
 
    The C code in a `pragma c_code' declaration for any procedure whose
 determinism indicates that it could fail must assign a truth value to
-the macro SUCCESS_INDICATOR.  For example:
+the macro `SUCCESS_INDICATOR'.  For example:
 
      :- pred string__contains_char(string, character).
      :- mode string__contains_char(in, in) is semidet.
@@ -2168,17 +2172,17 @@
              will_not_call_mercury,
              "SUCCESS_INDICATOR = (strchr(Str, Ch) != NULL);").
 
-   SUCCESS_INDICATOR should not be used other than as the target of an
-assignment.  (For example, it may be `#define'd to a register, so you
-should not try to take its address.) Procedures whose determinism
+   `SUCCESS_INDICATOR' should not be used other than as the target of
+an assignment.  (For example, it may be `#define'd to a register, so
+you should not try to take its address.) Procedures whose determinism
 indicates that that they cannot fail should not access
-SUCCESS_INDICATOR.
+`SUCCESS_INDICATOR'.
 
    Arguments whose mode is input will have their values set by the
 Mercury implementation on entry to the C code.  If the procedure
 succeeds, the C code must set the values of all output arguments before
 returning.  If the procedure fails, the C code need only set
-SUCCESS_INDICATOR to false (zero).
+`SUCCESS_INDICATOR' to false (zero).
 
 Including C headers
 -------------------
@@ -2209,7 +2213,7 @@
              extern void foo(void);
      ").
 
-   Mercury automatically includes certain headers such as `<stdio.h>',
+   Mercury automatically includes certain headers such as `<stdlib.h>',
 but you should not rely on this, as the set of headers which Mercury
 automatically includes is subject to change.
 

Here's the diff to the source code.

cvs diff: Diffing .
Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.67
diff -u -u -r1.67 reference_manual.texi
--- reference_manual.texi	1997/08/27 02:07:06	1.67
+++ reference_manual.texi	1997/09/19 00:55:07
@@ -2699,13 +2699,25 @@
 @end example
 
 @noindent
-results in any calls to @var{Pred} with variables in modes (@var{Mode1}, 
- at var{Mode2}, ...) being replaced by the C code given in @var{C_Code}.
+or
 
-If there is a @code{pragma c_code} declaration for a mode of a predicate,
-then that mode of the predicate may not be @samp{multi} or @samp{nondet},
-there must not be any clauses for that predicate,
-and there must be a @code{pragma c_code} goal for every mode of the predicate.
+ at example
+:- pragma c_code(@var{Func}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, ...) = (@var{Var}::@var{Mode}),
+        may_call_mercury, @var{C_Code}).
+ at end example
+
+ at noindent
+means that any calls to the specified mode of @var{Pred} or @var{Func}
+will be replaced by the C code given in @var{C_Code}.
+The C code fragment may refer to the specified variables
+(@var{Var1}, @var{Var2}, @dots{}, and @var{Var})
+directly by name.
+
+If there is a @code{pragma c_code} declaration for a mode of a predicate
+or function, then that mode of the predicate may not have determinism
+ at samp{multi} or @samp{nondet}, there must not be any clauses for that
+predicate or function, and there must be a @code{pragma c_code} goal
+for every mode of the predicate or function.
 
 For example, the following piece of code gives a predicate, 
 @samp{c_write_string/3}, which has a similar effect to the Mercury library 
@@ -2721,20 +2733,15 @@
 @end example
 
 If the C code does not recursively invoke Mercury code,
-as in the above example, then you can use a declaration of the form
-
- at example
-:- pragma c_code(@var{Pred}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, ...),
-        will_not_call_mercury, @var{C_Code}).
- at end example
-
-This allows the compiler to use a more efficient calling convention.
+as in the above example, then you can use @samp{will_not_call_mercury}
+in place of @samp{may_call_mercury} in the declarations above.
+This allows the compiler to use a slightly more efficient calling convention.
 (If you use this form, and the C code @emph{does} invoke Mercury code,
 then the behaviour is undefined --- your program may misbehave or crash.)
 
 The C code in a @code{pragma c_code} declaration
 for any procedure whose determinism indicates that it could fail
-must assign a truth value to the macro @var{SUCCESS_INDICATOR}.
+must assign a truth value to the macro @samp{SUCCESS_INDICATOR}.
 For example:
 
 @example
@@ -2746,17 +2753,18 @@
         "SUCCESS_INDICATOR = (strchr(Str, Ch) != NULL);").
 @end example
 
-SUCCESS_INDICATOR should not be used other than as the target of an assignment.
+ at code{SUCCESS_INDICATOR} should not be used other than as the target of
+an assignment.
 (For example, it may be @code{#define}d to a register, so you should not
 try to take its address.) 
 Procedures whose determinism indicates that that they cannot fail
-should not access SUCCESS_INDICATOR.
+should not access @code{SUCCESS_INDICATOR}.
 
 Arguments whose mode is input will have their values set by the
 Mercury implementation on entry to the C code.  If the procedure
 succeeds, the C code must set the values of all output arguments
 before returning.  If the procedure fails, the C code need only
-set SUCCESS_INDICATOR to false (zero).
+set @code{SUCCESS_INDICATOR} to false (zero).
 
 @node Including C headers
 @subsection Including C headers
@@ -2798,7 +2806,7 @@
 ").
 @end example
 
-Mercury automatically includes certain headers such as @code{<stdio.h>},
+Mercury automatically includes certain headers such as @code{<stdlib.h>},
 but you should not rely on this, as the set of headers which Mercury
 automatically includes is subject to change.
 
-- 
Fergus Henderson <fjh at cs.mu.oz.au>   |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>   |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3         |     -- the last words of T. S. Garp.