diff: documentation for pragma fact_table

[Fergus Henderson]

doc/reference_manual.texi:
	Document the support for `pragma fact_table'.

Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.63
diff -u -r1.63 reference_manual.texi
--- reference_manual.texi	1997/07/28 12:04:50	1.63
+++ reference_manual.texi	1997/07/28 12:17:59
@@ -2537,6 +2537,8 @@
                                 @samp{#@var{line}} directives provide support
                                 for preprocessors and other tools that
                                 generate Mercury code.
+* Implementation-dependent pragmas::
+                                Implementations may support additional pragmas.
 @end menu
 @c * Tabling::                     Mercury predicates can be evaluated
 @c                                 using a three different forms of tabled
@@ -2562,7 +2564,7 @@
 * Using C pointers::                    Maintaining a reference to C data
                                         structures in Mercury code.
 * Memory management::                   Caveats about passing dynamically
-					allocated memory to or from C.
+                                        allocated memory to or from C.
 @end menu
 
 The Mercury distribution includes a number of examples of the
@@ -2577,7 +2579,7 @@
 
 @example
 :- pragma c_code(@var{Pred}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, ...),
-	may_call_mercury, @var{C_Code}).
+        may_call_mercury, @var{C_Code}).
 @end example
 
 @noindent
@@ -2598,7 +2600,7 @@
 :- mode c_write_string(in, di, uo) is det.
 
 :- pragma c_code(c_write_string(S::in, IO0::di, IO::uo),
-	may_call_mercury,
+        may_call_mercury,
         "puts(S); IO = IO0;").
 @end example
 
@@ -2607,7 +2609,7 @@
 
 @example
 :- pragma c_code(@var{Pred}(@var{Var1}::@var{Mode1}, @var{Var2}::@var{Mode2}, ...),
-	will_not_call_mercury, @var{C_Code}).
+        will_not_call_mercury, @var{C_Code}).
 @end example
 
 This allows the compiler to use a more efficient calling convention.
@@ -3009,6 +3011,56 @@
 to reset the source file name and line number to point back to the
 generated file for the automatically generated text, as in the above
 example.
+
+ at node Implementation-dependent pragmas
+ at section Implementation-dependent pragmas
+
+The @samp{pragma} declarations described above are a standard part of
+the Mercury language.  However, as an extension, implementations may
+also choose to support additional pragmas with implementation-dependent
+semantics.
+
+The University of Melbourne Mercury implemenation supports the following
+additional pragmas:
+
+ at menu
+* Fact tables::         Support for very large tables of facts
+ at end menu
+
+ at node Fact tables
+ at subsection Fact tables
+
+Large tables of facts can be compiled using a different algorithm that
+is more efficient and produces more efficient code.
+
+A declaration of the form
+
+ at example
+:- pragma fact_table(@var{Name}/@var{Arity}, @var{FileName}).
+ at end example
+
+ at noindent
+tells the compiler that the predicate or function with name @var{Name}
+and arity @var{Arity} is defined by a set of facts in an external file
+ at var{FileName}.  Defining large tables of facts in this way allows the
+compiler to use a more efficient algorithm for compiling them.
+This algorithm uses less memory than would normally be required
+to compile the facts so much larger tables are possible.
+
+Each mode is indexed on all its input arguments so the compiler can
+produce very efficient code using this technique.
+
+In the current implementation, the table of facts is compiled into a
+separate C file named @samp{@var{FileName}.c}.  The compiler will
+automatically generate the correct depencencies for this file when the
+command @samp{mmake @var{main_module}.depend} is invoked.  This ensures
+that the C file will be compiled to @samp{@var{FileName}.o} and then
+linked with the other object files when @samp{mmake @var{main_module}}
+is invoked.
+
+The main limitation of the @samp{fact_table} pragma is that
+predicates or functions defined as fact tables can only have
+arguments of types @samp{string}, @samp{int} or @samp{float}.
 
 @contents
 @bye

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