[m-rev.] for post-commit review: fixes for the transition guide

[Julien Fischer]

Fixes for the transition guide.

These are effectively a review of Zoltan's recent changes.

doc/transition_guide.texi:
         The there is no longer a bintree module in the standard library and
         rtree is very definitely a map ADT with a specialized purpose.

         Fix spelling, typos and missing words.

         Avoid breaking examples across pages it the PDF version.

Julien.

diff --git a/doc/transition_guide.texi b/doc/transition_guide.texi
index 8231ff7..b3985b6 100644
--- a/doc/transition_guide.texi
+++ b/doc/transition_guide.texi
@@ -152,23 +152,26 @@ The modes of the two arguments that are added to calls are
  @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 is then guaranteed to be the
+and the latter means that the output variable is guaranteed to be the
  only reference to the state of the world produced by this predicate.

  For example, the direct translation of the Prolog predicate

  @example
+ at group
  write_total(Total) :-
      write('The total is '),
      write(Total),
      write('.'),
      nl.
+ at end group
  @end example

  @noindent
  into Mercury yields this Mercury predicate:

  @example
+ at group
  :- pred write_total(int::in, io::di, io::uo) is det.

  write_total(Total, IO0, IO) :-
@@ -176,6 +179,7 @@ write_total(Total, IO0, IO) :-
      print(Total, IO1, IO2),
      print('.', IO2, IO3),
      nl(IO3, IO).
+ at end group
  @end example

  The variables @code{IO0}, @code{IO1} etc each represent
@@ -196,17 +200,19 @@ and let the compiler name the various versions.
  With state variables, the above clause would be written as

  @example
+ at group
  write_total(Total, !IO) :-
      print("The total is ", !IO),
      print(Total, !IO),
      print('.', !IO),
      nl(!IO).
+ at end group
  @end example

  and the compiler will internally convert this clause
  into code that looks like the previous clause.
  (The usual convention in Mercury programs
-is to name the state variable reprenting the state of the world @code{!IO}.)
+is to name the state variable representing the state of the world @code{!IO}.)

  In the head of a clause,
  what looks like an argument that consists of
@@ -214,7 +220,7 @@ a variable name prefixed by an exclamation mark
  actually stands for two arguments which are both variables,
  holding the initial and final state
  of whatever entity the state variable stands for.
-In this case, they stands for the state of the world,
+In this case, they stand for the state of the world,
  respectively before and after the line about the total has been printed.
  In calls in the body of a clause,
  what looks like an argument that consists of
@@ -225,7 +231,8 @@ but these hold respectively, the current and the next state.
  In Prolog, it is quite normal to give to @code{print}
  an argument that is an atom that is not used anywhere else in the program,
  or at least not in code related to the code that does the printing.
-This is because the term being printed does not have belong to a defined type.
+This is because the term being printed does not have to belong to a defined
+type.
  Since Mercury is strongly typed, the atom being printed
  @emph{would} have to be a data constructor of a defined type.
  A Mercury programmer @emph{could} define a meaningless type
@@ -234,17 +241,19 @@ but it is far better to simply call a predicate specifically designed
  to print the string you want printed:

  @example
+ at group
  write_total(Total, !IO) :-
      io.write_string("The total is ", !IO),
      io.print(Total, !IO),
      io.write_char('.', !IO),
      io.nl(!IO).
+ at end group
  @end example

  The @code{io.} prefix on the predicates called in the body indicates that
  the callees are in the @code{io} module of the Mercury standard library.
  This module contains all of Mercury's primitive I/O operations.
-These @emph{module qualification} are not strictly necessary
+These @emph{module qualifications} are not strictly necessary
  (unless two or more modules define predicates
  with the same names and argument types,
  the Mercury compiler can figure out which modules called predicates are in),
@@ -287,14 +296,16 @@ In some circumstances, Prolog programs that suffer from this problem
  can be fixed by moving the I/O out of the failing context.
  For example

- at example
-    ...
+ at example 
+ at group
+    @dots{}
      ( solve(Goal) ->
-        ...
+        @dots{}
      ;
-        ...
+        @dots{}
      ),
      ...
+ at end group
  @end example

  @noindent
@@ -303,16 +314,18 @@ can be transformed into valid Mercury in at least two ways.
  The first is to make @samp{solve} deterministic and return a status:

  @example
-    ...
+ at group
+    @dots{}
      solve(Goal, Result, !IO),
      (
-        Result = success(...),
-        ...
+        Result = success(@dots{}),
+        @dots{}
      ;
          Result = failure,
-        ...
+        @dots{}
      ),
-    ...
+    @dots{} 
+ at end group
  @end example

  The other way is to transform @samp{solve} so that
@@ -334,7 +347,7 @@ all the input and output takes place outside it:
  @node AssertRetract
  @chapter Assert and retract

-Calls to the builtin predicates @code{assert} and @code{retract}
+In Prolog, calls to the builtin predicates @code{assert} and @code{retract}
  can change the set of clauses of the program currently being executed.
  This makes compilation very tricky,
  and different Prolog systems react differently
@@ -368,7 +381,7 @@ lists with specific semantics and operations appropriate to those semantics.
  If the order of items in the collection is not important,
  and if the items are key-value pairs,
  you can store them in ADTs implementing several different kinds of trees,
-including @code{bintree}, @code{rbtree}, @code{rtree}, and @code{tree234}.
+including @code{rbtree} and @code{tree234}.
  In the absence of a compelling reason to choose a different implementation,
  we recommend the @code{map} ADT for generic use.
  Maps are implemented using 234 trees,
@@ -377,7 +390,8 @@ but also have good performance in the average case.
  @c but in the future it may change to a hash table, or a trie,
  @c or it may become a module that chooses among several implementation methods
  @c dynamically depending on the size and characteristics of the data.
- at code{bimap} and @code{multi_map} are specialized version of maps.
+ at code{bimap}, @code{injection}, @code{multi_map} and @code{rtree} are
+specialized version of maps.

  If the items in the collection are not key-value pairs,
  then consider the @code{set} and @code{bag} ADTs.
@@ -412,12 +426,12 @@ These predicates take an argument of type @code{univ}, the universal type,
  so that by using @code{type_to_univ} and @code{univ_to_type}
  it is possible to store data of any type in the @code{io.state}.

-Alternatively, you can things up so that
+Alternatively, you set can things up so that
  the getter and setter predicates of a mutable are @emph{not} I/O operations,
  but in that case calls to those predicates are not considered pure Mercury,
  and must instead use Mercury's mechanisms for controlled impurity.
  These mechanisms require all code that is not pure Mercury
-musy be explicitly marked as such.
+to be explicitly marked as such.
  They are intended to allow programmers
  to implement pure interfaces using @emph{small} pieces of impure code,
  for use in circumstances where there is no feasible way