for review: Aditi documentation

[Simon Taylor]

Estimated hours taken: 1.5

doc/reference_manual.texi
doc/user_guide.texi
	Documentation of Aditi options and pragmas (mostly commented out).



Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.98
diff -u -t -u -r1.98 reference_manual.texi
--- reference_manual.texi	1998/06/30 08:54:29	1.98
+++ reference_manual.texi	1998/07/09 05:25:48
@@ -4169,6 +4169,9 @@
                                 calculated results and detecting or avoiding
                                 certain kinds of infinite loops.
 * Termination analysis::        Support for automatic proofs of termination.
+ at c * Aditi deductive database interface::
+ at c                              Support for bottom-up evaluation of Mercury
+ at c                              predicates.
 @end menu
 
 @node Fact tables
@@ -4375,6 +4378,76 @@
 If it cannot prove the termination of the specified predicate or
 function then the compiler will quit with an error message.
 
+ at ignore
+ at node Aditi deductive database interface
+ at subsection Aditi deductive database interface
+
+The compiler includes support for compiling Mercury predicates for bottom-up
+evaluation using the Aditi deductive database system. The Aditi system is not
+yet publicly available, so this is currently not very useful to anyone other
+than the Mercury and Aditi developers.
+
+Evaluation by a deductive database system is useful for predicates which
+use large amounts of data, since the database system can use efficient join
+algorithms instead of backtracking. Also, some predicates which loop when
+executed top-down may terminate when executed bottom-up by the database.
+
+There are several restrictions on predicates to be evaluated using Aditi.
+Argument types may include polymorphic, higher-order or abstract types.
+Type classes are not supported within database predicates. The argument
+modes must not contain partially instantiated insts. Every Aditi predicate
+must have one input argument of type @samp{aditi:state} - this ensures
+that database predicates cannot be called outside a transaction.
+
+Some useful predicates are defined in @samp{aditi/aditi.m} in the
+ at samp{extras} distribution.
+
+The following pragma declarations control Aditi compilation.
+
+ at example
+:- pragma aditi(@var{Name}/@var{Arity}).
+ at end example
+
+This predicate should be evaluated using the Aditi deductive database.
+
+ at example
+:- pragma base_relation(@var{Name}/@var{Arity}).
+ at end example
+
+This predicate is an Aditi base_relation. There must be no clauses for the
+predicate.
+
+ at example
+:- pragma supp_magic(@var{Name}/@var{Arity}).
+:- pragma context(@var{Name}/@var{Arity}).
+ at end example
+
+Perform either the supplementary magic sets or context transformations.
+One of these transformations must be performed on every Aditi predicate.
+ at samp{supp_magic} is the default.
+There are restrictions on predicates to which the context transformation
+can be applied described in @cite{Right-, left-, and multi-linear rule
+transformations that maintain context information.} @ref{[6]}.
+
+ at example
+:- pragma naive(@var{Name}/@var{Arity}).
+:- pragma psn(@var{Name}/@var{Arity}).
+ at end example
+
+Specify naive or predicate semi-naive evaluation for the predicate.
+ at samp{psn} is the default.
+
+ at example
+:- pragma memo(@var{Name}/@var{Arity}).
+:- pragma no_memo(@var{Name}/@var{Arity}).
+ at end example
+
+The Aditi deductive database can store the results of procedures within
+a transaction to avoid unnecessary recomputations.
+ at samp{no_memo} is the default.  @c XXX this will probably change
+
+ at end ignore
+
 @node Bibliography
 @chapter Bibliography
 
@@ -4387,6 +4460,9 @@
 * [4]::         Sagonas, @cite{The SLG-WAM: A Search-Efficient Engine
                 for Well-Founded Evaluation of Normal Logic Programs}.
 * [5]::         Demoen and Sagonas, @cite{CAT: the copying approach to tabling}.
+ at c * [6]::      Kemp, Ramamohanarao and Somogyi,
+ at c              @cite{Right-, left-, and multi-linear rule transformations
+ at c              that maintain context information}.
 @end menu
 
 @node [1]
@@ -4424,6 +4500,18 @@
 B. Demoen and K. Sagonas, @cite{CAT: the copying approach to tabling},
 submitted for publication,
 Katholieke Universiteit Leuven, 1998.
+
+ at ignore
+ at node [6]
+ at unnumberedsec [6]
+David B. Kemp and Kotagiri Ramamohanarao and Zoltan Somogyi. 
+ at cite{Right-, left-, and multi-linear rule transformations that maintain
+context information}, 
+The Proceedings of the Sixteenth Conference on Very Large Databases, pages
+380--391, August 1990.
+Available from <http://www.cs.mu.oz.au/~kemp/papers/tr90-2.ps>.
+ at c XXX David Kemp doesn't work here any more - this link may disappear.
+ at end ignore
 
 @contents
 @bye
Index: user_guide.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/user_guide.texi,v
retrieving revision 1.129
diff -u -t -u -r1.129 user_guide.texi
--- user_guide.texi	1998/07/03 06:43:47	1.129
+++ user_guide.texi	1998/07/09 05:39:17
@@ -1623,6 +1623,19 @@
 Output detailed debugging traces of the value numbering optimization pass.
 The different bits in the number argument of this option control the
 printing of different types of tracing messages.
+
+ at sp 1
+ at item --debug-pd
+Output detailed debugging traces of the partial
+deduction and deforestation process.
+
+ at sp 1
+ at item --debug-rl-gen
+Output detailed debugging traces of Aditi-RL code generation.
+
+ at sp 1
+ at item --debug-rl-opt
+Output detailed debugging traces of Aditi-RL optimization.
 @end table
 
 @node Output options
@@ -1726,6 +1739,10 @@
 Generate C code in @file{@var{module}.c}
 and object code in @file{@var{module}.o}
 but do not attempt to link the named modules.
+
+ at sp 1
+ at item --aditi-only
+Write Aditi-RL bytecode to `<module>.rlo' and do not compile to C.
 @end table
 
 @node Auxiliary output options
@@ -1819,6 +1836,22 @@
 The special argument value ``all''
 will cause the printing of all these fields.
 
+ at sp 1
+ at item --dump-rl
+Output a human readable representation of Aditi-RL
+to `<module>.rl_dump'.
+
+ at sp 1
+ at item --dump-rl-bytecode
+Output a human readable representation of Aditi-RL
+bytecodes to `<module>.rla'.
+
+ at sp 1
+ at item --generate-schemas
+Output schema strings for Aditi base relations
+to `<module>.base_schema' and for Aditi derived
+relations to `<module>.derived_schema'.
+
 @end table
 
 @node Language semantics options
@@ -2262,6 +2295,7 @@
 * Low-level (LLDS -> LLDS) optimization options::
 * Output-level (LLDS -> C) optimization options::
 * Object-level (C -> object code) optimization options::
+ at c * Aditi-RL optimization options::
 @end menu
 
 @node Overall optimization options
@@ -2635,6 +2669,35 @@
 
 @end table
 
+ at ignore
+ at node Aditi-RL optimization options
+ at subsection Aditi-RL optimization options
+
+These optimizations are applied to the Aditi-RL procedures produced
+for predicates with @samp{:- pragma aditi(...)} declarations.
+For detailed explanations, see the ``Aditi deductive database interface''
+section in Mercury Language Reference Manual.  (It is listed under
+``Implementation dependent pragmas'' in the ``Pragmas'' chapter.)
+
+@ table code
+ at item --optimize-rl
+Enable optimization of Aditi-RL procedures.
+
+ at sp 1
+ at item --optimize-rl-cse
+Optimize common subexpressions in Aditi-RL procedures.
+
+ at sp 1
+ at item --optimize-rl-invariants
+Optimize loop invariants in Aditi-RL procedures.
+
+ at sp 1
+ at item --detect-rl-streams
+Detect cases where intermediate results do not need to be materialised.
+
+ at end table
+ at end ignore
+
 @node Miscellaneous options
 @section Miscellaneous options
 @table @code
@@ -2667,6 +2730,21 @@
 @c This option is now obsolete.  In the past it was used to avoid
 @c NU-Prolog's "Panic: growing stacks has required shifting the heap"
 @c message.
+
+ at sp 1
+ at item --filenames-from-stdin
+Read a newline separated list of `.m' files to compile
+from the standard input rather than the command line.
+
+ at sp 1
+ at item --aditi
+Enable Aditi compilation.
+
+ at sp 1
+ at item --aditi-user
+Specify the Aditi login of the owner of any Aditi RL files produced.
+Defaults to the value of the USER environment variable
+
 @end table
 
 @node Link options