[m-rev.] for review: Correct status of partial instantiation support

[Julien Fischer]

On Wed, 12 Mar 2014, Paul Bone wrote:

> For review, does anyone know if there are more places throughout the
> documentation that need correcting?  Thanks.
>
> Branches: master, version-14.01-branch
>
> ---
>
> Correct status of partial instantiation support
>
> In (at least) two places we say that partial instantiation doesn't work or
> isn't supported.  To be more correct it works to some extent but is
> 'experimental'.

Experimental is a bit ambiguous, does it mean that: (1) it doesn't work,
(2) it partially works, (3) it works but hasn't been extensively tested?
I would prefer to say that support for partial instantiation is
incomplete in the current implementation.

>  Correcting this statement will confuse users of Mercury
> less.  (It was pointed out to me by 1-2 people that this had confused them.)

What exactly confused them?  That the compiler appeared to accept some
programs containing partially instantiated terms without complaining
even though the reference manual suggests otherwise?

> doc/reference_manual.texi:
> library/list.m:
>    As above.
> ---
> doc/reference_manual.texi | 4 ++--
> library/list.m            | 6 +++++-
> 2 files changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/doc/reference_manual.texi b/doc/reference_manual.texi
> index a7a34b2..d63f336 100644
> --- a/doc/reference_manual.texi
> +++ b/doc/reference_manual.texi
> @@ -2541,8 +2541,8 @@ These two modes are enough for most functions and predicates.
> Nevertheless, Mercury's mode system is sufficiently
> expressive to handle more complex data-flow patterns,
> including those involving partially instantiated data structures.
> -(The current implementation does not handle
> -partially instantiated data structures yet.)
> +(Partially instantiated data structures are experimental in the current
> +implementation.)
>
> For example, consider an
> interface to a database that associates data with keys, and provides
> diff --git a/library/list.m b/library/list.m
> index 102edb6..ce8c16d 100644
> --- a/library/list.m
> +++ b/library/list.m
> @@ -35,7 +35,11 @@
> %-----------------------------------------------------------------------------%
>
>     % Some declarations for complicated modes using lists.
> -    % (Note that partial instantiation is not currently supported.)
> +    %
> +    % Note that partial instantiation is experimental.  In particular it
> +    % does not work on the Erlang backend and that most existing code is

I think most of that is just clutter: the limitations of the Erlang
backend with partial instantiation are already covered in the
documentation for the Erlang backend.

> +    % not instantiation state polymorphic (such as the standard library
> +    % itself).

I would delete that last bit: the lack of mode polymorphism in the
standard library has little to do with the lack of support for partial
instantiation.

Maybe we should just remove insts like list_skel/0 (and the accompanying
comment) if their presence is causing confusion?

Cheers,
Julien.