[m-rev.] for review: document event goals and tabling of foreign types in ref man

[Julien Fischer]

For review by anyone.

Branches: main, 11.01

Fix a number of documentation issues.

doc/reference_manual.texi:
 	Briefly describe event goals and point the user towards the User's
 	Guide for the actual documentation of that feature.
 	This addresses bug #198.

 	Extend the ``Tabled evaluation'' section to describe tabling
 	of foreign types.

 	Add a pointer from the ``Using foreign types from Mercury'' section
 	to the ``Tabled evaluation'' section.  The former describes the
 	foreign type assertions that make tabling of foreign types possible.

 	Fix an inconsistency:  it should be (and usually is) "I/O" rather than "IO"
 	in all but code examples.

 	Fix some texinfo style issues.

doc/transition_guide.texi:
 	s/IO/I\/O/ as above.

Julien.

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.461
diff -u -r1.461 reference_manual.texi
--- doc/reference_manual.texi	8 Apr 2011 07:25:51 -0000	1.461
+++ doc/reference_manual.texi	17 May 2011 15:35:04 -0000
@@ -950,6 +950,12 @@

  See @ref{Exception handling} for the full details.

+ at item @code{event @var{Goal}}
+An event goal.  @var{Goal} must be a predicate call.
+Event goals are an extension used by the Melbourne Mercury implementation
+to support user defined events in the Mercury debugger, @samp{mdb}.
+See the ``Debugging'' chapter of the Mercury User's Guide for further details.
+
  @item @code{@var{Call}}
  Any goal which does not match any of the above forms
  must be a predicate call.
@@ -1159,7 +1165,7 @@

  @table @b

- at item Threading the IO state
+ at item Threading the I/O state
  @example
  main(!IO) :-
  	io.write_string("The 100th prime is ", !IO),
@@ -1194,7 +1200,7 @@

  (DCG notation is intended for writing parsers and sequence generators
  in a particular style; in the past it has also been used to thread an
-implicit state variable, typically the IO state, through code.  As a
+implicit state variable, typically the I/O state, through code.  As a
  matter of style, we recommend that in future DCG notation be reserved
  for writing parsers and sequence generators and that state variable
  syntax be used for passing state threads.)
@@ -6515,8 +6521,8 @@

  @item @samp{will_not_call_mm_tabled/may_call_mm_tabled}
  This attribute declares whether or not a foreign procedure makes calls back to
-Mercury procedures that are evaluated using minimal model tabling (see
- at ref{Tabled evaluation}).  Specifying that a foreign procedure will not call
+Mercury procedures that are evaluated using minimal model tabling
+(@pxref{Tabled evaluation}).  Specifying that a foreign procedure will not call
  procedures evaluated using minimal model tabling may allow the compiler to
  generate more efficient code.  In compilation grades that do not support
  minimal model tabling this attribute is ignored.  These attributes may not be
@@ -7118,9 +7124,9 @@
  only in the presence of the @samp{can_pass_as_mercury_type} assertion.
  It states that either the C type is an integer type,
  or it is a pointer type pointing to memory that will never change.
-Together, these assertions are sufficient to allow
-tabling and the @samp{compare_representation} primitive
-to work on values of such types.
+Together, these assertions are sufficient to allow tabling
+(@pxref{Tabled evaluation}) and the @samp{compare_representation}
+primitive to work on values of such types.

  As with discriminated union types, programmers can specify the unification
  @w{and/or} comparison predicates to use for values of the type using the
@@ -9744,6 +9750,11 @@
  you cannot apply any of these pragmas to procedures
  whose arguments' modes include any unique component.

+Tabled evaluation of a predicate or function that has an argument whose type
+is a foreign type will result in a run-time error unless the foreign type
+is one for which the @samp{can_pass_as_mercury_type} and @samp{stable}
+assertions have been made (@pxref{Using foreign types from Mercury}).
+
  The optional list of attributes allows programmers
  to control some aspects of the management of the memo table(s)
  of the procedure(s) affected by the pragma.
Index: doc/transition_guide.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/transition_guide.texi,v
retrieving revision 1.53
diff -u -r1.53 transition_guide.texi
--- doc/transition_guide.texi	3 Jan 2011 14:45:35 -0000	1.53
+++ doc/transition_guide.texi	17 May 2011 15:32:54 -0000
@@ -203,16 +203,16 @@
  One of the important consequences of our model for input and output
  is that predicates that can fail may not do input or output.
  This is because the state of the world must be a unique object,
-and each IO operation destructively replaces it with a new state.
-Since each IO operation destroys the current state object
+and each I/O operation destructively replaces it with a new state.
+Since each I/O operation destroys the current state object
  and produces a new one,
-it is not possible for IO to be performed in a context that may fail,
+it is not possible for I/O to be performed in a context that may fail,
  since when failure occurs the old state of the world will have been destroyed,
  and since bindings cannot be exported from a failing computation,
  the new state of the world is not accessible.

  In some circumstances, Prolog programs that suffer from this problem
-can be fixed by moving the IO out of the failing context.
+can be fixed by moving the I/O out of the failing context.
  For example

  @example
@@ -226,7 +226,7 @@
  @end example

  @noindent
-where @samp{solve(Goal)} does some IO can be transformed into
+where @samp{solve(Goal)} does some I/O can be transformed into
  valid Mercury in at least two ways. The first is to make
  @samp{solve} deterministic and return a status:

--------------------------------------------------------------------------
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
--------------------------------------------------------------------------