[m-rev.] for review: improve sub-modules documentation

[Simon Taylor]

Estimated hours taken: 0.25
Branches: main, release

doc/reference_manual.texi:
	Improve the documentation of sub-modules.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.224
diff -u -u -r1.224 reference_manual.texi
--- reference_manual.texi	12 Nov 2001 11:08:13 -0000	1.224
+++ reference_manual.texi	15 Nov 2001 06:26:12 -0000
@@ -3721,14 +3721,30 @@
 Mercury implementation requires the module name in the @samp{:- module}
 declaration for that module to be fully qualified.)
 
-If an @samp{:- include_module} declaration occurs in the interface
-section of a module, then only the declarations (interfaces) of the sub-modules
-are included in the parent module's interface; the definitions
-(implementations) of the sub-modules are considered to be implicitly
-part of the parent module's implementation.
+The semantics of separate sub-modules are identical to those of nested
+sub-modules.
 
-Apart from that, the semantics of separate sub-modules are
-identical to those of nested sub-modules.
+ at example
+:- module x.
+:- interface.
+:- include_module y.
+:- end_module x.
+ at end example
+
+is equivalent to
+
+ at example
+:- module x.
+:- interface.
+    :- module y.
+    % interface section of module @samp{y}
+    :- end_module y.
+:- implementation.
+    :- module y.
+    % implementation section of module @samp{y}
+    :- end_module y.
+:- end_module x.
+ at end example
 
 @node Visibility rules
 @subsection Visibility rules
@@ -3739,10 +3755,18 @@
 Similarly, declarations in the interfaces of any modules imported using an
 @samp{:- import_module} or a @samp{:- use_module} in the parent module
 are visible in the parent's sub-modules, including indirect sub-modules.
-However, declarations in a child module are not visible in the parent
-module or in "sibling" modules (other children of the same parent)
-unless the child is explicitly imported using an @samp{:- import_module}
-or @samp{:- use_module} declaration. 
+
+Declarations in a child module are not visible in the parent module,
+or in "sibling" modules (other children of the same parent), or in
+other unrelated modules unless the child is explicitly imported using
+an @samp{:- import_module} or @samp{:- use_module} declaration. It
+is an error to import a module without importing all of its parent
+modules.
+
+A sub-module for which the @samp{:- module} or @samp{:- include_module}
+declaration occurs only in the implementation section of the parent module
+is an implementation sub-module. It may only be imported or used by its
+parent module.
 
 Note that as mentioned previously, all @samp{:- import_module} and
 @samp{:- use_module} declarations must use fully-qualified module
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------