[wwwdocs] document modula-2 in gcc-13/changes.html (and index.html)

  Hello,

The following patch provides a summary of the modula-2 front end
and also contains links to the online modula-2 documentation in
index.html.

[I'm just about to git push fixes so that modula-2 builds html, info and
 pdf documentation into the standard directories.]

regards,
Gaius
  

On Fri, Feb 03, 2023 at 02:52:43PM +0000, Gaius Mulley via Gcc-patches wrote:
> 
> Hello,
> 
> The following patch provides a summary of the modula-2 front end
> and also contains links to the online modula-2 documentation in
> index.html.
> 
> [I'm just about to git push fixes so that modula-2 builds html, info and
>  pdf documentation into the standard directories.]

IMHO it should go also into the News section on the gcc.gnu.org page.
If you look into https://gcc.gnu.org/news.html which contains older news,
it contains also e.g. D addition entry.

	Jakub
  

On Fri, 3 Feb 2023, Gaius Mulley wrote:
> The following patch provides a summary of the modula-2 front end
> and also contains links to the online modula-2 documentation in
> index.html.

> +<h3 id="modula2">Modula-2</h3>
> +<ul>
> +  <li>Support for the language Modula-2 has been added.  The dialects
> +  supported are PIM2, PIM3, PIM4 and ISO/IEC 10514-1.  Also included
> +  are a complete set of ISO/IEC 10514-1 libraries and PIM
> +    libraries.</li>

I wonder whether we can this a bit more active. 

Maybe something like "This includes support for the ... dialects, a 
complete set of ...and ..."?

> +  <li><a href="https://gcc.gnu.org/onlinedocs/m2/Compiler-options.html">
> +      Compiler options</a>.</li>

Maybe put this in parenthesis since it's not an update as such and more 
relatives to the previous item?

> +  <li>Linking has been redesigned.</li>

What are we saying here? I.e., what is the change we are announcing? As a 
user, what might I notice? Why do I care?


The above are questions to possibly improve this for our users. Please 
adjust as you see fit, or push as is, if you prefer.


On a somewhat related note: This is definitely big enough to warrant an 
entry in the News section on our main page. :-)  Do you want to propose
something?

Gerald
  

Gerald Pfeifer <gerald@pfeifer.com> writes:

> On Fri, 3 Feb 2023, Gaius Mulley wrote:
>> The following patch provides a summary of the modula-2 front end
>> and also contains links to the online modula-2 documentation in
>> index.html.
>
>> +<h3 id="modula2">Modula-2</h3>
>> +<ul>
>> +  <li>Support for the language Modula-2 has been added.  The dialects
>> +  supported are PIM2, PIM3, PIM4 and ISO/IEC 10514-1.  Also included
>> +  are a complete set of ISO/IEC 10514-1 libraries and PIM
>> +    libraries.</li>
>
> I wonder whether we can this a bit more active. 
>
> Maybe something like "This includes support for the ... dialects, a 
> complete set of ...and ..."?
>
>> +  <li><a href="https://gcc.gnu.org/onlinedocs/m2/Compiler-options.html">
>> +      Compiler options</a>.</li>
>
> Maybe put this in parenthesis since it's not an update as such and more 
> relatives to the previous item?
>
>> +  <li>Linking has been redesigned.</li>
>
> What are we saying here? I.e., what is the change we are announcing? As a 
> user, what might I notice? Why do I care?
>

Thanks for spotting this - agreed.

> The above are questions to possibly improve this for our users. Please 
> adjust as you see fit, or push as is, if you prefer.
>
>
> On a somewhat related note: This is definitely big enough to warrant an 
> entry in the News section on our main page. :-)  Do you want to propose
> something?
>
> Gerald

Ah yes thank you for the advice - here is an improved proposed patch
containing:

	* htdocs/frontends.html: An update to say the front end is now in
	the development trunk.
	* htdocs/gcc-13/changes.html: A description of which dialects are
	supported and the user level front end changes so far.
	* htdocs/index.html: Proposed news entry.
	* htdocs/onlinedocs/index.html: PDF, PS and HTML documentation
	links.

regards,
Gaius


diff --git a/htdocs/frontends.html b/htdocs/frontends.html
index 12af359b..75be4658 100644
--- a/htdocs/frontends.html
+++ b/htdocs/frontends.html
@@ -41,10 +41,10 @@ has a back end that generates assembler directly, using the GCC back end.</li>
 (at an early stage of development).</li>
 
 <li><a href="http://www.nongnu.org/gm2/">GNU Modula-2</a> implements
-the PIM2, PIM3, PIM4 and ISO dialects of the language.  The compiler
-is fully operational with GCC 10 and GCC 11 (on
-GNU/Linux x86 systems).  Work is in progress to move the front end to
-the GCC trunk.  The front end is mostly written in Modula-2 and it
+the ISO/IEC 10514-1, PIM2, PIM3 and PIM4 dialects of the language.
+The compiler is operational with GCC 10, GCC 11 GCC 12 (on
+GNU/Linux x86 systems).  The front end is now in the GCC development
+trunk (GCC 13).  The front end is mostly written in Modula-2 and it
 includes a bootstrap tool which translates Modula-2 into C/C++.</li>
 
 <li>Modula-3 (for links see <a
diff --git a/htdocs/gcc-13/changes.html b/htdocs/gcc-13/changes.html
index 9ecd115c..20453c92 100644
--- a/htdocs/gcc-13/changes.html
+++ b/htdocs/gcc-13/changes.html
@@ -283,6 +283,18 @@ a work-in-progress.</p>
 
 <!-- <h3 id="go">Go</h3> -->
 
+<h3 id="modula2">Modula-2</h3>
+<ul>
+  <li>Support for the language Modula-2 has been added.  This includes
+    support for the ISO/IEC 10514-1, PIM2, PIM3, PIM4 dialects
+    together with a complete set of ISO/IEC 10514-1 and PIM
+    libraries.</li>
+  <li>The <code><* noreturn *></code> attribute is supported
+    with the <code>-Wreturn-type</code>
+    <a href="https://gcc.gnu.org/onlinedocs/m2/Compiler-options.html">
+      option</a>.</li>
+</ul>
+
 <!-- .................................................................. -->
 <!-- <h2 id="jit">libgccjit</h2> -->
 
diff --git a/htdocs/index.html b/htdocs/index.html
index 80730c06..3d03ef46 100644
--- a/htdocs/index.html
+++ b/htdocs/index.html
@@ -61,6 +61,11 @@ mission statement</a>.</p>
   has been contributed to Compiler Explorer (aka godbolt.org) by Marc
   Poulhiès</dd>
 
+<dt><span><a href="gcc-13/changes.html#modula2">Modula-2 front end added</a></span>
+  <span class="date">[2022-12-14]</span></dt>
+<dd>The Modula-2 programming language front end has been added to GCC.
+  This front end was contributed by Gaius Mulley.</dd>
+
 <dt><span><a href="https://gcc.gnu.org/wiki/cauldron2022">GNU Tools Cauldron 2022</a></span>
     <span class="date">[2022-09-02]</span></dt>
     <dd>Prague, Czech Republic and online, September 16-18 2022</dd>
diff --git a/htdocs/onlinedocs/index.html b/htdocs/onlinedocs/index.html
index 343ff9f5..27a8a505 100644
--- a/htdocs/onlinedocs/index.html
+++ b/htdocs/onlinedocs/index.html
@@ -1647,6 +1647,12 @@ existing release.</p>
            href="https://gcc.gnu.org/onlinedocs/gdc.ps.gz">PostScript</a> or <a
            href="https://gcc.gnu.org/onlinedocs/gdc-html.tar.gz">an
            HTML tarball</a>)</li>
+    <li><a href="https://gcc.gnu.org/onlinedocs/m2/">GNU M2 Manual</a> (<a
+           href="https://gcc.gnu.org/onlinedocs/m2.pdf">also in
+           PDF</a> or <a
+           href="https://gcc.gnu.org/onlinedocs/m2.ps.gz">PostScript</a> or <a
+           href="https://gcc.gnu.org/onlinedocs/m2-html.tar.gz">an
+           HTML tarball</a>)</li>
     <li><a href="https://gcc.gnu.org/onlinedocs/libgomp/">GNU Offloading and
            Multi Processing Runtime Library Manual</a> (<a
            href="https://gcc.gnu.org/onlinedocs/libgomp.pdf">also in
  

Hi Gaius,

apologies, I thought you had pushed the updated patch and only now 
realized it's not in yet.

Please look into the few bits below and then go ahead and push.

On Mon, 6 Feb 2023, Gaius Mulley wrote:
> 	* htdocs/frontends.html: An update to say the front end is now in
> 	the development trunk.

Here we'd usually simply say

  * frontends: The Modula-2 front end is now on the 
  development trunk.

skiping "An update to say", or at least "An update to" and the "htdocs/" 
port (and adding which front end).

> 	* htdocs/gcc-13/changes.html: A description of which dialects are
> 	supported and the user level front end changes so far.

  * gcc-13: Note which Modula-2 dialects are...

> 	* htdocs/index.html: Proposed news entry.

  * index: Announce Modula-2 inclusion 

(or something like that).

> 	* htdocs/onlinedocs/index.html: PDF, PS and HTML documentation
> 	links.
  * onlinedocs: Add links to Modula-2 documentation


> +The compiler is operational with GCC 10, GCC 11 GCC 12 (on
                                   
...GCC 11, and GCC 12...

> +GNU/Linux x86 systems).  The front end is now in the GCC development
> +trunk (GCC 13).  The front end is mostly written in Modula-2 and it
>  includes a bootstrap tool which translates Modula-2 into C/C++.</li>

How about "It is mostly written in Modula-2 and includes..." to avoid
repetition of "the front end"?


Thank you,
Gerald
  

Gerald Pfeifer <gerald@pfeifer.com> writes:

> Hi Gaius,
>
> apologies, I thought you had pushed the updated patch and only now 
> realized it's not in yet.
>
> Please look into the few bits below and then go ahead and push.
>
> On Mon, 6 Feb 2023, Gaius Mulley wrote:
>> 	* htdocs/frontends.html: An update to say the front end is now in
>> 	the development trunk.
>
> Here we'd usually simply say
>
>   * frontends: The Modula-2 front end is now on the 
>   development trunk.
>
> skiping "An update to say", or at least "An update to" and the "htdocs/" 
> port (and adding which front end).
>
>> 	* htdocs/gcc-13/changes.html: A description of which dialects are
>> 	supported and the user level front end changes so far.
>
>   * gcc-13: Note which Modula-2 dialects are...
>
>> 	* htdocs/index.html: Proposed news entry.
>
>   * index: Announce Modula-2 inclusion 
>
> (or something like that).
>
>> 	* htdocs/onlinedocs/index.html: PDF, PS and HTML documentation
>> 	links.
>   * onlinedocs: Add links to Modula-2 documentation
>
>
>> +The compiler is operational with GCC 10, GCC 11 GCC 12 (on
>                                    
> ...GCC 11, and GCC 12...
>
>> +GNU/Linux x86 systems).  The front end is now in the GCC development
>> +trunk (GCC 13).  The front end is mostly written in Modula-2 and it
>>  includes a bootstrap tool which translates Modula-2 into C/C++.</li>
>
> How about "It is mostly written in Modula-2 and includes..." to avoid
> repetition of "the front end"?
>
>
> Thank you,
> Gerald

Hi Gerald,

no problem at all and many thanks for the advice.  I'll push the changes
shortly,

regards,
Gaius
  

The patch is now in, alas all the GNU M2 manual links now point to 
non-existant locations.

Does maintainer-scripts/update_web_docs_git require an update to cover 
Modula-2 and actually build the manual we are now linking to (or rather
trying to)?

Gerald
  

Gerald Pfeifer <gerald@pfeifer.com> writes:

> The patch is now in, alas all the GNU M2 manual links now point to 
> non-existant locations.
>
> Does maintainer-scripts/update_web_docs_git require an update to cover 
> Modula-2 and actually build the manual we are now linking to (or rather
> trying to)?
>
> Gerald

Apologies I was going to ask about these links.  I've updated the m2
subtree with target documentation independent sections.  Attached is a
proposed patch for maintainer-scripts/update_web_docs_git feel free to
apply or adapt in any way.

regards,
Gaius


--->o--->o--->o--->o--->o--->o--->o--->o--->o--->o--->o--->o--->o--->o

Add modula-2 documentation to be built

Update the online documentation build script to include modula-2.

maintainer-scripts/ChangeLog:

	* update_web_docs_git (MANUALS): Add gm2.
	Add include path for m2 target independent sections.


diff --git a/maintainer-scripts/update_web_docs_git b/maintainer-scripts/update_web_docs_git
index 1c6a993cafd..c678fc29155 100755
--- a/maintainer-scripts/update_web_docs_git
+++ b/maintainer-scripts/update_web_docs_git
@@ -24,6 +24,7 @@ MANUALS="cpp
   gdc
   gfortran
   gfc-internals
+  gm2
   gnat_ugn
   gnat-style
   gnat_rm
@@ -169,6 +170,9 @@ for file in $MANUALS; do
     includes="-I ${includedir} -I `dirname ${filename}`"
     if [ "$file" = "gnat_ugn" ]; then
       includes="$includes -I gcc/gcc/ada -I gcc/gcc/ada/doc/gnat_ugn"
+    elif [ "$file" = "gm2" ]; then
+      includes="$includes -I gcc/gcc/m2/target-independent"
+      includes="$includes -I gcc/gcc/m2/target-independent/m2"
     fi
     makeinfo --html --css-ref $CSS $includes -o ${file} ${filename}
     tar cf ${file}-html.tar ${file}/*.html
  

On Thu, 16 Mar 2023, Gaius Mulley wrote:
>> Does maintainer-scripts/update_web_docs_git require an update to cover 
>> Modula-2 and actually build the manual we are now linking to
> Apologies I was going to ask about these links.  I've updated the m2
> subtree with target documentation independent sections.  Attached is a
> proposed patch for maintainer-scripts/update_web_docs_git feel free to
> apply or adapt in any way.

I sorted the special casing alphabetically and pushed the updated patch
below.

Then I updated the script on gcc.gnu.org and did a testrun. 

Indeed Modula 2 manuals are now available below
  https://gcc.gnu.org/onlinedocs/ 
just the links from that page are off (referring to m2 instead of gm2). 
I'll fix that next.

Gerald


commit fa4d0ab533cc2bc9cb6f512b3d4bd0bbc01ee797
Author: Gaius Mulley <gaiusmod2@gmail.com>
Date:   Fri Mar 17 00:08:20 2023 +0100

    maintainer-scripts: Add Modula-2 manual to update_web_docs_git
    
    maintainer-scripts/ChangeLog:
    
            * update_web_docs_git (MANUALS): Add gm2.
            Add include path for gm2 manual.

diff --git a/maintainer-scripts/update_web_docs_git b/maintainer-scripts/update_web_docs_git
index 1c6a993cafd..4bb4897bf35 100755
--- a/maintainer-scripts/update_web_docs_git
+++ b/maintainer-scripts/update_web_docs_git
@@ -24,6 +24,7 @@ MANUALS="cpp
   gdc
   gfortran
   gfc-internals
+  gm2
   gnat_ugn
   gnat-style
   gnat_rm
@@ -167,7 +168,10 @@ for file in $MANUALS; do
   filename=`find . -name ${file}.texi`
   if [ "${filename}" ]; then
     includes="-I ${includedir} -I `dirname ${filename}`"
-    if [ "$file" = "gnat_ugn" ]; then
+    if [ "$file" = "gm2" ]; then
+      includes="$includes -I gcc/gcc/m2/target-independent"
+      includes="$includes -I gcc/gcc/m2/target-independent/m2"
+    elif [ "$file" = "gnat_ugn" ]; then
       includes="$includes -I gcc/gcc/ada -I gcc/gcc/ada/doc/gnat_ugn"
     fi
     makeinfo --html --css-ref $CSS $includes -o ${file} ${filename}