[m-rev.] minor fixes for reference manual
Fergus Henderson
fjh at cs.mu.OZ.AU
Thu Nov 22 14:13:32 AEDT 2001
Simon, you might want to review the changes to the Aditi
documention here. The rest of it is pretty trivial.
----------
Estimated hours taken: 0.75
Branches: main
doc/reference_manual.texi:
Add some missing `@noindent' declarations,
and some missing blank lines around `@example ... @end example'.
Also some minor changes in the wording of the section on
Aditi update goals, to improve readability.
Workspace: /home/earth/fjh/ws-earth4/mercury
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.226
diff -u -d -r1.226 reference_manual.texi
--- doc/reference_manual.texi 22 Nov 2001 02:07:20 -0000 1.226
+++ doc/reference_manual.texi 22 Nov 2001 03:09:07 -0000
@@ -1067,9 +1067,12 @@
@subsection Unification expressions
A unification expression is an expression of the form
+
@example
X @@ Y
@end example
+
+ at noindent
where @var{X} and @var{Y} are data-terms.
The semantics of a unification expression is that @var{X} and @var{Y}
@@ -1984,6 +1987,7 @@
listskel >> listskel.
@end example
+ at noindent
the (type and) mode declarations of the function length and predicate append
are as follows:
@@ -2045,6 +2049,7 @@
:- mode append(in_listskel, in_listskel, out_listskel).
@end example
+ at noindent
would not be allowed, since it would create aliasing between the
different arguments --- on success of the predicate, the list elements
would be free variables but they would not be distinct.
@@ -4103,6 +4108,7 @@
<= @var{Typeclass}(@var{TypeVariable}, @dots{}), @dots{}
@end example
+ at noindent
where @var{Typeclass} is the name of a type class and @var{TypeVariable} is
a type variable that appears in the predicate's or function's type signature.
@@ -4537,6 +4543,7 @@
'new cons'(String, nil))).
@end example
+ at noindent
while the function @samp{process_list} below applies the @samp{show}
method of the @samp{showable} class to the values in such a list.
@@ -4986,14 +4993,17 @@
:- pragma foreign_import_module("@var{Lang}", @var{ImportedModule}).
@end example
+ at noindent
where @var{ImportedModule} is the name of the module containing
the @samp{pragma export} declarations.
If @var{Lang} is @code{"C"} this is equivalent to
+
@example
:- pragma foreign_decl("C", "#include ""@var{ImportedModule.h}""").
@end example
+ at noindent
where @file{@var{ImportedModule}.h} is the automatically generated
header file containing the C declarations for the predicates
and functions exported to C.
@@ -5916,9 +5926,12 @@
@end example
This is equivalent to
+
@example
:- pragma c_header_code("#include ""imported_module.h""").
@end example
+
+ at noindent
but it tells the implementation that the object file for the
module containing the @samp{pragma c_import_module} declaration
should not be built before @file{imported_module.h} is built.
@@ -7204,6 +7217,7 @@
@example
:- pragma terminates(@var{Name}/@var{Arity}).
@end example
+
This declaration may be used to inform the compiler that this predicate
or function is guaranteed to terminate for any input. This is useful
when the compiler cannot prove termination of some predicates or
@@ -7213,6 +7227,7 @@
@example
:- pragma does_not_terminate(@var{Name}/@var{Arity}).
@end example
+
This declaration may be used to inform the compiler that this predicate
does not necessarily terminate. This is useful for procedures defined
using the C interface, which the compiler assumes to terminate by
@@ -7221,6 +7236,7 @@
@example
:- pragma check_termination(@var{Name}/@var{Arity}).
@end example
+
This pragma forces the compiler to prove termination of this predicate.
If it cannot prove the termination of the specified predicate or
function then the compiler will quit with an error message.
@@ -7459,6 +7475,7 @@
Predicate and function names in Aditi update goals may be module qualified.
The examples make use of the following declarations:
+
@example
:- pred p(aditi__state::aditi_mui, int::out, int::out) is nondet.
:- pragma base_relation(p/3).
@@ -7529,6 +7546,7 @@
@sp 1
Examples:
+
@example
insert_example_1(DB0, DB) :-
aditi_insert(p(_, 1, 2), DB0, DB).
@@ -7610,14 +7628,15 @@
@samp{aditi__state}. They have mode @w{@samp{aditi_di, aditi_uo}}.
@end itemize
- at c Don't delete the blank lines here -- they are needed for readability.
- at c @sp commands have no effect on the info file.
- at example
+ at sp 1
+The form
+ at example
aditi_bulk_insert((@var{PredName}(@var{DB1}, @var{Arg2}, @dots{}) :- @var{Goal}), @var{DB0}, @var{DB}).
@end example
+ at noindent
is equivalent to
@example
@@ -7626,17 +7645,18 @@
aditi_bulk_insert(@var{PredOrFunc} @var{Name}/@var{Arity}, @var{Closure}, @var{DB0}, @var{DB}).
@end example
-bulk_insert_example_1, bulk_insert_example_2 and bulk_insert_example_3 below
-are all equivalent.
-
- at c Don't delete the blank lines here -- they are needed for readability.
- at c @sp commands have no effect on the info file.
- at example
+ at noindent
+and likewise for the function version. For instance, the examples
+bulk_insert_example_1, bulk_insert_example_2 and bulk_insert_example_3
+below are all equivalent.
+Similarly, the form
+ at example
aditi_bulk_delete((@var{PredName}(@var{Arg1}, @var{Arg2}, @dots{}) :- @var{Goal}), @var{DB0}, @var{DB}).
@end example
+ at noindent
is equivalent to
@example
@@ -7648,11 +7668,14 @@
aditi_bulk_delete(@var{PredOrFunc} @var{Name}/@var{Arity}, @var{Closure}, @var{DB0}, @var{DB}).
@end example
+ at noindent
+and likewise for the function version. For instance
bulk_delete_example_1 and bulk_delete_example_2 below are equivalent.
@sp 2
Examples:
+
@example
bulk_insert_example_1(DB0, DB) :-
aditi_bulk_insert(p(DB1, X, Y) :- ancestor(DB1, X, Y), DB0, DB).
@@ -7797,7 +7820,8 @@
@sp 2
-The first syntax can be rewritten into the second:
+The forms using @samp{==>} can be considered as syntactic sugar for the
+form using @var{PredOrFunc} @var{PredName}/@var{Arity}:
@example
aditi_bulk_modify(
@@ -7808,6 +7832,7 @@
@var{DB0}, @var{DB}).
@end example
+ at noindent
is equivalent to
@example
@@ -7820,15 +7845,17 @@
aditi_bulk_modify(pred @var{PredName}/@var{PredArity}, ModifyClosure, DB0, DB).
@end example
- at c Don't delete the blank lines here -- they are needed for readability.
- at c @sp commands have no effect on the info file.
- at example
+ at noindent
+and likewise for the function version.
+The bulk modify operation
+ at example
aditi_bulk_modify(pred p/3, Closure, DB0, DB).
@end example
-is almost equivalent to
+ at noindent
+is almost equivalent to a bulk delete followed by a bulk insert:
@example
DeleteClosure =
@@ -7843,13 +7870,16 @@
aditi_bulk_insert(pred p/3, InsertClosure, DB1, DB).
@end example
-They are not quite equivalent because @var{InsertClosure}
+ at noindent
+However, they are not quite equivalent,
+because in the bulk modify operation @var{InsertClosure}
is executed using the contents of @samp{p/3} before the deletion
is applied.
@sp 2
Examples:
+
@example
bulk_modify_example_1(DB0, DB) :-
aditi_bulk_modify(
--
Fergus Henderson <fjh at cs.mu.oz.au> | "I have always known that the pursuit
The University of Melbourne | of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh> | -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post: mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------
More information about the reviews
mailing list