Modula-2: fix documentation layout
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. gcc/ * doc/gm2.texi (Overview): Fix @node markers. (Using): Likewise. Remove subsections that were moved to Overview from the menu and move others around.
This commit is contained in:
Eric Botcazou
parent
01ea66a6c5
commit
1dcc9779d6
1 changed files with 193 additions and 197 deletions
390
gcc/doc/gm2.texi
390
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue