From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by sourceware.org (Postfix) with ESMTPS id 5211C3858D38 for ; Mon, 9 Jan 2023 22:32:12 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 5211C3858D38 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=adacore.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=adacore.com Received: by mail-wm1-x32b.google.com with SMTP id ay40so7464604wmb.2 for ; Mon, 09 Jan 2023 14:32:12 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=adacore.com; s=google; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=4DcwuXSjiYZ8CZBVHBvKXIytr1FEr2CTmqqmrij2BUw=; b=JkeB5X42GsauRtTZxZu8zBT3bKrOfhHpc23o6p0JOE9uWwmgI1JpDwfm9tJfttKFOp A/nu7yXIykI9Ybp5U6PpFNEPifUyM3YSTSoWYcxqJuP7rNAbNb5URAI/vd5yoW/EWgir gFU5U1oax+DWVsQgjWZjfnHVkKOmMQKVfNEhdpFlToEnUKsvmdcFyQqNnumOQgYrJGxr LFhcAb3qGArm9I10FAtQYir6iqDW7ER8crRYohKRi7UXtNBsltkBkhvUm+jZhdJlEbLx QE/GgTobpYQvhuKOHSA82WLw6ZV8BtzTc21SWmOuWpg9V4riXSkLny3jDUE2jADEb1/K 1yWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=4DcwuXSjiYZ8CZBVHBvKXIytr1FEr2CTmqqmrij2BUw=; b=KwAXR/8CqBgznt+xXtGkRn1fl2HJOcW9aMfeSX6jrx5UJkyS3hqYPuEYEh76tSoKXj Dgt8LHVHnXdwY6FlF6HE3GB4A9KrfbAGn2I9/2qH513G7BS5rhW1scPmoXX0wzrF66wq 4PtMPD+vFRnQsoTvJnZfjMXdjYiIwUdo6LGF1KBN00qmjb8TiATnm1aMZZeqvwExdCTS /FD/ZAEW8vW2y8gyAT57VbuJWS9+2+VJjYbv5i36eizwVCaTWyCs+wdQcsf/b1/7lVR7 Ew9dOT6AzAWY+NZHJz0amX4lrWy1XXW4umLxgZSDty2ynUKGV/fre6L0tLJTjD9mzE1Q c9rg== X-Gm-Message-State: AFqh2kpPNjznuTMWtM3f/09ubeoBbIQ3FYDAg0wNM1Yxu3wE51DW4edV LczyhGiz+Ld63fA/w2AaDJfAgn/0BWWhnM+/ X-Google-Smtp-Source: AMrXdXuGnpAnDqTIsSYSRy5safAXRPBCNaOUVnV712Yuc5OlOTSvY5PfJNiKjVSvRinaoqM0PlC9gw== X-Received: by 2002:a05:600c:22cc:b0:3d1:bd81:b1b1 with SMTP id 12-20020a05600c22cc00b003d1bd81b1b1mr46804386wmg.18.1673303531051; Mon, 09 Jan 2023 14:32:11 -0800 (PST) Received: from fomalhaut.localnet ([2a01:e0a:8d5:d990:e654:e8ff:fe8f:2ce6]) by smtp.gmail.com with ESMTPSA id g12-20020a05600c310c00b003c70191f267sm18630284wmo.39.2023.01.09.14.32.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Jan 2023 14:32:10 -0800 (PST) From: Eric Botcazou X-Google-Original-From: Eric Botcazou To: gcc-patches@gcc.gnu.org Cc: gaiusmod2@gmail.com Subject: [PATCH] Modula-2: fix documentation layout Date: Mon, 09 Jan 2023 23:30:52 +0100 Message-ID: <3209307.aeNJFYEL58@fomalhaut> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="nextPart3215459.44csPzL39Z" Content-Transfer-Encoding: 7Bit X-Spam-Status: No, score=-10.6 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,KAM_SHORT,RCVD_IN_DNSWL_NONE,SPF_HELO_NONE,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: This is a multi-part message in MIME format. --nextPart3215459.44csPzL39Z Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" 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 * 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 --nextPart3215459.44csPzL39Z Content-Disposition: attachment; filename="p.diff" Content-Transfer-Encoding: 7Bit Content-Type: text/x-patch; charset="UTF-8"; name="p.diff" 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 --nextPart3215459.44csPzL39Z--