[m-rev.] diff: fix a documentation bug

[Julien Fischer]

Estimated hours taken: 0.2
Branches: main

Fix a documentation bug.  The C data passing conventions section in the
reference manual included some paragraphs related to the old `pragma export'
declaration that should have been deleted when the data passing conventions
section for the old and new interfaces were merged.

doc/reference_manual.texi:
 	Delete the above paragraph - it's content is covered in the documentation
 	for `pragma foreign_export'.

 	Mention that MR_Integer is the same size as a pointer of type `void *'.

 	Mention that the behaviour of a C foreign_proc that contains a return
 	statement is undefined.

 	Fix some spelling errors.

 	Reformat some paragraphs to make modification easier.

Julien.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.426
diff -u -r1.426 reference_manual.texi
--- reference_manual.texi	28 Apr 2008 00:50:55 -0000	1.426
+++ reference_manual.texi	26 May 2008 08:53:22 -0000
@@ -6693,11 +6693,11 @@
  @code{MR_Integer}, @code{MR_Float}, @code{MR_Char},
  and @code{MR_String} respectively.

-In the current implementation, @samp{MR_Integer} is a typedef for an
-integral type whose size is the same size as a pointer; @samp{MR_Float} is
-a typedef for @samp{double} (unless the program and the Mercury library
-was compiled with @samp{--single-prec-float}, in which case it is
-a typedef for @samp{float}); @samp{MR_Char} is a typedef for @samp{char};
+In the current implementation, @samp{MR_Integer} is a typedef for an integral
+type whose size is the same size as a pointer of type @samp{void *};
+ at samp{MR_Float} is a typedef for @samp{double} (unless the program and the
+Mercury library was compiled with @samp{--single-prec-float}, in which case it
+is a typedef for @samp{float}); @samp{MR_Char} is a typedef for @samp{char};
  and @samp{MR_String} is a typedef for @samp{MR_Char *}.

  Mercury variables of type @code{int}, @code{float}, @code{char}, or
@@ -6735,25 +6735,6 @@
  and it will also minimize any compatibility problems if and when we do change
  this.)

-Mercury arguments declared with input modes are passed by value to the
-C function.
-For output arguments,
-the Mercury implementation will pass to the C function an address in
-which to store the result. 
-If the Mercury procedure can fail,
-then its C function should return a truth value of type
- at samp{MR_Integer} indicating success or failure:
-non-zero indicates success, and zero indicates failure.
-If the Mercury procedure is a Mercury function that cannot fail,
-and the function result has an output mode,
-then the C function should return the Mercury function result value.
-Otherwise the function result is appended as an extra argument.
-Arguments of type @samp{io.state} or @samp{store.store(_)} are not
-passed at all.
-(The reason for this is that these types represent mutable state,
-and in C modifications to mutable state are done via side effects,
-rather than argument passing.)
-
  Mercury lists can be manipulated by C code using the following macros,
  which are defined by the Mercury implementation.

@@ -7430,20 +7411,21 @@
  the code can be moved into a separate function
  (defined in a @samp{pragma foreign_code} declaration, for example).

-The C code fragment should not declare any labels or static variables
-unless there is also a @samp{pragma no_inline} declaration
-or a @samp{may_not_duplicate} foreign code attribute for the procedure.
-The reason for this is that otherwise the Mercury implementation may
-inline the procedure by duplicating the C code fragment for each call.
-If the C code fragment declared a static variable, inlining it in this
-way could result in the program having multiple instances of the static
-variable, rather than a single shared instance.  If the C code fragment
-declared a label, inlining it in this way could result in an error due
-to the same label being defined twice inside a single C function.
-
-C code in a @code{pragma foreign_proc} declaration
-for any procedure whose determinism indicates that it can fail
-must assign a truth value to the macro @samp{SUCCESS_INDICATOR}.
+The C code fragment should not declare any labels or static variables unless
+there is also a @samp{pragma no_inline} declaration or a
+ at samp{may_not_duplicate} foreign code attribute for the procedure.
+The reason for this is that otherwise the Mercury implementation may inline
+the procedure by duplicating the C code fragment for each call.
+If the C code fragment declared a static variable, inlining it in this way
+could result in the program having multiple instances of the static variable,
+rather than a single shared instance.
+If the C code fragment declared a label, inlining it in this way could result
+in an error due to the same label being defined twice inside a single C
+function.
+
+C code in a @code{pragma foreign_proc} declaration for any procedure whose
+determinism indicates that it can fail must assign a truth value to the macro
+ at samp{SUCCESS_INDICATOR}.
  For example:

  @example
@@ -7463,11 +7445,15 @@
  Procedures whose determinism indicates that they cannot fail
  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.
-If the procedure fails, the C code need only
-set @code{SUCCESS_INDICATOR} to false (zero).
+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.
+If the procedure fails, the C code need only set @code{SUCCESS_INDICATOR} to
+false (zero).
+
+The behaviour of a procedure defined using a @samp{pragma foreign_proc}
+declaration whose body contains a @samp{return} statement is undefined.

  @node Using pragma foreign_export for C
  @subsubsection Using pragma foreign_export for C

--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------