[m-dev.] for review: reorganise reference_manual.texi
Simon Taylor
stayl at cs.mu.OZ.AU
Wed Aug 4 14:11:21 AEST 1999
Estimated hours taken: 2
doc/reference_manual.texi:
Reorganise the reference manual to move the "C interface", "Impurity"
and "Implementation-dependent pragmas" sections out of the "Pragmas"
chapter. The rationale for this change is that it is interesting
to readers that the language supports these features, not that
there are pragmas to control them. Also, the nesting in the
"Pragmas" chapter was becoming excessive.
doc/user_guide.texi:
Refer to the "Implementation-dependent extensions" chapter
rather than the "Implemenentation-dependent pragmas" section
of the reference manual.
doc/*.texi:
Be consistent about the use of full stops at the end of
menu item descriptions. All menu item descriptions now
end with full stops (as in the texinfo info file).
Index: faq.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/faq.texi,v
retrieving revision 1.22
diff -u -u -r1.22 faq.texi
--- faq.texi 1999/03/24 13:08:55 1.22
+++ faq.texi 1999/08/04 02:35:24
@@ -74,9 +74,9 @@
@node Top,,, (mercury)
@top The Mercury Frequently Asked Questions list
@menu
-* Programming:: Common programming errors
-* Unimplemented:: Problems caused by unimplemented Mercury features
-* Last resort:: What to do when all else fails
+* Programming:: Common programming errors.
+* Unimplemented:: Problems caused by unimplemented Mercury features.
+* Last resort:: What to do when all else fails.
@end menu
@end ifinfo
Index: reference_manual.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/reference_manual.texi,v
retrieving revision 1.148
diff -u -u -r1.148 reference_manual.texi
--- reference_manual.texi 1999/08/04 03:23:57 1.148
+++ reference_manual.texi 1999/08/04 04:04:43
@@ -73,25 +73,33 @@
@top
@end ifinfo
@menu
-* Introduction:: A brief introduction to Mercury
-* Syntax:: Mercury's syntax is similar to ISO Prolog
-* Types:: Mercury has a strong parametric polymorphic type system
-* Modes:: Modes allow you to specify the direction of data flow
+* Introduction:: A brief introduction to Mercury.
+* Syntax:: Mercury's syntax is similar to ISO Prolog.
+* Types:: Mercury has a strong parametric polymorphic type system.
+* Modes:: Modes allow you to specify the direction of data flow.
* Unique modes:: Unique modes allow you to specify when there is only one
reference to a particular value, so the compiler can
- safely use destructive update to modify that value
+ safely use destructive update to modify that value.
* Determinism:: Determinism declarations let you specify that a predicate
- should never fail or should never succeed more than once
+ should never fail or should never succeed more than once.
* Equality preds:: User-defined types can have user-defined equality
predicates.
* Higher-order:: Mercury supports higher-order predicates and functions,
- with closures, lambda expressions, and currying
-* Modules:: Modules allow you to divide a program into smaller parts
-* Type classes:: Constrained polymorphism
-* Existential types:: Support for data abstraction and heterogeneous collections
-* Semantics:: Declarative and operational semantics of Mercury programs
-* Pragmas:: Various compiler directives, used for the C interface
- and to control optimization.
+ with closures, lambda expressions, and currying.
+* Modules:: Modules allow you to divide a program into smaller parts.
+* Type classes:: Constrained polymorphism.
+* Existential types:: Support for data abstraction and heterogeneous
+ collections.
+* Semantics:: Declarative and operational semantics of Mercury
+ programs.
+* C interface:: The C interface allows C code to be called
+ from Mercury code, and vice versa.
+* Impurity:: Users can write impure Mercury code.
+* Pragmas:: Various compiler directives, used for example to
+ control optimization.
+* Implementation-dependent extensions::
+ The University of Melbourne Mercury implementation
+ supports several extensions to the Mercury language.
* Bibliography:: References for further reading.
@end menu
@@ -3818,33 +3826,8 @@
evaluation is lazy, rather than strict; semantics with a guaranteed
fair search rule; and so forth.
- at node Pragmas
- at chapter Pragmas
-
- at ifinfo
-There are several uses for @code{pragma} declarations:
- at end ifinfo
-
- at menu
-* C interface:: The C interface allows C code to be called
- from Mercury code, and vice versa.
-* Impurity:: Users can write impure Mercury code
-* Inlining:: Pragmas can be used to suggest or prevent
- procedure inlining.
-* Type specialization:: Pragmas can be used to produce specialized
- versions of polymorphic procedures.
-* Obsolescence:: Library developers can declare old versions
- of predicates or functions to be obsolete.
-* Source file name:: The @samp{source_file} pragma and
- @samp{#@var{line}} directives provide support
- for preprocessors and other tools that
- generate Mercury code.
-* Implementation-dependent pragmas::
- Implementations may support additional pragmas.
- at end menu
-
@node C interface
- at section C interface
+ at chapter C interface
@menu
* Calling C code from Mercury:: How to implement a Mercury predicate
@@ -3872,7 +3855,7 @@
See the @samp{samples/c_interface} directory in the Mercury distribution.
@node Calling C code from Mercury
- at subsection Calling C code from Mercury
+ at section Calling C code from Mercury
There are two slightly different mechanisms for calling C code from Mercury:
@samp{pragma import} and @samp{pragma c_code}. @samp{pragma import}
@@ -3887,8 +3870,8 @@
@c e.g. "pragma import" rather than "@samp{pragma import}".
@c
@menu
-* pragma import:: Importing C functions
-* pragma c_code:: Defining Mercury procedures using C code
+* pragma import:: Importing C functions.
+* pragma c_code:: Defining Mercury procedures using C code.
* Nondet pragma c_code:: Using @samp{pragma c_code} for Mercury procedures
that can have more than one solution.
* C code attributes:: Describing properties of C functions or C code.
@@ -3896,7 +3879,7 @@
@end menu
@node pragma import
- at subsubsection pragma import
+ at subsection pragma import
A declaration of the form
@@ -3965,7 +3948,7 @@
using @samp{pragma c_code} -- @pxref{Nondet pragma c_code}).
@node pragma c_code
- at subsubsection pragma c_code
+ at subsection pragma c_code
A declaration of the form
@@ -4052,7 +4035,7 @@
set @code{SUCCESS_INDICATOR} to false (zero).
@node Nondet pragma c_code
- at subsubsection Nondet pragma c_code
+ at subsection Nondet pragma c_code
For procedures that can return more than one result on backtracking,
i.e. those with determinism @samp{nondet} or @samp{multi},
@@ -4179,7 +4162,7 @@
@end example
@node C code attributes
- at subsubsection C code attributes
+ at subsection C code attributes
As described above, @samp{pragma import} and @samp{pragma c_code}
declarations may include a list of attributes describing properties
@@ -4223,7 +4206,7 @@
@end table
@node Purity and side effects
- at subsubsection Purity and side effects
+ at subsection Purity and side effects
Note that procedures implemented in C using either
@samp{pragma import} or @samp{pragma c_code} must still be ``pure'',
@@ -4268,7 +4251,7 @@
of the program in unpredictable ways.
@node Including C headers
- at subsection Including C headers
+ at section Including C headers
Any macros, function prototypes, or other C declarations
that are used in @samp{c_code} pragmas must be included using a
@@ -4312,7 +4295,7 @@
automatically includes is subject to change.
@node Including C code
- at subsection Including C code
+ at section Including C code
Definitions of C functions or global variables may be
included using a declaration of the form
@@ -4333,7 +4316,7 @@
Such code is copied verbatim into the generated C file.
@node Calling Mercury code from C
- at subsection Calling Mercury code from C
+ at section Calling Mercury code from C
It is also possible to export Mercury procedures to C,
so that you can call Mercury code from C (or from
@@ -4395,7 +4378,7 @@
standard library module @samp{std_util}.
@node Linking with C object files
- at subsection Linking with C object files
+ at section Linking with C object files
A Mercury implementation should allow you to link with
object files or libraries that were produced by compiling C code.
@@ -4427,7 +4410,7 @@
Mercury users guide, and the @samp{man} pages for @samp{mmc} and @samp{ml}.
@node Passing data to and from C
- at subsection Passing data to and from C
+ at section Passing data to and from C
For each of the Mercury types @code{int}, @code{float}, @code{char},
and @code{string}, there is a C typedef for the corresponding type in C:
@@ -4468,7 +4451,7 @@
(@pxref{Memory management}).
@node Using C pointers
- at subsection Using C pointers
+ at section Using C pointers
The inbuilt Mercury type @code{c_pointer} can be used to pass C pointers
between C functions which are called from Mercury. For example:
@@ -4507,7 +4490,7 @@
@end example
@node Memory management
- at subsection Memory management
+ at section Memory management
Passing pointers to dynamically-allocated memory from Mercury to code
written in other languages, or vice versa, is in general
@@ -4545,7 +4528,7 @@
needed before we can formulate such an interface.
@node Trailing
- at subsection Trailing
+ at section Trailing
In certain compilation grades (see the ``Compilation model options''
section of the Mercury User's Guide), the University of Melbourne
@@ -4579,7 +4562,7 @@
@end menu
@node Choice points
- at subsubsection Choice points
+ at subsection Choice points
A ``choice point'' is a point in the computation to
which execution might backtrack. The ``current''
@@ -4599,7 +4582,7 @@
to a prior choice point.
@node Value trailing
- at subsubsection Value trailing
+ at subsection Value trailing
The simplest form of trailing is value trailing.
This allows you to trail updates to memory and have
@@ -4632,7 +4615,7 @@
@end table
@node Function trailing
- at subsubsection Function trailing
+ at subsection Function trailing
For more complicated uses of trailing, you can store the address
of a C function on the trail and have the Mercury runtime call your
@@ -4697,7 +4680,7 @@
then it should probably abort execution with an error message.
@node Delayed goals and floundering
- at subsubsection Delayed goals and floundering
+ at subsection Delayed goals and floundering
Another use for the function trail is check for floundering
in the presence of delayed goals.
@@ -4730,7 +4713,7 @@
an error message and then abort execution.
@node Avoiding redundant trailing
- at subsubsection Avoiding redundant trailing
+ at subsection Avoiding redundant trailing
If a mutable data structure is updated multiple times, and each update
is recorded on the trail using the functions described above, then
@@ -4814,7 +4797,7 @@
@c such as implementing your own exception handling.
@node Impurity
- at section Impurity declarations
+ at chapter Impurity declarations
In order to efficiently implement certain predicates, it is occasionally
necessary to venture outside pure logic programming. Other predicates
@@ -4845,17 +4828,17 @@
@menu
-* Purity levels:: Choosing the right level of purity
-* Impurity semantics:: What impure code means
-* Declaring impurity:: Declaring predicates impure
-* Impure calls:: Marking a call as impure
-* Promising purity:: Promising that a predicate is pure
-* Impurity Example:: A simple example using impurity
+* Purity levels:: Choosing the right level of purity.
+* Impurity semantics:: What impure code means.
+* Declaring impurity:: Declaring predicates impure.
+* Impure calls:: Marking a call as impure.
+* Promising purity:: Promising that a predicate is pure.
+* Impurity Example:: A simple example using impurity.
@end menu
@node Purity levels
- at subsection Choosing the right level of purity
+ at section Choosing the right level of purity
Mercury distinguishes three ``levels'' of purity:
@@ -4888,7 +4871,7 @@
@node Impurity semantics
- at subsection Semantics
+ at section Semantics
It is important to the proper operation of impure and semipure code, to
the flexibility of the compiler to optimize pure code, and to the
@@ -4929,7 +4912,7 @@
@node Declaring impurity
- at subsection Declaring predicate impurity
+ at section Declaring predicate impurity
A predicate is declared to be impure or semipure by preceding the word
@code{pred} in its @code{pred} declaration with @code{impure}
@@ -4951,7 +4934,7 @@
@node Impure calls
- at subsection Marking a call as impure
+ at section Marking a call as impure
If a predicate is impure or semipure, all calls to it must be preceded
with the word @code{impure} or @code{semipure}, respectively. Note
@@ -4969,7 +4952,7 @@
@node Promising purity
- at subsection Promising that a predicate is pure
+ at section Promising that a predicate is pure
Some predicates which call impure or semipure predicates are themselves
pure. In fact, the main purpose of the Mercury impurity system is to
@@ -4988,7 +4971,7 @@
@node Impurity Example
- at subsection An example using impurity
+ at section An example using impurity
The following example illustrates how a pure predicate may be
implemented using impure code. Note that this code is not reentrant,
@@ -5026,7 +5009,29 @@
).
@end example
+ at node Pragmas
+ at chapter Pragmas
+
+The pragma declarations described below are a standard part of the
+Mercury language, as are the pragmas for controlling the C interface
+(@pxref{C interface}) and impurity (@pxref{Impurity}).
+As an extension, implementations may also choose to support additional
+pragmas with implementation-dependent semantics
+(@pxref{Implementation-dependent extensions}).
+ at menu
+* Inlining:: Pragmas can be used to suggest or prevent
+ procedure inlining.
+* Type specialization:: Pragmas can be used to produce specialized
+ versions of polymorphic procedures.
+* Obsolescence:: Library developers can declare old versions
+ of predicates or functions to be obsolete.
+* Source file name:: The @samp{source_file} pragma and
+ @samp{#@var{line}} directives provide support
+ for preprocessors and other tools that
+ generate Mercury code.
+ at end menu
+
@node Inlining
@section Inlining
@@ -5210,17 +5215,12 @@
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.
+ at node Implementation-dependent extensions
+ at chapter Implementation-dependent extensions
The University of Melbourne Mercury implementation supports the following
-additional pragmas:
+extensions to the Mercury language:
@menu
* Fact tables:: Support for very large tables of facts.
@@ -5236,7 +5236,7 @@
@end menu
@node Fact tables
- at subsection Fact tables
+ at section Fact tables
Large tables of facts can be compiled using a different algorithm that
is more efficient and produces more efficient code.
@@ -5271,7 +5271,7 @@
arguments of types @samp{string}, @samp{int} or @samp{float}.
@node Tabled evaluation
- at subsection Tabled evaluation
+ at section Tabled evaluation
(Note: ``Tabled evaluation'' has no relation to the ``fact tables''
described above.)
@@ -5386,7 +5386,7 @@
@end cartouche
@node Termination analysis
- at subsection Termination analysis
+ at section Termination analysis
The compiler includes a termination analyser which can be used to prove
termination of predicates and functions. Details of the analysis is
@@ -5470,17 +5470,17 @@
@ifset aditi
@node Aditi deductive database interface
- at subsection Aditi deductive database interface
+ at section Aditi deductive database interface
@menu
* Aditi overview::
-* Aditi pragma declarations:: Controlling Aditi compilation
-* Aditi update syntax:: Changing the contents of Aditi relations
-* Aditi glossary:: Glossary of Aditi terms
+* Aditi pragma declarations:: Controlling Aditi compilation.
+* Aditi update syntax:: Changing the contents of Aditi relations.
+* Aditi glossary:: Glossary of Aditi terms.
@end menu
@node Aditi overview
- at subsubsection Aditi overview
+ at subsection Aditi overview
The University of Melbourne Mercury implementation includes support for
compiling Mercury predicates for bottom-up evaluation using the Aditi
@@ -5591,7 +5591,7 @@
@samp{string__length/2}.
@node Aditi pragma declarations
- at subsubsection Aditi pragma declarations
+ at subsection Aditi pragma declarations
The following pragma declarations control compilation of Aditi predicates.
@@ -5667,7 +5667,7 @@
numbers (argument numbers are counted from one).
@node Aditi update syntax
- at subsubsection Aditi update syntax
+ at subsection Aditi update syntax
The Melbourne Mercury compiler provides special syntax to specify updates
of Aditi base relations.
@@ -5675,8 +5675,6 @@
Note: Only error checking is implemented for Aditi updates --- no code is
generated yet.
- at c XXX texinfo doesn't have subsubsubsection.
- at ignore
@menu
* Aditi update notes::
* Insertion::
@@ -5684,10 +5682,9 @@
* Bulk insertion and deletion::
* Modification::
@end menu
- at end ignore
- at c @node Aditi update notes::
- at subsubheading Aditi update notes
+ at node Aditi update notes
+ at subsubsection Aditi update notes
All Aditi update goals have determinism @samp{det}.
@@ -5715,8 +5712,8 @@
:- pragma aditi(ancestor/3).
@end example
- at c @node Insertion
- at subsubheading Insertion
+ at node Insertion
+ at subsubsection Insertion
@example
aditi_insert(@var{PredName}(@var{Arg1}, @var{Arg2}, @dots{}), @var{DB0}, @var{DB}).
@@ -5761,8 +5758,8 @@
aditi_insert(f(_, 1) = 2, DB0, DB).
@end example
- at c @node Deletion
- at subsubheading Deletion
+ at node Deletion
+ at subsubsection Deletion
@example
aditi_delete((@var{PredName}(@var{Arg1}, @var{Arg2}, @dots{}) :- @var{Goal}), @var{DB0}, @var{DB}).
@@ -5874,8 +5871,8 @@
in the deletion goal would be parsed as an extra argument of the
@samp{aditi_delete} call, resulting in a syntax error.
- at c @node Bulk insertion and deletion
- at subsubheading Bulk insertion and deletion
+ at node Bulk insertion and deletion
+ at subsubsection Bulk insertion and deletion
@example
aditi_bulk_insert(@var{PredOrFunc} @var{Name}/@var{Arity}, @var{Closure}, @var{DB0}, @var{DB}).
@@ -5947,8 +5944,8 @@
Its inst is @w{@samp{pred(aditi_ui, out, out) is nondet}},
as for a normal lambda expression.
- at c @node Modification
- at subsubheading Modification
+ at node Modification
+ at subsubsection Modification
@example
aditi_modify(
@@ -6076,7 +6073,7 @@
of the @samp{aditi_modify} call, resulting in a syntax error.
@node Aditi glossary
- at subsubsection Aditi glossary
+ at subsection Aditi glossary
@table @asis
Index: transition_guide.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/transition_guide.texi,v
retrieving revision 1.28
diff -u -u -r1.28 transition_guide.texi
--- transition_guide.texi 1999/07/13 08:54:37 1.28
+++ transition_guide.texi 1999/08/04 02:35:52
@@ -68,15 +68,15 @@
translating Prolog programs into Mercury.
@menu
-* Introduction:: Introduction
-* Syntax:: Syntax
-* IO:: Input and output
-* FailLoops:: Failure driven loops, @code{assert} and @code{retract}
-* Commits:: Cuts
-* Accumulators:: Accumulators and difference lists
-* Determinism:: Determinism
-* All-solutions:: All-solutions predicates: @code{findall} and @code{setof}
- at c * Problems:: Common Problems
+* Introduction:: Introduction.
+* Syntax:: Syntax.
+* IO:: Input and output.
+* FailLoops:: Failure driven loops, @code{assert} and @code{retract}.
+* Commits:: Cuts.
+* Accumulators:: Accumulators and difference lists.
+* Determinism:: Determinism.
+* All-solutions:: All-solutions predicates: @code{findall} and @code{setof}.
+ at c * Problems:: Common Problems.
@end menu
@end ifinfo
Index: user_guide.texi
===================================================================
RCS file: /home/staff/zs/imp/mercury/doc/user_guide.texi,v
retrieving revision 1.181
diff -u -u -r1.181 user_guide.texi
--- user_guide.texi 1999/07/26 02:52:39 1.181
+++ user_guide.texi 1999/08/04 02:41:00
@@ -72,21 +72,21 @@
how to build and debug Mercury programs.
@menu
-* Introduction:: General overview
-* Filenames:: File naming conventions
-* Using mmc:: Compiling and linking programs with the Mercury compiler
-* Running:: Execution of programs built with the Mercury compiler
-* Using Mmake:: ``Mercury Make'', a tool for building Mercury programs
-* Libraries:: Creating and using libraries of Mercury modules
-* Debugging:: The Mercury debugger @samp{mdb}
+* Introduction:: General overview.
+* Filenames:: File naming conventions.
+* Using mmc:: Compiling and linking programs with the Mercury compiler.
+* Running:: Execution of programs built with the Mercury compiler.
+* Using Mmake:: ``Mercury Make'', a tool for building Mercury programs.
+* Libraries:: Creating and using libraries of Mercury modules.
+* Debugging:: The Mercury debugger @samp{mdb}.
* Profiling:: The Mercury profiler @samp{mprof}, a tool for analyzing
- program performance
-* Invocation:: List of options for the Mercury compiler
-* Environment:: Environment variables used by the compiler and utilities
-* C compilers:: How to use a C compiler other than GNU C
+ program performance.
+* Invocation:: List of options for the Mercury compiler.
+* Environment:: Environment variables used by the compiler and utilities.
+* C compilers:: How to use a C compiler other than GNU C.
@ifset aditi
* Using Aditi:: Executing Mercury predicates using the Aditi
- deductive database
+ deductive database.
@end ifset
@c XXX I'd like to put the Aditi section below the Using libraries section
@c in the menu but texinfo doesn't seem to like `@ifset's in menus.
@@ -1954,9 +1954,9 @@
@itemize @bullet
@item
-the ``Aditi deductive database interface'' section in
-Mercury Language Reference Manual (listed under
-``Implementation dependent pragmas'' in the ``Pragmas'' chapter)
+the ``Aditi deductive database interface'' section of the
+``Implementation-dependent extensions'' chapter in the
+Mercury Language Reference Manual
@item
the Aditi Reference Manual (doesn't exist yet) @c XXX
@item
@@ -2802,8 +2802,8 @@
@section Termination analysis options
For detailed explanations, see the ``Termination analysis'' section
-in Mercury Language Reference Manual. (It is listed under
-``Implementation dependent pragmas'' in the ``Pragmas'' chapter.)
+of the ``Implementation-dependent extensions'' chapter in the Mercury
+Language Reference Manual.
@table @code
@item --enable-term
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to: mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions: mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------
More information about the developers
mailing list