[m-dev.] for review: Aditi documentation

[Fergus Henderson]

Thanks, Simon.

I have some more suggestions:

> +++ reference_manual.texi	1998/07/16 05:12:20
...
> + at ifset aditi
> + 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.

s/compiler/The University of Melbourne Mercury implementation/

> +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.

I suggest you add here a comment that another solution in such cases is to use
tabling, and cross-reference to the section on tabling.

> +There are several restrictions on predicates to be evaluated using Aditi.
> +Argument types may not 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. Aditi
> +predicates must be stratified and must not be mutually recursive with
> +predicates in other modules.

Please s/aditi:state/aditi__state/

You should explain what "stratified" means, or give a cross-reference to
somewhere that does.

Oh, I see that you explain it in the glossary.
A cross-reference would still be helpful, I think.

	Aditi predicates must be stratified (@pxref{Aditi glossary}) and ...

> +Some useful predicates are defined in @file{aditi/aditi.m} in the
> + at samp{extras} distribution.

s^aditi^extras/aditi^
s^extras^mercury-extras^

> +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]}.

I suggest s/applied described/applied; these are described/

> + 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.

You should explain the difference between these, or give a cross-reference
to somewhere that does.

> + 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.
> + at c XXX this will probably change

`pragma memo' is already used by the tabling interface.

Are the semantics the same?  I think the semantics here
would probably be more like the semantics for `pragma minimal_model'.

If the semantics are different, then you should definitely use
a different name.

If the semantics are the same, it may be reasonable to use the same
pragma.  But if so, you should document the fact that it has two
slightly different operational effects depending on whether it is
applied to an Aditi or a non-Aditi predicate, and you should put
cross-references in both places where it is documented.

> + at example
> +:- pragma owner(@var{Name}/@var{Arity}, @var{UserName}).
> + at end example
> +
> +The predicate is owned by the named user. A predicate in the database
> +is identified by owner, module name, predicate name and arity. If no
> + at samp{:- pragma owner(...)} declaration is given, the owner is taken from
> +the @samp{--aditi-user} option.

What if the `--aditi-user' option was not specified?

> + at item @samp{aditi:state}
> +Every predicate with a @samp{:- pragma aditi(...)} or
> + at samp{:- pragma base_relation(...)} declaration must have an input
> +argument of type @samp{aditi:state}. This ensures that Aditi predicates
> +are only called from within transactions and that updates and database
> +calls are ordered correctly, in the same way that @samp{io__state} arguments
> +are used to ensure ordering of I/O operations.

s/aditi:state/aditi__state/g

> + at item schema
> +A schema is a representation of the types of the attributes a relation.

"... the attributes of a relation"?
                    ^^

> + at item stratification
> +A program is stratified if there are no recursive arcs in the call graph
> +which pass through a negation or an aggregate.

What's an aggregate?
That should be another entry in the glossary.

For that matter, what's a call graph,
and what's a recursive arc in a call graph?
I think you could explain this concept without talking about graphs
and arcs.

> + at item transaction
> +A transaction is a database operation which is executed atomically. If
> +part of a transaction fails, the database reverts to its original state
> +before the transaction. For details on how transactions are implemented
> +in Mercury, see @cite{Database transactions in a purely declarative logic
> +programming language} @ref{[7]} and @file{aditi/aditi.m} in the
> + at samp{extras} distribution.

As above -- aditi/aditi.m should be extras/aditi/aditi.m,
and the distribution is the `mercury-extras' distribution.

user_guide.texi:
> +the file @file{aditi/aditi.m} in the @samp{extras} distribution

Likewise.

> +To compile code which accesses an Aditi database, you will need to install
> +the Aditi library in the @samp{aditi} subdirectory of the @samp{extras}
> +distribution. Once you have done that, use the Mmakefile in

Likewise.

> + at sp 1
> + at item --filenames-from-stdin
> +Read a newline separated list of module names to compile
> +from the standard input rather than the command line.

I still don't quite understand the rationale for this option.
Why not just use

	mmc `cat`

?
If the idea is to get interactive compilation (read a file name,
compile it, read the next one, compiler that) without having to the
overhead of process creation each time, then I think the documentation
should say that -- the specification should be tighter (the current
specification could be met fine by reading all the files
until EOF, and only then starting to compile the first file)
and it should also explain the rationale.

> + 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. If USER is
> +not set, @samp{--aditi-user} defaults to the string ``guest''. 

s/USER/@samp{USER}/

> Index: papers.html
...
> +<a href = "./mu_96_45_cover.ps.gz">

Why the `./'?

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.