[m-rev.] for review: transparent sub-module documentation

[Peter Ross]

Hi,

Here is the documentation for transparent sub-modules.
I will not commit this until I have finished the implementation but have
I misinterpreted anything.

===================================================================


Estimated hours taken: 0.25
Branches: main

reference_manual.texi:
    Document transparent sub-modules.


Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.228
diff -u -r1.228 reference_manual.texi
--- reference_manual.texi	22 Nov 2001 19:19:54 -0000	1.228
+++ reference_manual.texi	28 Nov 2001 11:47:49 -0000
@@ -487,8 +487,10 @@
 --->              xfy       1179
 type              fx        1180
 end_module        fx        1199
+end_transparent_module fx        1199
 import_module     fx        1199
 include_module    fx        1199
+include_transparent_module fx        1199
 instance          fx        1199
 inst              fx        1199
 mode              fx        1199
@@ -497,6 +499,7 @@
 promise           fx        1199
 rule              fx        1199
 typeclass         fx        1199
+transparent_module fx        1199
 use_module        fx        1199
 -->               xfx       1200
 :-                xfx       1200
@@ -543,6 +546,9 @@
 :- use_module
 :- include_module
 :- end_module
+:- transparent_module
+:- include_transparent_module
+:- end_transparent_module
 @end example
 
 The @samp{type}, @samp{pred} and @samp{func} declarations are used for the
@@ -3650,10 +3656,15 @@
 @section Sub-modules
 
 As mentioned above, modules may contain sub-modules.
-There are two kinds of sub-modules, called nested sub-modules
-and separate sub-modules; the difference is that nested sub-modules
+A sub-module can be either nested or separate:
+the difference is that nested sub-modules
 are defined in the same source file as the containing module,
 whereas separate sub-modules are defined in separate source files.
+A sub-module can also either be transparent or opaque:
+the difference is that any visible transparent sub-modules
+are also imported when the parent module is imported,
+whereas an opaque sub-module declarations are only available if the
+sub-module is explicitly imported.
 Implementations should support separate compilation of separate sub-modules.
 
 A module may not contain more than one sub-module with the same name.
@@ -3668,13 +3679,17 @@
 @node Nested sub-modules
 @subsection Nested sub-modules
 
-Nested sub-modules within a module are delimited by
+Opaque nested sub-modules within a module are delimited by
 matching @samp{:- module} and @samp{:- end_module} declarations.
 (Note that @samp{:- end_module} for nested sub-modules 
 are mandatory, not optional, even if the nested sub-module
 is the last thing in the source file.
 Also note that the module name in a @samp{:- module} or @samp{:- end_module}
 declaration need not be fully-qualified.)
+A transparent nested sub-module is declared using
+ at samp{:- transparent_module} and @samp{end_transparent_module},
+otherwise the rules are identical to those of opaque sub-modules.
+
 The sequence of items thus delimited is known as a sub-module item sequence.
 
 The interface and implementation parts of a nested sub-module
@@ -3699,10 +3714,13 @@
 @node Separate sub-modules
 @subsection Separate sub-modules
 
-Separate sub-modules are declared using
+Opaque separate sub-modules are declared using
 @samp{:- include_module @var{Modules}} declarations.
 Each @samp{:- include_module} declaration specifies a comma-separated list
 of sub-modules.
+Transparent separate sub-modules use the
+ at samp{:- include_transparent_module} declaration instead,
+otherwise the rules are identical to those of opaque sub-modules.
 
 @example
 :- include_module @var{Module1}, @var{Module2}, @dots{}, @var{ModuleN}.

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