[m-dev.] documentation for pragma fact_table

[David Matthew OVERTON]

Hi Fergus,

Could you please review the following changes.

David.

--------

Estimated hours taken: 1

Added documentation for `pragma fact_table's to the user guide and
reference manual.  The additions are commented out at the moment.

doc/reference_manual.texi:
	Added a new (commented out) section describing the
	`fact_table' pragma.  

doc/user_guide.texi:
	Added (commented out) documentation for the two new invocation
	options relating to `pragma fact_table's.


Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.49
diff -u -r1.49 reference_manual.texi
--- 1.49	1997/01/27 07:46:37
+++ reference_manual.texi	1997/03/04 06:49:09
@@ -2458,7 +2458,10 @@
 @c * Tabling::                     Mercury predicates can be evaluated
 @c                                 using a three different forms of tabled
 @c                                 evaluation.
-
+ at c * Large Tables of Facts		Large tables of facts can be compiled
+ at c				using a different algorithm that is
+ at c				more efficient and produces more
+ at c				efficient code.
 * Obsolescence::		Library developers can declare old versions
 				of predicates or functions to be obsolete.
 * Source file name::		The @samp{source_file} pragma and
@@ -2732,6 +2735,37 @@
 @c with name @var{Name} and arity @var{Arity} should be evaluated using
 @c memoing.
 
+ at c @node Large Tables of Facts
+ at c @section Large Tables of Facts
+ at c 
+ at c A declaration of the form
+ at c 
+ at c @example
+ at c :- pragma fact_table(@var{Name}/@var{Arity}, @var{FileName}).
+ at c @end example
+ at c 
+ at c @noindent
+ at c tells the compiler that the predicate or function with name @var{Name}
+ at c and arity @var{Arity} is defined by a set of facts in an external file
+ at c @var{FileName}.  Defining large tables of facts in this way allows the
+ at c compiler to use a more efficient algorithm for compiling them.
+ at c This algorithm uses less memory than would normally be required
+ at c to compile the facts so much larger tables are possible.
+ at c 
+ at c Each mode is indexed on all its input arguments so the compiler can
+ at c produce very efficient code using this technique.
+ at c 
+ at c In the current implementation, the table of facts is compiled into a
+ at c separate C file named @samp{@var{FileName}.c}.  The compiler will
+ at c automatically generate the correct depencencies for this file when the
+ at c command @samp{mmake @var{main_module}.depend} is invoked.  This ensures
+ at c that the C file will be compiled to @samp{@var{FileName}.o} and then
+ at c linked with the other object files when @samp{mmake @var{main_module}}
+ at c is invoked.
+ at c 
+ at c Currently the only types supported with the @samp{fact_table} pragma
+ at c are the builtin @samp{string}, @samp{int} and @samp{float} types.
+
 @node Obsolescence
 @section Obsolescence
 
Index: user_guide.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/user_guide.texi,v
retrieving revision 1.82
diff -u -r1.82 user_guide.texi
--- 1.82	1997/02/01 08:38:31
+++ user_guide.texi	1997/03/04 06:54:48
@@ -1448,6 +1448,20 @@
 @item --cflags @var{options}
 Specify options to be passed to the C compiler.
 
+ at c @sp 1
+ at c @item --fact-table-max-array-size @var{size}
+ at c Specify the maximum number of elements in a single 
+ at c @samp{pragma fact_table} data array (default: 1024).
+ at c The data for fact tables is placed into multiple C arrays, each with a
+ at c maximum size given by this option.  The reason for doing this is that
+ at c most C compilers have trouble compiling very large arrays.
+ at c 
+ at c @sp 1
+ at c @item --fact-table-hash-percent-full @var{percentage}
+ at c Specify how full the @samp{pragma fact_table} hash tables should be
+ at c allowed to get.  Given as an integer percentage (valid range: 1 to 100,
+ at c default: 90).
+
 @end table
 
 @node Optimization options