[m-rev.] for post-commit review: fix io section of transition guide

[Julien Fischer]

Hi Zoltan,

On Wed, 11 Feb 2015, Zoltan Somogyi wrote:

> For post-commit review by anyone.
>
> I will look at the other sections later.
>
> Zoltan.


> diff --git a/doc/transition_guide.texi b/doc/transition_guide.texi
> index fa8ebbe..293f6a5 100644
> --- a/doc/transition_guide.texi
> +++ b/doc/transition_guide.texi
> @@ -142,16 +142,19 @@ Therefore it cannot use Prolog's mechanism for doing
>  input and output with side-effects.
>  The mechanism that Mercury uses is the threading of an object
>  that represents the state of the world through the computation.
> -The type of this structure is @samp{io.state}.
> +The type of this structure is @code{io.state}, or just @code{io} for short.

s/structure/object/ for consistency with the previous sentence.

> +Each operation that affects the state of the world
> +has added to it two arguments of this type,

s/added to it/requires/

> +representing respectively the state of the world before the operation,
> +and the state of the world after the operation.
>  The modes of the two arguments that are added to calls are
> - at samp{di} for ``destructive input'' and @samp{uo} for ``unique output''.
> + at code{di} for ``destructive input'' and @code{uo} for ``unique output''.
>  The first means that the input variable
>  must be the last reference to the original state of the world,
> -and that the output variable will be the only reference
> -to the state of the world produced by this predicate.
> +and that the output variable is then guaranteed to be the
> +only reference to the state of the world produced by this predicate.
> 
> -Predicates that do input or output must have these arguments added.
> -For example the Prolog predicate:
> +For example, the direct translation of the Prolog predicate
>
>  @example
>  write_total(Total) :-
> @@ -162,11 +165,10 @@ write_total(Total) :-
>  @end example
>
>  @noindent
> -in Mercury becomes
> +into Mercury yields this Mercury predicate:
>
>  @example
> -:- pred write_total(int, io.state, io.state).
> -:- mode write_total(in, di, uo) is det.
> +:- pred write_total(int::in, io::di, io::uo) is det.
>
>  write_total(Total, IO0, IO) :-
>      print("The total is ", IO0, IO1),
> @@ -175,32 +177,97 @@ write_total(Total, IO0, IO) :-
>      nl(IO3, IO).
>  @end example
> 
> -Definite Clause Grammars (DCGs) are convenient syntactic sugar
> -to use in such situations.
> -The above clause can also be written
> +The variables @code{IO0}, @code{IO1} etc each represent
> +one version of the state of the world.
> + at code{IO0} represents the state before the total is printed,
> + at code{IO1} represents the state after just @samp{"The total is"} is printed,

Use @code around the string literal rather than @samp.  I don't think it
requires an extra level of quoting, the change in typeface ought to be
sufficient.

> +and so on.
> +However, programmers usually don't want to give specific names
> +to all these different versions;
> +they want to name only the entities
> +that all these variables represent different versions of.
> +That is why Mercury supports state variable notation.
> +This is syntactic sugar
> +designed to make it easier to thread a sequence of variables
> +holding successive states of an entity through a clause.

    ... holding the successive states ...

I think it would also be worth explicitly mentioning that the usual convention
in Mercury programs is to name the I/O state variable 'IO'.

Cheers,
Julien.