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

[Simon Taylor]

On 28-Nov-2001, Peter Ross <peter.ross at miscrit.be> wrote:
> Estimated hours taken: 0.25
> Branches: main
> 
> reference_manual.texi:
>     Document transparent sub-modules.
> 
>  @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:

s/can be/is/

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

It's probably clearer if these definitions are split out into
separate sentences:

	Nested sub-modules are defined in the same source file
	as the containing module,
	Separate sub-modules are defined in separate source files.

> +A sub-module can also either be transparent or opaque:

s/can also either be/is either/

Separate sentences defining transparent and opaque sub-modules would
probably be clearer.

> +the difference is that any visible transparent sub-modules
> +are also imported when the parent module is imported,

Visible from where?
This also doesn't match the final proposal -- transparent sub-modules
are imported as if by a `:- use_module' declaration.

I suggest:
	A transparent sub-module is implicitly imported as if by a 
	a @samp{:- use_module} declaration whenever the parent
	module is imported

You haven't updated the "Visibility rules" section.

> +whereas an opaque sub-module declarations are only available if the
> +sub-module is explicitly imported.

I suggest:
	An opaque sub-module must always be explicitly imported.

It would also be a good idea to state that most sub-modules
should be opaque, and give some hints on when transparent
sub-modules should be used.

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

I suggest:
	Transparent nested sub-modules are delimited by
	@samp{:- transparent_module} and @samp{:- end_transparent_module},
	declarations, but are otherwise syntactically identical to
	opaque sub-modules.

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

I suggest:
	Transparent separate sub-modules are declared using
	@samp{:- include_transparent_module @var{Modules}} declarations.
	Each @samp{:- include_module} or @samp{:- include_transparent_module}
	declaration specifies a comma-separated list of sub-modules.

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