[m-rev.] diff: foreign interface documentation fixes

[Fergus Henderson]

Estimated hours taken: 2
Branches: main

Improve the documentation of the foreign language interface.

doc/reference_manual.texi:
	Document the semantics of "pragma foreign_decl" and "pragma
	foreign_code", rather than leaving them implementation-defined.

	In the "Foreign Language Interface" chapter, document that all
	Mercury implementations should support the C interface.
	This fixes an inconsistency between the F.L.I. chapter,
	which said that it was implementation-specific,
	and the C interface chapter, which said that all
	Mercury implementations should support linking with C code.

doc/reference_manual.texi:
doc/user_guide.texi:
	Various other minor improvements: fix typos, improve wording, etc.

Workspace: /mnt/mars/home/mars/fjh/ws1/mercury
Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.209
diff -u -d -r1.209 reference_manual.texi
--- doc/reference_manual.texi	2001/07/18 10:21:01	1.209
+++ doc/reference_manual.texi	2001/07/23 16:38:10
@@ -4236,7 +4236,8 @@
 (Note, however, that the standard library includes some quite powerful
 procedures such as `io__write' which can be useful in this context.)
 
-A non-variable type is considered @emph{more general} than an
+A non-variable type (i.e. a type which is not a type variable)
+is considered @emph{more general} than an
 existentially quantified type variable.  Type inference will therefore
 never infer an existentially quantified type for a predicate or
 function unless that predicate or function calls (directly or indirectly)
@@ -4685,10 +4686,10 @@
 				       written in a different
 				       programming language.
 * Adding foreign declarations::        How to add declarations of
-  				       enities in other programming
+  				       entities in other programming
 				       languages.
-* Adding foreign definitions::         How to add definitions of entities
-  				       enities in other programming
+* Adding foreign definitions::         How to add definitions of
+  				       entities in other programming
 				       languages.
 * Language specific bindings::         Information specific to each
   				       foreign language.
@@ -4700,8 +4701,8 @@
 See the @pxref{C interface} chapter for the existing, supported C
 interface for Mercury.
 
-The syntax, documentation, behaviour and semantics described in this
-chapter are subject to change without notice.
+The syntax, documentation, behaviour and semantics of the constructs
+described in this chapter are subject to change without notice.
 
 @node Calling foreign code from Mercury
 @section Calling foreign code from Mercury
@@ -4740,7 +4741,7 @@
 language code by this implementation. 
 See the ``Foreign Language Interface'' chapter of the
 Mercury User's Guide, for more information about how the implementation
-selects the approriate @samp{foreign_proc} to use.
+selects the appropriate @samp{foreign_proc} to use.
 
 The foreign code fragment may refer to the specified variables
 (@var{Var1}, @var{Var2}, @dots{}, and @var{Var})
@@ -4757,11 +4758,11 @@
 in the ``Foreign Language Interface'' chapter of the
 Mercury User's Guide.
 
-If there is one @code{pragma foreign_proc} declaration for any
+If there is a @code{pragma foreign_proc} declaration for any
 mode of a predicate or function, then there must be either a mode
-specific clause, or a @code{pragma foreign_proc} 
+specific clause or a @code{pragma foreign_proc} 
 @c or @code{pragma import} 
-declaration for every mode of the predicate or function.
+declaration for every mode of that predicate or function.
 
 Here's an example of code using @samp{pragma foreign_proc}:
 The following code defines a Mercury function
@@ -4851,15 +4852,24 @@
 @section Adding foreign declarations
 
 Foreign language declarations (such as type declarations, header file
-inclusions or macro defintions) can included in the Mercury source file as
+inclusions or macro definitions) can included in the Mercury source file as
 part of a @samp{foreign_decl} declaration of the form
 
 @example
 :- pragma foreign_decl("@var{Lang}", @var{DeclCode}).
 @end example
 
-The semantics of @samp{foreign_decl} depend upon the implementation and
-foreign language used. 
+This declaration will have effects equivalent to including the specified
+ at var{DeclCode} in an automatically-generated source file of the specified
+programming language, in a place appropriate for declarations,
+and linking that source file with the Mercury program
+(after having compiled it with a compiler for the specified programming
+language, if appropriate).
+
+Entities declared in @samp{pragma foreign_decl} declarations should be
+visible in @samp{pragma foreign_code} and @samp{pragma foreign_proc}
+declarations that specify the same foreign language and occur in in the
+same Mercury module.
 
 @node Adding foreign definitions
 @section Adding foreign definitions
@@ -4871,35 +4881,45 @@
 :- pragma foreign_code("@var{Lang}", @var{Code}).
 @end example
 
-The semantics of @samp{foreign_code} depend upon the implementation and
-foreign language used. 
+This declaration will have effects equivalent to including the specified
+ at var{DeclCode} in an automatically-generated source file of the specified
+programming language, in a place appropriate for definitions,
+and linking that source file with the Mercury program
+(after having compiled it with a compiler for the specified programming
+language, if appropriate).
+
+Entities declared in @samp{pragma foreign_code} declarations should be
+visible in @samp{pragma foreign_proc} declarations that specify the same
+foreign language and occur in in the same Mercury module.
 
 @c -----------------------------------------------------------------------
 
 @node Language specific bindings
 @section Language specific bindings
 
-Note that these bindings are specific to the Melbourne Mercury compiler,
-other compilers may choose to implement a different set of bindings.
+All Mercury implementations should support interfacing with C.
+The set of other languages supported is implementation-defined.
 
+The University of Melbourne Mercury implementation supports
+interfacing with the following languages:
+
 @table @asis
 
+ at c Please keep this table in alphabetical order
+
 @item @samp{C}
 Use the string "C" to set the foreign language to C.
 
- at item @samp{Managed C++}
-Use the string "MC++" to set the foreign language to Managed C++.
-
 @item @samp{C#}
 Use the string "C#" to set the foreign language to C#.
 
 @item @samp{IL}
 Use the string "IL" to set the foreign language to IL.
 
- at end table
+ at item @samp{Managed C++}
+Use the string "MC++" to set the foreign language to Managed C++.
 
-Each of these foreign language interfaces requires that an appropriate
-compiler be installed.
+ at end table
 
 
 @node C interface
@@ -5523,6 +5543,11 @@
 and to treat each such type as an abstract data type.  This is good style
 and it will also minimize any compatibility problems if and when we do change
 this.)
+
+ at c For the Managed C++ interface, the types are mapped slightly differently:
+ at c Mercury variables which are polymorphically typed
+ at c have type @samp{MR_Box} rather than @samp{MR_Word}.
+ at c XXX We should document the Managed C++ interface somewhere.
 
 Mercury lists can be manipulated by C code using the following macros,
 which are defined by the Mercury implementation.
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.262
diff -u -d -r1.262 user_guide.texi
--- doc/user_guide.texi	2001/07/18 10:21:03	1.262
+++ doc/user_guide.texi	2001/07/23 15:57:32
@@ -593,6 +593,8 @@
 
 @end table
 
+ at cindex Variables, Mmake
+ at cindex Mmake variables
 The variables used by the builtin rules (and their default values) are
 defined in the file @file{@var{prefix}/lib/mercury/mmake/Mmake.vars}, however
 these may be overridden by user @samp{Mmake} files.  Some of the more
@@ -640,8 +642,8 @@
 
 @item MS_CL_NOASM 
 @vindex MS_CL_NOASM
-The option to control whether the Microsoft command line C++ compile
-will generate assemblies from managed C++ files.  Set to
+The option to control whether the Microsoft command line C++ compiler
+will generate .NET assemblies from Managed C++ files.  Set to
 @samp{:noAssembly} to turn off assembly generation, leave empty to turn
 on assembly generation.  The default is to leave this variable empty.
 
@@ -5724,8 +5726,9 @@
 Only available on backends that compile to C or assembler.
 
 @item @samp{Managed C++}
-Managed Extensions for C++ provides support for writing .NET components
-in C++, by adding extra keywords and syntax.
+Managed Extensions for C++ is a language based on C++ that
+provide support for writing .NET components, by adding extra
+keywords and syntax.
 
 This is the default foreign language on all backends which compile to IL.
 In the current implementation, this is only available on backends that

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------