[m-dev.] for review: Aditi documentation

[Fergus Henderson]

On 09-Jul-1998, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> 
> +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.

The solution to that is to add the tr90-2.ps paper to the
Mercury www directory (which is in the CVS repository).

> Index: user_guide.texi
...
> + 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

What's Aditi-RL?

There should be a cross-reference here to a section
"Using Aditi".  That section should explain how
to use the Aditi interface.  (Step 1: install Aditi ...)

All of the documentation for the options relating only to Aditi should
be commented out until they are useful, i.e. until Aditi is publically
available.  You commented some of them out but not all of them.

Actually TexInfo has features for conditional inclusion, so you
could use those.

	@c Uncomment the line below to enable documentation
	@c of the Aditi interface
	@c @set aditi

	@ifset aditi
	...
	@end ifset

This would be a better idea, now that I think of it, because
(a) you could easily produce a version of the manual with the
    Aditi features included; this would make it easier for you
    to check that your documentation is correctly formatted,
    as well as being useful for 
(b) you could be sure that when we do enable the documentation
    for Aditi, we enable it all; there's no danger of someone
    forgetting to uncomment the documentation for
    `--debug-rl-opt', for example.

> + at sp 1
> + at item --aditi-only
> +Write Aditi-RL bytecode to `<module>.rlo' and do not compile to C.
>  @end table

s/<module>/@var{module}/
s/`/@file{/
s/'/}/

Similarly for all the other stuff you added.

>  @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'.

How about "... of the generated Aditi-RL code ..."?

> + at sp 1
> + at item --dump-rl-bytecode
> +Output a human readable representation of Aditi-RL
> +bytecodes to `<module>.rla'.

How about "... of the generated Aditi-RL bytecodes ..."?

It might be useful to briefly explain the different between
Aditi-RL and Aditi-RL bytecode here, or to cross-reference
to somewhere else that explains it.

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

What's a schema string?
What's a base relation?
There should be a cross-reference here to somewhere
that explains these terms (perhaps the Aditi manual).

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

The language reference manual doesn't give detailed explanations
of these optimizations.

Also, would 

	s/Aditi-RL procedures/Aditi-RL code/

(just here, not below) make it clearer?

> +@ table code
> + at item --optimize-rl
> +Enable optimization of Aditi-RL procedures.

Does this just have the effect of enabling the
three optimizations below?  If so, please say so.

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

For consistency, I suggest you add "in Aditi-RL procedures"
in between "results" and "do".

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

The command line lets you also specify module names instead
of file names; does this option allow that?

> + at sp 1
> + at item --aditi
> +Enable Aditi compilation.

If the user doesn't know what "Aditi" means, then they
will be none the wiser after reading this documentation.

There should be a slighly more detailed explanation
here, and a cross-reference to a "Using Aditi" section;
e.g.

	Enable Aditi compilation.  You need to enable
	this option if you are making use of the Aditi
	deductive database interface described in the
	``Implementation dependent pragmas'' section of
	the ``Pragmas'' of the Mercury language reference
	manual.

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

Missing full stop.

What happens if the USER environment variable isn't set?

--------------------

I'd like to see another diff for this one.

Thanks,
	Fergus.

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