for review: update doc/transition_guide.texi

[Fergus Henderson]

Estimated hours taken: 0.5

doc/transition_guide.texi:
	This had suffered from documentation rot.  I updated it to reflect
	the fact that we now have write/3, print/3, and nl/2,
	and that we have solutions_set/2 and unsorted_solutions/2.

Index: doc/transition_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/transition_guide.texi,v
retrieving revision 1.23
diff -u -r1.23 transition_guide.texi
--- transition_guide.texi	1997/12/09 04:02:20	1.23
+++ transition_guide.texi	1998/11/20 06:36:03
@@ -224,9 +224,10 @@
 :- mode write_total(in, di, uo) is det.
 
 write_total(Total, IO0, IO) :-
-    io__write_string("The total is ", IO0, IO1),
-    io__write_int(Total, IO1, IO2),
-    io__write_string(".\n", IO2, IO).
+    print("The total is ", IO0, IO1),
+    print(Total, IO1, IO2),
+    print('.', IO2, IO3),
+    nl(IO3, IO).
 @end example
 
 Definite Clause Grammars (DCGs) are convenient syntactic sugar
@@ -235,9 +236,10 @@
 
 @example
 write_total(Total) -->
-    io__write_string("The total is "),
-    io__write_int(Total),
-    io__write_string(".\n").
+    print("The total is "),
+    print(Total),
+    print('.'),
+    nl.
 @end example
 
 In DCGs, any calls (including unifications)
@@ -245,21 +247,15 @@
 are escaped in the usual way by surrounding them in curly braces
 (@code{ @{ @} }).
 
-The library predicate @samp{io__write_string} writes only strings, 
-and the library predicate @samp{io__write_int} writes only integers,
-and you must work out yourself which should be called when.
-At the moment there is no predicate
-that can print a value of an arbitrary type.
-However, in the next release of the Mercury implementation
-we will implement a polymorphic @samp{io__write} predicate,
-so that you can write the above code as
+Note that in Mercury you normally use strings (@code{"..."})
+rather than atoms (@code{'...'}) for messages like @code{"The total is"}.
+(It's possible to use atoms, but you have to declare each
+such atom before-hand, so its more convenient to use strings.)
+However, for strings and characters, @samp{write} prints out the quotes;
+to avoid this, you need to use @samp{print} instead of @samp{write}.
 
- at example
-write_total(Total) -->
-    io__write("The total is "),
-    io__write(Total),
-    io__write(".\n").
- at end example
+Both @samp{write} and @samp{print} are defined in the @samp{io}
+module in the Mercury standard library.
 
 One of the important consequences of our model for input and output
 is that predicates that can fail may not do input or output.
@@ -568,12 +564,16 @@
 @node All-solutions
 @chapter All-solutions predicates.
 
-Unlike Prolog, which has a variety of subtly different all-solutions
-predicates (findall/3, bagof/3, setof/3, not to mention NU-Prolog's
-solutions/3), Mercury has a single all-solutions predicate called
-solutions/2.  To avoid the variable scoping problems of the Prolog
+Prolog's various different all-solutions predicates (findall/3, bagof/3,
+and setof/3) all have semantic problems.
+Mercury's has a different set of all-solutions predicates (solutions/2,
+solutions_set/2, and unsorted_solutions/2 -- all defined in the library
+module @samp{std_util}) that
+address the problems of the Prolog versions.
+To avoid the variable scoping problems of the Prolog
 versions, rather than taking both a goal to execute and an aliased
-term holding the resulting value to collect, Mercury's solutions/2 takes
+term holding the resulting value to collect, Mercury's all-solutions
+predicates take
 as input a single higher-order predicate term.  The Mercury equivalent to
 
 @example

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.