[PATCH] Modula-2: fix documentation layout

[PATCH] Modula-2: fix documentation layout

[Eric Botcazou]

[-- Attachment #1: Type: text/plain, Size: 620 bytes --]

Hi,

the Modula-2 documentation is rejected by older versions of Makeinfo because 
the web of @node markers is fairly broken, apparently some subsections were 
moved around, most notably between the Overview and Using sections, and the 
@node markers were not (properly) adjusted.

This patch allows me to build it with these older versions, as well as with 
modern versions.  OK for mainline?


2023-01-09  Eric Botcazou  <ebotcazou@adacore.com>

	* doc/gm2.texi (Overview): Fix @node markers.
	(Using): Likewise.  Remove subsections that were moved to
	Overview from the menu and move others around.

-- 
Eric Botcazou

[-- Attachment #2: p.diff --]
[-- Type: text/x-patch, Size: 16863 bytes --]

diff --git a/gcc/doc/gm2.texi b/gcc/doc/gm2.texi
index 18cb798c6cd..35e0f5ef622 100644
--- a/gcc/doc/gm2.texi
+++ b/gcc/doc/gm2.texi
@@ -89,7 +89,7 @@ Boston, MA 02110-1301, USA@*
 * Features::              GNU Modula-2 Features
 @end menu
 
-@node What is GNU Modula-2, Why use GNU Modula-2, , Using
+@node What is GNU Modula-2, Why use GNU Modula-2, , Overview
 @section What is GNU Modula-2
 
 GNU Modula-2 is a @uref{http://gcc.gnu.org/frontends.html, front end}
@@ -115,7 +115,7 @@ technology - programming languages - part 1: Modula-2 Language,
 ISO/IEC 10514-1 (1996)'
 }
 
-@node Why use GNU Modula-2, Release map, What is GNU Modula-2, Using
+@node Why use GNU Modula-2, Development, What is GNU Modula-2, Overview
 @section Why use GNU Modula-2
 
 There are a number of advantages of using GNU Modula-2 rather than
@@ -149,25 +149,13 @@ directory for a sub directory @code{foo} containing the library
 contents.  The library module search path is altered accordingly
 for compile and link.
 
-@node Release map, Development, Why use GNU Modula-2, Using
-@section Release map
-
-GNU Modula-2 is now part of GCC and therefore will adopt the GCC
-release schedule.  It is intended that GNU Modula-2 implement more of
-the GCC builtins (vararg access) and GCC features.
-
-There is an intention to implement the ISO generics and the M2R10
-dialect of Modula-2.  It will also implement all language changes.  If
-you wish to see something different please email
-@email{gm2@@nongnu.org} with your ideas.
-
-@node Development, Features, Release map, Using
+@node Development, Features, Why use GNU Modula-2, Overview
 @section How to get source code using git
 
 GNU Modula-2 is now in the @url{https://gcc.gnu.org/git.html, GCC git
 tree}.
 
-@node Features, Documentation, Development, Using
+@node Features, , Development, Overview
 @section GNU Modula-2 Features
 
 @itemize @bullet
@@ -230,99 +218,7 @@ such as the AVR and the ARM).
 
 @end itemize
 
-@node Documentation, Regression tests, Features, Using
-@section Documentation
-
-The GNU Modula-2 documentation is available on line
-@url{https://www.nongnu.org/gm2/homepage.html,at the gm2 homepage}
-or in the pdf, info, html file format.
-
-@node Regression tests, Limitations, Documentation, Using
-@section Regression tests for gm2 in the repository
-
-The regression testsuite can be run from the gcc build directory:
-
-@example
-$ cd build-gcc
-$ make check -j 24
-@end example
-
-which runs the complete testsuite for all compilers using 24 parallel
-invocations of the compiler.  Individual language testsuites can be
-run by specifying the language, for example the Modula-2 testsuite can
-be run using:
-
-@example
-$ cd build-gcc
-$ make check-m2 -j 24
-@end example
-
-Finally the results of the testsuite can be emailed to the
-@url{https://gcc.gnu.org/lists.html, gcc-testresults} list using the
-@file{test_summary} script found in the gcc source tree:
-
-@example
-$ @samp{directory to the sources}/contrib/test_summary
-@end example
-
-@node Limitations, Objectives, Regression tests, Using
-@section Limitations
-
-Logitech compatibility library is incomplete.  The principle modules
-for this platform exist however for a comprehensive list of completed
-modules please check the documentation
-@url{gm2.html}.
-
-@node Objectives, FAQ, , Using
-@section Objectives
-
-@itemize @bullet
-
-@item
-The intention of GNU Modula-2 is to provide a production Modula-2
-front end to GCC.
-
-@item
-It should support all Niklaus Wirth PIM Dialects [234] and also ISO
-Modula-2 including a re-implementation of all the ISO modules.
-
-@item
-There should be an easy interface to C.
-
-@item
-Exploit the features of GCC.
-
-@item
-Listen to the requests of the users.
-@end itemize
-
-@node FAQ, Community, Objectives, Using
-@section FAQ
-
-@subsection Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism?
-
-The C++ mechanism is tried and tested, it also provides GNU Modula-2
-with the ability to link with C++ modules and via swig it can raise
-Python exceptions.
-
-@node Community, Other languages, FAQ, Using
-@section Community
-
-You can subscribe to the GNU Modula-2 mailing by sending an
-email to:
-@email{gm2-subscribe@@nongnu.org}
-or by
-@url{http://lists.nongnu.org/mailman/listinfo/gm2}.
-The mailing list contents can be viewed
-@url{http://lists.gnu.org/archive/html/gm2}.
-
-@node Other languages, , Community, Using
-@section Other languages for GCC
-
-These exist and can be found on the frontends web page on the
-@uref{http://gcc.gnu.org/frontends.html, gcc web site}.
-
-@node Using, , Community, Top
+@node Using, License, Overview, Top
 @chapter Using GNU Modula-2
 
 @menu
@@ -347,20 +243,16 @@ These exist and can be found on the frontends web page on the
 * Built-ins::             Accessing GNU Modula-2 Built-ins.
 * The PIM system module:: SYSTEM data types and procedures.
 * The ISO system module:: SYSTEM data types, procedures and run time.
-* Other languages::       Other languages for GCC.
-* What is GNU Modula-2::  Brief description of GNU Modula-2.
-* Why use GNU Modula-2::  Advantages of GNU Modula-2.
 @ifnothtml
 @c omit these nodes if generating gm2 webpage as these are hand written.
 * Release map:: Release map.
-* Development:: Development.
-* Features:: Features of the implementation.
 * Documentation:: Placeholder for how to access the documentation online.
 * Regression tests:: How to run the testsuite.
 * Limitations:: Current limitations.
 * Objectives:: Objectives of the implementation.
 * FAQ:: Frequently asked questions.
 * Community:: How to join the community.
+* Other languages:: Other languages for GCC.
 @end ifnothtml
 @end menu
 
@@ -427,7 +319,7 @@ add the @samp{-v} flag at the command line, for example:
 This displays the sub processes initiated by @samp{gm2} which can be useful
 when trouble shooting.}
 
-@node Compiler options, Elementary data types, Example usage, Using
+@node Compiler options, Linking, Example usage, Using
 @section Compiler options
 
 This section describes the compiler options specific to GNU Modula-2
@@ -804,7 +696,86 @@ generate code to detect whole number overflow and underflow.
 
 @c man end
 
-@node Elementary data types, Standard procedures, Compiler options, Using
+@node Linking, Elementary data types, Compiler options, Using
+
+This section describes the linking related options.  There are three
+linking strategies available which are dynamic scaffold, static
+scaffold and user defined.  The dynamic scaffold is enabled by default
+and each module will register itself to the run time @samp{M2RTS} via
+a constructor.  The static scaffold mechanism will invoke each modules
+@samp{_init} and @samp{_finish} function in turn via a sequence of
+calls from within @samp{main}.  Lastly the user defined strategy
+can be implemented by turning off the dynamic and static options via
+@samp{-fno-scaffold-dynamic} and @samp{-fno-scaffold-static}.
+
+In the simple test below:
+
+@example
+$ gm2 hello.mod
+@end example
+
+the driver will add the options @samp{-fscaffold-dynamic} and
+@samp{-fgen-module-list=-} which generate a list of application
+modules and also creates the @samp{main} function with calls to
+@samp{M2RTS}.  It can be useful to add the option @samp{-fsources}
+which displays the source files as they are parsed and summarizes
+whether the source file is required for compilation or linking.
+
+If you wish to split the above command line into a compile and link
+then you could use these steps:
+
+@example
+$ gm2 -c -fscaffold-main hello.mod
+$ gm2 hello.o
+@end example
+
+The @samp{-fscaffold-main} informs the compiler to generate the
+@samp{main} function and scaffold.  You can enable the environment
+variable @samp{GCC_M2LINK_RTFLAG} to trace the construction and
+destruction of the application.  The values for
+@samp{GCC_M2LINK_RTFLAG} are shown in the table below:
+
+@example
+value   | meaning
+=================
+all     | turn on all flags below
+module  | trace modules as they register themselves
+pre     | generate module list prior to dependency resolution
+dep     | trace module dependency resolution
+post    | generate module list after dependency resolution
+force   | generate a module list after dependency and forced
+        | ordering is complete
+@end example
+
+The values can be combined using a comma separated list.
+
+One of the advantages of the dynamic scaffold is that the driver
+behaves in a similar way to the other front end drivers.
+For example consider a small project consisting of 4 definition
+implementation modules (@samp{a.def}, @samp{a.mod}, @samp{b.def},
+@samp{b.mod}, @samp{c.def}, @samp{c.mod}, @samp{d.def}, @samp{d.mod})
+and a program module @samp{program.mod}.
+
+To link this project we could:
+
+@example
+$ gm2 -g -c a.mod
+$ gm2 -g -c b.mod
+$ gm2 -g -c c.mod
+$ gm2 -g -c d.mod
+$ gm2 -g program.mod a.o b.o c.o d.o
+@end example
+
+The module initialization sequence is defined by the ISO standard to
+follow the import graph traversal.  The initialization order is the
+order in which the corresponding separate modules finish the
+processing of their import lists.
+
+However, if required, you can override this using
+@samp{-fruntime-modules=a,b,c,d} for example which forces the
+initialization sequence to @samp{a}, @samp{b}, @samp{c} and @samp{d}.
+
+@node Elementary data types, Standard procedures, Linking, Using
 @section Elementary data types
 
 This section describes the elementary data types supported by GNU
@@ -1851,85 +1822,6 @@ and @code{f} are type compatible and will produce run time checking
 code to test whether the address range of their respective contents
 intersect.
 
-@node Linking, Building a shared library, Unbounded by reference, Using
-
-This section describes the linking related options.  There are three
-linking strategies available which are dynamic scaffold, static
-scaffold and user defined.  The dynamic scaffold is enabled by default
-and each module will register itself to the run time @samp{M2RTS} via
-a constructor.  The static scaffold mechanism will invoke each modules
-@samp{_init} and @samp{_finish} function in turn via a sequence of
-calls from within @samp{main}.  Lastly the user defined strategy
-can be implemented by turning off the dynamic and static options via
-@samp{-fno-scaffold-dynamic} and @samp{-fno-scaffold-static}.
-
-In the simple test below:
-
-@example
-$ gm2 hello.mod
-@end example
-
-the driver will add the options @samp{-fscaffold-dynamic} and
-@samp{-fgen-module-list=-} which generate a list of application
-modules and also creates the @samp{main} function with calls to
-@samp{M2RTS}.  It can be useful to add the option @samp{-fsources}
-which displays the source files as they are parsed and summarizes
-whether the source file is required for compilation or linking.
-
-If you wish to split the above command line into a compile and link
-then you could use these steps:
-
-@example
-$ gm2 -c -fscaffold-main hello.mod
-$ gm2 hello.o
-@end example
-
-The @samp{-fscaffold-main} informs the compiler to generate the
-@samp{main} function and scaffold.  You can enable the environment
-variable @samp{GCC_M2LINK_RTFLAG} to trace the construction and
-destruction of the application.  The values for
-@samp{GCC_M2LINK_RTFLAG} are shown in the table below:
-
-@example
-value   | meaning
-=================
-all     | turn on all flags below
-module  | trace modules as they register themselves
-pre     | generate module list prior to dependency resolution
-dep     | trace module dependency resolution
-post    | generate module list after dependency resolution
-force   | generate a module list after dependency and forced
-        | ordering is complete
-@end example
-
-The values can be combined using a comma separated list.
-
-One of the advantages of the dynamic scaffold is that the driver
-behaves in a similar way to the other front end drivers.
-For example consider a small project consisting of 4 definition
-implementation modules (@samp{a.def}, @samp{a.mod}, @samp{b.def},
-@samp{b.mod}, @samp{c.def}, @samp{c.mod}, @samp{d.def}, @samp{d.mod})
-and a program module @samp{program.mod}.
-
-To link this project we could:
-
-@example
-$ gm2 -g -c a.mod
-$ gm2 -g -c b.mod
-$ gm2 -g -c c.mod
-$ gm2 -g -c d.mod
-$ gm2 -g program.mod a.o b.o c.o d.o
-@end example
-
-The module initialization sequence is defined by the ISO standard to
-follow the import graph traversal.  The initialization order is the
-order in which the corresponding separate modules finish the
-processing of their import lists.
-
-However, if required, you can override this using
-@samp{-fruntime-modules=a,b,c,d} for example which forces the
-initialization sequence to @samp{a}, @samp{b}, @samp{c} and @samp{d}.
-
 @node Building a shared library, Interface for Python, Unbounded by reference, Using
 @section Building a shared library
 
@@ -2733,7 +2625,7 @@ There are also a variety of fixed sized @code{INTEGER} and
 @code{CARDINAL} types.  The variety of the fixed sized types will
 depend upon the target architecture.
 
-@node The ISO system module, , The PIM system module, Using
+@node The ISO system module, Release map, The PIM system module, Using
 @section The ISO system module
 
 @include m2/SYSTEM-iso.texi
@@ -2750,7 +2642,111 @@ There are also a variety of fixed sized @code{INTEGER} and
 @code{CARDINAL} types.  The variety of the fixed sized types will
 depend upon the target architecture.
 
-@node License, Copying, The ISO system module, Top
+@node Release map, Documentation, The ISO system module, Using
+@section Release map
+
+GNU Modula-2 is now part of GCC and therefore will adopt the GCC
+release schedule.  It is intended that GNU Modula-2 implement more of
+the GCC builtins (vararg access) and GCC features.
+
+There is an intention to implement the ISO generics and the M2R10
+dialect of Modula-2.  It will also implement all language changes.  If
+you wish to see something different please email
+@email{gm2@@nongnu.org} with your ideas.
+
+@node Documentation, Regression tests, Release map, Using
+@section Documentation
+
+The GNU Modula-2 documentation is available on line
+@url{https://www.nongnu.org/gm2/homepage.html,at the gm2 homepage}
+or in the pdf, info, html file format.
+
+@node Regression tests, Limitations, Documentation, Using
+@section Regression tests for gm2 in the repository
+
+The regression testsuite can be run from the gcc build directory:
+
+@example
+$ cd build-gcc
+$ make check -j 24
+@end example
+
+which runs the complete testsuite for all compilers using 24 parallel
+invocations of the compiler.  Individual language testsuites can be
+run by specifying the language, for example the Modula-2 testsuite can
+be run using:
+
+@example
+$ cd build-gcc
+$ make check-m2 -j 24
+@end example
+
+Finally the results of the testsuite can be emailed to the
+@url{https://gcc.gnu.org/lists.html, gcc-testresults} list using the
+@file{test_summary} script found in the gcc source tree:
+
+@example
+$ @samp{directory to the sources}/contrib/test_summary
+@end example
+
+@node Limitations, Objectives, Regression tests, Using
+@section Limitations
+
+Logitech compatibility library is incomplete.  The principle modules
+for this platform exist however for a comprehensive list of completed
+modules please check the documentation
+@url{gm2.html}.
+
+@node Objectives, FAQ, Limitations, Using
+@section Objectives
+
+@itemize @bullet
+
+@item
+The intention of GNU Modula-2 is to provide a production Modula-2
+front end to GCC.
+
+@item
+It should support all Niklaus Wirth PIM Dialects [234] and also ISO
+Modula-2 including a re-implementation of all the ISO modules.
+
+@item
+There should be an easy interface to C.
+
+@item
+Exploit the features of GCC.
+
+@item
+Listen to the requests of the users.
+@end itemize
+
+@node FAQ, Community, Objectives, Using
+@section FAQ
+
+@subsection Why use the C++ exception mechanism in GCC, rather than a bespoke Modula-2 mechanism?
+
+The C++ mechanism is tried and tested, it also provides GNU Modula-2
+with the ability to link with C++ modules and via swig it can raise
+Python exceptions.
+
+@node Community, Other languages, FAQ, Using
+@section Community
+
+You can subscribe to the GNU Modula-2 mailing by sending an
+email to:
+@email{gm2-subscribe@@nongnu.org}
+or by
+@url{http://lists.nongnu.org/mailman/listinfo/gm2}.
+The mailing list contents can be viewed
+@url{http://lists.gnu.org/archive/html/gm2}.
+
+@node Other languages, , Community, Using
+@section Other languages for GCC
+
+These exist and can be found on the frontends web page on the
+@uref{http://gcc.gnu.org/frontends.html, gcc web site}.
+
+@node License, Copying, Using, Top
 @section License of GNU Modula-2
 
 GNU Modula-2 is free software, the compiler is held under the GPL v3

Re: [PATCH] Modula-2: fix documentation layout

[Gaius Mulley]

Eric Botcazou <botcazou@adacore.com> writes:

> Hi,
>
> the Modula-2 documentation is rejected by older versions of Makeinfo because 
> the web of @node markers is fairly broken, apparently some subsections were 
> moved around, most notably between the Overview and Using sections, and the 
> @node markers were not (properly) adjusted.
>
> This patch allows me to build it with these older versions, as well as with 
> modern versions.  OK for mainline?
>
>
> 2023-01-09  Eric Botcazou  <ebotcazou@adacore.com>
>
> 	* doc/gm2.texi (Overview): Fix @node markers.
> 	(Using): Likewise.  Remove subsections that were moved to
> 	Overview from the menu and move others around.

Hi Eric,

yes indeed and thanks for the patch!

regards,
Gaius

Re: [PATCH] Modula-2: fix documentation layout

[Eric Botcazou]

[-- Attachment #1: Type: text/plain, Size: 406 bytes --]

Hi Gaius,

> yes indeed and thanks for the patch!

You're welcome.  The documentation was slightly broken again in the meantime, 
but nothing really serious this time.

Again tested with a modern and an old version of Makeinfo.  OK for mainline?


2023-03-27  Eric Botcazou  <ebotcazou@adacore.com>

	* doc/gm2.texi: Add missing Next, Previous and Top fields to most
	top-level sections.

-- 
Eric Botcazou

[-- Attachment #2: p.diff --]
[-- Type: text/x-patch, Size: 1588 bytes --]

diff --git a/gcc/doc/gm2.texi b/gcc/doc/gm2.texi
index c08bb89ac68..db35f6f7e93 100644
--- a/gcc/doc/gm2.texi
+++ b/gcc/doc/gm2.texi
@@ -2761,7 +2761,7 @@ The mailing list contents can be viewed
 These exist and can be found on the frontends web page on the
 @uref{http://gcc.gnu.org/frontends.html, gcc web site}.
 
-@node License, , ,
+@node License, Copying, Using, Top
 @section License of GNU Modula-2
 
 GNU Modula-2 is free software, the compiler is held under the GPL v3
@@ -2781,10 +2781,10 @@ see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
 More information on how these licenses work is available
 @uref{http://www.gnu.org/licenses/licenses.html} on the GNU web site.
 
-@node Copying, , ,
+@node Copying, Contributing, License, Top
 @include gpl_v3_without_node.texi
 
-@node Contributing, , ,
+@node Contributing, EBNF, Copying, Top
 @section Contributing to GNU Modula-2
 
 Please do and please read the GNU Emacs info under
@@ -2808,7 +2808,7 @@ Many thanks and enjoy your coding!
 @c This section is still being written.
 @c @include gm2-internals.texi
 
-@node EBNF, , ,
+@node EBNF, Libraries, Contributing, Top
 @chapter EBNF of GNU Modula-2
 
 This chapter contains the EBNF of GNU Modula-2.  This grammar currently
@@ -2822,14 +2822,14 @@ phase.
 
 @include m2/gm2-ebnf.texi
 
-@node Libraries, , ,
+@node Libraries, Indices, EBNF, Top
 @chapter PIM and ISO library definitions
 
 This chapter contains M2F, PIM and ISO libraries.
 
 @include m2/gm2-libs.texi
 
-@node Indices, , ,
+@node Indices, , Libraries, Top
 @section Indices
 
 @ifhtml

Re: [PATCH] Modula-2: fix documentation layout

[Gaius Mulley]

Eric Botcazou <botcazou@adacore.com> writes:

> Hi Gaius,
>
>> yes indeed and thanks for the patch!
>
> You're welcome.  The documentation was slightly broken again in the meantime, 
> but nothing really serious this time.
>
> Again tested with a modern and an old version of Makeinfo.  OK for mainline?
>
>
> 2023-03-27  Eric Botcazou  <ebotcazou@adacore.com>
>
> 	* doc/gm2.texi: Add missing Next, Previous and Top fields to most
> 	top-level sections.

Hi Eric,

yes certainly - thanks again!

regards,
Gaius