updates for version 13.0.0 completed

annotations/yo/modules.yo

@@ -1,3 +1,5 @@
+NOUSERMACRO(file)
+
 includefile(modules/intro.yo)
 
 sect(An initial, complete module)
@@ -39,7 +41,6 @@ COMMENT(
     subsect(Using a module having partitions)
     includefile(modules/partmain.yo)
 
-COMMENT(NEXT)
 lsect(MODMAPPER)(Module mapping)
 includefile(modules/modmap.yo)
 

annotations/yo/modules/libraries.yo

@@ -1,22 +1,22 @@
 Software libraries are traditionally constructed using header files. For
-example, the compiler's development files are found in, e.g.,
+example, the compiler's development header files are found in
 tt(/usr/include/c++/14.) Currently, only these header files are installed, and
 not their corresponding module-compiled tt(.gcm) equivalents. Section
 ref(MODHDR) covered how to construct the module-compiled versions of those
-system header files. Once the system header files are compiled and available
-next to their traditional header files (so tt(iostream) and tt(iostream.gcm)
-are both available in the same directory) then module-aware source files can
-import those header files (i.e., tt(import <iostream>;)) instead of including
-them (as in tt(#include <iostream>)).
+system header files. Once the system header files were compiled and made
+available next to their traditional header files (so tt(iostream) and
+tt(iostream.gcm) are both available in the same directory) then module-aware
+source files can import those header files (i.e., tt(import <iostream>;))
+instead of including them (as in tt(#include <iostream>)).
 
 When constructing a library whose header files are available in a
 sub-directory of the standard include directory (like the headers of the
 tt(bobcat) library, cf. section ref(IOSTREAM)), then the header files of such
-libraries are also traditionally made available using tt(#include) directives
-like tt(#include <bobcat/exception>). To prepare the headers of such libraries
-for use by module-aware source files is easy: simply construct their
-module-compiled versions like the the module-compiled versions of the standard
-header files were constructed:
+libraries are traditionally also available using tt(#include) directives like
+tt(#include <bobcat/exception>). To prepare the headers of such libraries for
+use by module-aware source files is easy: simply construct their
+module-compiled versions like the way the module-compiled versions of the
+standard header files were constructed:
     itemization(
     it() tt(cd) to the directory containing the library's header files;
     it() to construct the module-compiled version of a header `tt(libclass)'
@@ -29,7 +29,7 @@ header files were constructed:
     )
 
 Since the system header files and their module-aware equivalents are located
-in the standard system files directories, all below tt(/usr), the compiler
+in the standard system files directories (all below tt(/usr)), the compiler
 will look for module-aware tt(.gcm) files either in the project's
 tt(gcm.cache) sub-directory or it will look for those files in the standard
 system directories, starting its search in the tt(gcm.cache)
@@ -72,7 +72,7 @@ actually required can be answered by bf(icmodmap)(1): it offers the
 tt(--dependencies) option showing which modules are required by each of the
 library's (or any project's, for that matter) modules. When executing
 `tt(icmodmap -d .)' in the library's base directory it shows:
-        verb(    External: e
+        verb(    External:e
     Module1: External:e
     Module2: External:e Module1 
     Module3: External:e Module1  Module2)

annotations/yo/modules/locallib.yo

@@ -1,18 +1,18 @@
 In addition to libraries whose header files are located in (sub-directories
 of) the standard system include directories it's of course also possible that
-a local library is defined by a user. That library could very well be a
-traditionally developed library, using traditional header files. 
+some a local library was constructed. That library could very well
+traditionally have been developed, using traditional header files.
 
-To construct the module-aware versions of that library's header file the
+To construct the module-aware versions of that library's header files the
 procedure described in the previous section can be used. However, since the
 header files of a local library aren't located in the standard system files
 directories, they must be made available in the tt(gcm.cache) sub-directory of
 the project using them. 
 
-Copying the headers and their module-compiled versions to the tt(gcm.cache)
-sub-directory is of course possible, but a simpler alternative exists which
-can be used by multiple module-aware projects which may all depend on the
-local library.
+It is possible to copy the headers and their module-compiled versions to the
+tt(gcm.cache) sub-directory, but a simpler alternative
+exists which can be used by multiple module-aware projects which may all
+depend on the local library.
 
 First some preparatory steps are performed (only once):
     itemization(

annotations/yo/modules/modmap.yo

@@ -37,27 +37,26 @@ source files of the modules can be compiled, even if a source file imports a
 module whose tt(module.cc) file had to be compiled after the tt(module.cc)
 file of the module to which the source file belongs.
 
-COMMENT(NEXT)
-
-This two-step process (first the modules' tt(module.cc) files in the right
+this two-step process (first the modules' tt(module.cc) files in the right
 order and then the remaining source files) quickly becomes a challenge. To
-fight that challenge a emi(module mapper) is a useful tool. Module mappers
+fight that challenge a emi(module mapper) is commonly used. Module mappers
 inspect the modules of a project, building their dependency tree. The module
 mapper bf(icmodmap)(1), a utility program of the 
-bf(icmake)(1) project, can be used as a basic module mapper.
+bf(icmake)(1) project, can be used as a module mapper.
 
-bf(Icmodmap) expect projects using modules to be organized as follows:
+bf(Icmodmap) expect projects using modules as follows:
     itemization(
     it() The project's top-level directory contains a file tt(CLASSES), where
-        each line (ignoring (bf(C++)) comment) specifies the name of a
+        each line (ignoring bf(C++) comment) specifies the name of a
         sub-directory implementing one of the project's
-        components. Alternatively a (subset) of the directory's
-        sub-directories can be specified. Each sub-directory can define a
-        module, a module partition, a class (not part of a module, but maybe
-        using modules), or global-level functions (also maybe using modules);
+        components. Alternatively, not using tt(CLASSES), a (subset) of the
+        directory's sub-directories can be specified. Each sub-directory can
+        define a module, a module partition, a class (not part of a module,
+        but maybe using modules), or global-level functions (also maybe using
+        modules);
     it() If the project defines a program, the project's top-level directory
-        contains source files (like tt(main.cc)) defining the tt(main)
-        function.  The top-level directory does not define a module, but its
+        contains source files (like tt(main.cc) defining the tt(main)
+        function).  The top-level directory does not define a module, but its
         sources may use modules;
     it() Sub-directories defining modules or partitions by default contain a
         file tt(module.cc), defining the module's name and its interface
@@ -68,26 +67,26 @@ bf(Icmodmap) expect projects using modules to be organized as follows:
     )
 
 bf(Icmodmap)(1) inspects each specified sub-directory. If it contains the file
-tt(module.cc) (or its alternative name), then that file (having the
-following structure) is inspected:
+tt(module.cc) (or its alternative name), then that file is inspected:
     itemization(
-    it() its first non-empty line: defines the name of the module or partition;
+    it() its first non-empty line defines the name of the module or partition;
     it() tt(import) lines can specify system headers, modules and/or
         partitions.
     )
 
 Once all tt(module.cc) files were successfully inspected bf(icmodmap)(1)
-has determined the module dependencies and the interface files are compiled in
-the required order. Each compiled interface file starts with an
-ordering number which is equal to the line number in the tt(CLASSES) file
-(or sub-directory order or the inspected sub-directories),
-e.g., tt(1interface.o, 2interface.o,) etc.
+determines the module dependencies, and if there are no circular dependencies
+the interface files are compiled in the required order. Each compiled
+interface file name will begin with an ordering number which is equal to the
+line number in the tt(CLASSES) file (or sub-directory order number of the
+inspected sub-directories), e.g., tt(1module.o, 2module.o,) etc.
 
 When bf(icmodmap)(1) successfully returns then all module defining interface
-files were successfully compiled; the project's top-level directory will
-contain a sub-directory tt(gcm.cache) containing the tt(.gcm) files of all
+files were successfully compiled, and the project's top-level directory
+contains a sub-directory tt(gcm.cache) containing the tt(.gcm) files of all
 modules and partitions; and each inspected sub-directory has received a
-soft-link tt(gcm.cache) to the top-level tt(gcm.cache) sub-directory. Next,
+soft-link tt(gcm.cache) to the top-level tt(gcm.cache) sub-directory, allowing
+the files in each sub-directory to import the project's modules. Next,
 the source files in the directories listed in the tt(CLASSES) file (and
 possibly the source file(s) in the top-level diretory itself) can be compiled
 as usual, e.g., using a build-utility.