for review: document meaning of "can fail"

[Fergus Henderson]

On 18-Sep-1998, Tyson Dowd <trd at cs.mu.OZ.AU> wrote:
> On 18-Sep-1998, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> > [someone wrote:]
> > > This rather strange to see a multi proc failing since it is supposed not
> > > to fail. Isn't that a bug in the tracer ?
> > 
> > No, this is not a bug in the tracer, or in the code generator.
> > 
> > "This rather strange to see a multi proc failing since it is supposed not
> > to fail" indicates a misconception. A multi proc is not supposed to fail
> > *without first producing a solution*. Once it has produced that solution,
> > and possibly other solutions, the multi proc is allowed to fail, and
> > must fail if it has no more solutions. The only difference between nondet
> > and multi is that multi promises at least one solution before failure.
> 
> I think the problem is that our "quick summary" table in the language
> reference manual says "can fail?  no" for multi, and if you learn
> that table, you might answer the question "can multi ever fail?" with
> "no".
> 
> Perhaps what it should say is "can fail with no solutions?".

I think "can fail with no solutions" is itself a bit unclear.
Instead, I've added a brief note under the table which
should hopefully clarify things.

Does this look OK?

--------------------

Estimated hours taken: 0.5

doc/reference_manual.texi:
	Document the meaning of the "Can fail?" column in the
	determinism table more clearly.

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.106
diff -u -u -6 -r1.106 reference_manual.texi
--- reference_manual.texi	1998/10/20 15:06:57	1.106
+++ reference_manual.texi	1998/10/27 18:15:59
@@ -1529,12 +1529,17 @@
                 Maximum number of solutions
 Can fail?       0               1               > 1
 no              erroneous       det             multi
 yes             failure         semidet         nondet
 @end example
 
+(Note: the "Can fail?" column here indicates only whether the procedure
+can fail before producing at least one solution; attempts to find a
+ at emph{second} solution to a particular call, e.g. for a procedure
+with determinism @samp{multi}, are always allowed to fail.)
+
 The determinism of each mode of a predicate or function
 is indicated by an annotation on the mode declaration.
 For example:
 
 @example
 :- pred append(list(T), list(T), list(T)).

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