[m-rev.] for review: Improvements to reference manual

[Zoltan Somogyi]

On Sat, 4 Oct 2014 20:37:04 +1000, Mark Brown <mark at mercurylang.org> wrote:
> The sections in the reference manual on interfacing nondet code to the
> real world and committed choice are a bit out of date, and can also be
> clarified. For review by Zoltan.

Sorry for the late review, but my laptop was being repaired for the
last few days.

>  If you just want to see if a nondeterministic goal is satisfiable or not,
>  without needing to know what variable bindings it produces,
>  then there is no problem -
> -determinism analysis considers @code{nondet} and @code{multi} goals
> -with no non-local output variables to be
> +solutions to @code{nondet} and @code{multi} goals
> +with no non-local output variables
> +are declaratively equivalent,
> +so Mercury can safely prune away any potential duplicate solutions.
> +Determinism analysis thus considers these goals to be
>  @code{semidet} and @code{det} respectively.

can AND WILL prune away ...
 
> -is when you know that all the solutions returned will be equivalent.
> +you need to allow Mercury to prune the other solutions.

prune AWAY

> +If you know that there will only ever be at most one distinct
> +solution under the equality theory of the output variables,
> +then you can use a @samp{promise_equivalent_solutions} determinism cast,
> +which will do the pruning.

under YOUR equality theory

which will prune away all solutions after the first

> +More generally, Mercury prunes alternative solutions for
> +goals that are in a ``single-solution context'',
> +of which the above are two particular cases.
> +The full definition of single-solution context
> +is given in @ref{Committed choice nondeterminism}.

s/context/contexts/
Give brief sketches of those cases before the reference.

The diff is otherwise fine. It would be nice if most of this discussion
were accompanied by examples, but that would be a separate change.

Zoltan.