diff: improve documentation about sub-module file names

[Fergus Henderson]

Estimated hours taken: 0.5

doc/user_guide.texi:
doc/reference_manual.texi:
	Update/clarify the documentation about the rules for naming
	source files when using separate sub-modules.

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.117
diff -u -r1.117 reference_manual.texi
--- reference_manual.texi	1999/01/30 04:10:49	1.117
+++ reference_manual.texi	1999/01/31 11:41:27
@@ -2706,9 +2706,10 @@
 Each of the named sub-modules in an @samp{:- include_module} declaration
 must be defined in a separate source file.
 The mapping between module names and source file names is
-implementation-defined.  (The University of Melbourne Mercury
-implementation requires a module named @samp{foo:bar:baz} to be
-located in source file @file{foo.bar.baz.m}.)
+implementation-defined.  (For a module named @samp{foo:bar:baz},
+The University of Melbourne Mercury implementation requires the source
+to be located in a file named @file{foo.bar.baz.m}, @file{bar.baz.m},
+or @file{baz.m}.) 
 The separate source file must contain the declaration (interface)
 and definition (implementation) of the sub-module.
 It must start with a @samp{:- module} declaration
@@ -2717,7 +2718,11 @@
 implementation sections, and it may optionally end with a @samp{:- end_module}
 declaration.  (Note: the module names in the @samp{:- module},
 @samp{:- end_module}, and @samp{:- include_module} declarations
-need not be fully-qualified.)
+need not be fully-qualified.  However,
+if the file name used for a particular module does
+not include all the module qualifiers, then the University of Melbourne
+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
Index: doc/user_guide.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/user_guide.texi,v
retrieving revision 1.155
diff -u -r1.155 user_guide.texi
--- user_guide.texi	1998/12/17 13:36:46	1.155
+++ user_guide.texi	1999/01/31 11:44:47
@@ -187,9 +187,14 @@
 have a similar meaning to that in other Unix compilers.
 
 Arguments to @samp{mmc} may be either file names (ending in @samp{.m}),
-or module names.  For a module name such as @samp{foo.bar.baz},
+or module names, with @samp{.} (rather than @samp{__} or @samp{:})
+as the module qualifier.  For a module name such as @samp{foo.bar.baz},
 the compiler will look for the source in files @file{foo.bar.baz.m},
 @file{bar.baz.m}, and @file{baz.m}, in that order.
+Note that if the file name does not include all the module
+qualifiers (e.g. if it is @file{bar.baz.m} or @file{baz.m}
+rather than @file{foo.bar.baz.m}), then the module name in the
+ at samp{:- module} declaration for that module must be fully qualified.
 
 To compile a program which consists of just a single source file,
 use the command
@@ -2196,7 +2201,8 @@
 
 Arguments can be either module names or file names.
 Arguments ending in @samp{.m} are assumed to be file names,
-while other arguments are assumed to be module names.
+while other arguments are assumed to be module names, with
+ at samp{.} (rather than @samp{__} or @samp{:}) as module qualifier.
 If you specify a module name such as @samp{foo.bar.baz},
 the compiler will look for the source in files @file{foo.bar.baz.m},
 @file{bar.baz.m}, and @file{baz.m}, in that order.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "Binaries may die
WWW: <http://www.cs.mu.oz.au/~fjh>  |   but source code lives forever"
PGP: finger fjh at 128.250.37.3        |     -- leaked Microsoft memo.