[gcc-wwdocs] Update to Fortran changes

I've check the changes with W3 validator. There are no problems related 
to my changes, however, it does object to the lack of character encoding 
in the file. My knowledge of HTML is limited, so don't know how to fix that.

This is the first time in changing the wwwdoc, I haven't included a 
change log as there there doesn't appear to be any ChangeLog files.

The patch is attached. OK to commit?

Hi Mark,

On 11/26/19 11:46 AM, Mark Eggleston wrote:
> I've check the changes with W3 validator. There are no problems 
> related to my changes, however, it does object to the lack of 
> character encoding in the file.

Note that some script modifies the file a bit – the final file does have 
a character encoding (content="text/html; charset=utf-8").

> This is the first time in changing the wwwdoc, I haven't included a 
> change log as there there doesn't appear to be any ChangeLog files.

There is only a commit log (see 'git log'); the format is still a bit in 
a flux as before there was only 'csv' where it applied to a single file.

[With git it is useful to have a meaningful single line (for "git log 
--pretty=oneline") and, if needed, an empty line and something more. As 
the main repository is going to move to GIT as well, this also applies 
there. – But you already follow this style.]

> The patch is attached. OK to commit?

I wonder whether you should use a main bullet point with something like 
"Legacy improvements (<code>-fdec</code>)" under which you put the 
current list. [Or some other wording.] That makes it easier to read for 
users – those, who care about legacy support, can quickly look at the 
-fdec changes – while those interested in standard Fortran can skip it. 
(Except for the character-diagnostic type-info improvement, all are 
items seem to be for -fdec or -fdec-…)

In particular, currently, the following item does not make clear that it 
is about legacy support: "Variables with the <code>AUTOMATIC</code> 
attribute can be used in <code>EQUIVALENCE</code> statements."

I think it can remain as is with the -fdec umbrella item. But without it 
really requires the background knowledge that the AUTOMATIC attribute is 
only available with -fdec-static (or -fdec).

Cheers,

Tobias

On 26/11/2019 11:12, Tobias Burnus wrote:
> Hi Mark,
>
> On 11/26/19 11:46 AM, Mark Eggleston wrote:
>> I've check the changes with W3 validator. There are no problems 
>> related to my changes, however, it does object to the lack of 
>> character encoding in the file.
>
> Note that some script modifies the file a bit – the final file does 
> have a character encoding (content="text/html; charset=utf-8").
Understood.
>
>> This is the first time in changing the wwwdoc, I haven't included a 
>> change log as there there doesn't appear to be any ChangeLog files.
>
> There is only a commit log (see 'git log'); the format is still a bit 
> in a flux as before there was only 'csv' where it applied to a single 
> file.
>
> [With git it is useful to have a meaningful single line (for "git log 
> --pretty=oneline") and, if needed, an empty line and something more. 
> As the main repository is going to move to GIT as well, this also 
> applies there. – But you already follow this style.]
>
>> The patch is attached. OK to commit?
>
> I wonder whether you should use a main bullet point with something 
> like "Legacy improvements (<code>-fdec</code>)" under which you put 
> the current list. [Or some other wording.] That makes it easier to 
> read for users – those, who care about legacy support, can quickly 
> look at the -fdec changes – while those interested in standard Fortran 
> can skip it. (Except for the character-diagnostic type-info 
> improvement, all are items seem to be for -fdec or -fdec-…)
Used "Legacy extension:".
>
> In particular, currently, the following item does not make clear that 
> it is about legacy support: "Variables with the <code>AUTOMATIC</code> 
> attribute can be used in <code>EQUIVALENCE</code> statements."
Made it clear that this an extension of -fdec-static.
>
> I think it can remain as is with the -fdec umbrella item. But without 
> it really requires the background knowledge that the AUTOMATIC 
> attribute is only available with -fdec-static (or -fdec).

Stated that -fdec-static or -fdec are needed to use AUTOMATIC in 
EQUIVALENCE.

>
> Cheers,
>
> Tobias
>
>
Changes acceptable? OK to commit?

Second attempt this time with attachment.

Apologies.

regards,

Mark

On 26/11/2019 15:56, Mark Eggleston wrote:
>
> On 26/11/2019 11:12, Tobias Burnus wrote:
>> Hi Mark,
>>
>> On 11/26/19 11:46 AM, Mark Eggleston wrote:
>>> I've check the changes with W3 validator. There are no problems 
>>> related to my changes, however, it does object to the lack of 
>>> character encoding in the file.
>>
>> Note that some script modifies the file a bit – the final file does 
>> have a character encoding (content="text/html; charset=utf-8").
> Understood.
>>
>>> This is the first time in changing the wwwdoc, I haven't included a 
>>> change log as there there doesn't appear to be any ChangeLog files.
>>
>> There is only a commit log (see 'git log'); the format is still a bit 
>> in a flux as before there was only 'csv' where it applied to a single 
>> file.
>>
>> [With git it is useful to have a meaningful single line (for "git log 
>> --pretty=oneline") and, if needed, an empty line and something more. 
>> As the main repository is going to move to GIT as well, this also 
>> applies there. – But you already follow this style.]
>>
>>> The patch is attached. OK to commit?
>>
>> I wonder whether you should use a main bullet point with something 
>> like "Legacy improvements (<code>-fdec</code>)" under which you put 
>> the current list. [Or some other wording.] That makes it easier to 
>> read for users – those, who care about legacy support, can quickly 
>> look at the -fdec changes – while those interested in standard 
>> Fortran can skip it. (Except for the character-diagnostic type-info 
>> improvement, all are items seem to be for -fdec or -fdec-…)
> Used "Legacy extension:".
>>
>> In particular, currently, the following item does not make clear that 
>> it is about legacy support: "Variables with the 
>> <code>AUTOMATIC</code> attribute can be used in 
>> <code>EQUIVALENCE</code> statements."
> Made it clear that this an extension of -fdec-static.
>>
>> I think it can remain as is with the -fdec umbrella item. But without 
>> it really requires the background knowledge that the AUTOMATIC 
>> attribute is only available with -fdec-static (or -fdec).
>
> Stated that -fdec-static or -fdec are needed to use AUTOMATIC in 
> EQUIVALENCE.
>
>>
>> Cheers,
>>
>> Tobias
>>
>>
> Changes acceptable? OK to commit?
>

On Tue, Nov 26, 2019 at 1:12 PM Tobias Burnus <tobias@codesourcery.com> wrote:
> In particular, currently, the following item does not make clear that it
> is about legacy support: "Variables with the <code>AUTOMATIC</code>
> attribute can be used in <code>EQUIVALENCE</code> statements."
>
> I think it can remain as is with the -fdec umbrella item. But without it
> really requires the background knowledge that the AUTOMATIC attribute is
> only available with -fdec-static (or -fdec).

Speaking of which, to avoid confusion maybe we should rename the
-f[no-]automatic option to something like -f[no-]save, since the
Fortran standard description of an "automatic data object" doesn't
really have anything to do with the option, and neither does the
option have anything to do specifically with the DEC AUTOMATIC
specifier?

On 11/27/19 8:58 AM, Janne Blomqvist wrote:
> On Tue, Nov 26, 2019 at 1:12 PM Tobias Burnus <tobias@codesourcery.com> wrote:
>> AUTOMATIC attribute
> Speaking of which, to avoid confusion maybe we should rename the
> -f[no-]automatic option to something like -f[no-]save, since the
> Fortran standard description of an "automatic data object" doesn't
> really have anything to do with the option, and neither does the
> option have anything to do specifically with the DEC AUTOMATIC
> specifier?

While in principle I concur that the naming is bad, I fear this will 
break several makefiles – hence, I am not sure it is worth the trouble – 
and I am declined to say that it isn't.

Cheers,

Tobias

On Wed, Nov 27, 2019 at 10:29 AM Tobias Burnus <tobias@codesourcery.com> wrote:
>
> On 11/27/19 8:58 AM, Janne Blomqvist wrote:
> > On Tue, Nov 26, 2019 at 1:12 PM Tobias Burnus <tobias@codesourcery.com> wrote:
> >> AUTOMATIC attribute
> > Speaking of which, to avoid confusion maybe we should rename the
> > -f[no-]automatic option to something like -f[no-]save, since the
> > Fortran standard description of an "automatic data object" doesn't
> > really have anything to do with the option, and neither does the
> > option have anything to do specifically with the DEC AUTOMATIC
> > specifier?
>
> While in principle I concur that the naming is bad, I fear this will
> break several makefiles – hence, I am not sure it is worth the trouble –
> and I am declined to say that it isn't.

Yes, of course we can't remove it outright. But we could keep it as a
deprecated alias for -f[no-]save (or whatever it should be called) and
document it as such.

On 11/26/19 7:33 PM, Mark Eggleston wrote:
>   htdocs/gcc-10/changes.html | 41 +++++++++++++++++++++++++++++++++++++++++
>
> +      <li>
> +        Default fields widths can be used for <code>I</code>, <code>F</code>
> +        and <code>G</code> format specifiers when excplicit widths are omitted.
> +        Use the option <code>-fdec-format-defaults</code>, this options is implied
> +        with <code>-fdec</code>.
> +      </li>

Typo: excplicit. I had to read it twice and look at the manual: The 
options permits to use I/F/G data-edit descriptors** without specifying 
a number (a width) and then a default width is used. At the first 
reading, I wondered whether in the code or on the command line one 
specifies the default value.

Maybe the following is clearer:
"For formatted input/output, if the explicit widths after the data-edit 
descriptors <code>I</code>, <code>F</code> and <code>G</code> have been 
omitted, default widths are used."

Other wording suggestions are welcome.

> +      <li>
> +        A blank format item at the end of a format specification i.e. nothing
> +        following the final comma is allowed.  Use the option
> +        <code>-fdec-blank-format-item</code>, this options is implied with
> +        <code>-fdec</code>.
> +      </li>
(I personally would add a comma before 'i.e.' and 'is allowed' – but 
commas are a rather personal affair.*)
> +    <li>
> +      Character type names in errors and warnings now include <code>len</code>
> +      in addition to <code>kind</code>, <code>*</code> is used for assumed
> +      length. The kind is omitted if it the default kind. Examples:
> +      <code>CHARACTER(12)</code>, <code>CHARACTER(6,4)</code>.

I'd use a semicolon instead of a comma before "* is used for". And add 
an 'is' after 'if it'.

Otherwise, it looks good to me.

Tobias

*Cf. https://www.newyorker.com/magazine/2015/02/23/holy-writ
** data-edit-desc is the wording used by the Fortran standard; but I 
don't think its name makes it immediately clear what is meant.

Corrected and committed.

On 27/11/2019 09:00, Tobias Burnus wrote:
> On 11/26/19 7:33 PM, Mark Eggleston wrote:
>>   htdocs/gcc-10/changes.html | 41 
>> +++++++++++++++++++++++++++++++++++++++++
>>
>> +      <li>
>> +        Default fields widths can be used for <code>I</code>, 
>> <code>F</code>
>> +        and <code>G</code> format specifiers when excplicit widths 
>> are omitted.
>> +        Use the option <code>-fdec-format-defaults</code>, this 
>> options is implied
>> +        with <code>-fdec</code>.
>> +      </li>
>
> Typo: excplicit. I had to read it twice and look at the manual: The 
> options permits to use I/F/G data-edit descriptors** without 
> specifying a number (a width) and then a default width is used. At the 
> first reading, I wondered whether in the code or on the command line 
> one specifies the default value.
>
> Maybe the following is clearer:
> "For formatted input/output, if the explicit widths after the 
> data-edit descriptors <code>I</code>, <code>F</code> and 
> <code>G</code> have been omitted, default widths are used."
>
> Other wording suggestions are welcome.
>
>> +      <li>
>> +        A blank format item at the end of a format specification 
>> i.e. nothing
>> +        following the final comma is allowed.  Use the option
>> +        <code>-fdec-blank-format-item</code>, this options is 
>> implied with
>> +        <code>-fdec</code>.
>> +      </li>
> (I personally would add a comma before 'i.e.' and 'is allowed' – but 
> commas are a rather personal affair.*)
>> +    <li>
>> +      Character type names in errors and warnings now include 
>> <code>len</code>
>> +      in addition to <code>kind</code>, <code>*</code> is used for 
>> assumed
>> +      length. The kind is omitted if it the default kind. Examples:
>> +      <code>CHARACTER(12)</code>, <code>CHARACTER(6,4)</code>.
>
> I'd use a semicolon instead of a comma before "* is used for". And add 
> an 'is' after 'if it'.
>
> Otherwise, it looks good to me.
>
> Tobias
>
> *Cf. https://www.newyorker.com/magazine/2015/02/23/holy-writ
> ** data-edit-desc is the wording used by the Fortran standard; but I 
> don't think its name makes it immediately clear what is meant.
>

On 27/11/2019 08:29, Tobias Burnus wrote:
> On 11/27/19 8:58 AM, Janne Blomqvist wrote:
>> On Tue, Nov 26, 2019 at 1:12 PM Tobias Burnus 
>> <tobias@codesourcery.com> wrote:
>>> AUTOMATIC attribute
>> Speaking of which, to avoid confusion maybe we should rename the
>> -f[no-]automatic option to something like -f[no-]save, since the
>> Fortran standard description of an "automatic data object" doesn't
>> really have anything to do with the option, and neither does the
>> option have anything to do specifically with the DEC AUTOMATIC
>> specifier?

-fno-automatic means that all local variables are saved however a local 
variable can still be automatic if it explicitly has the AUTOMATIC 
attribute, this is only possible with -fdec-static/-fdec, it is not 
possible in standard fortran, SAVE equates to STATIC but there is no 
standard attribute that equates to AUTOMATIC.

regards

Mark

>
> While in principle I concur that the naming is bad, I fear this will 
> break several makefiles – hence, I am not sure it is worth the trouble 
> – and I am declined to say that it isn't.
>
> Cheers,
>
> Tobias
>
>

On Tue, 26 Nov 2019, Mark Eggleston wrote:
> I've check the changes with W3 validator. There are no problems related 
> to my changes, however, it does object to the lack of character encoding 
> in the file. My knowledge of HTML is limited, so don't know how to fix 
> that.

Let me take this as good feedback and help make things a bit easier 
going forward. :-)

I just committed a patch a patch that added a
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
tag to all of our HTML files which, also in my own tests with
https://validator.w3.org, addresses what you have encountered.

Is there anything else we can do to make things easier?

Gerald

On Tue, 26 Nov 2019, Mark Eggleston wrote:
> Second attempt this time with attachment.

>From f884924877ba84578e75bd16cb127bab33eb5ee6 Mon Sep 17 00:00:00 2001
From: Mark Eggleston <markeggleston@codethink.com>
Date: Tue, 26 Nov 2019 10:12:44 +0000
Subject: [PATCH] Update Fortran changes

+      <li>
+        A blank format item at the end of a format specification i.e. nothing
+        following the final comma is allowed.  Use the option
+        <code>-fdec-blank-format-item</code>, this options is implied with
+        <code>-fdec</code>.
+      </li>

The second sentence is a bit confusing.  "Use the option" ... "this
option is implied"?

When/why to use this option?

How does the implication come into play?

In any case "this option is" (singular)

Same below.


I have applied the patch below for now to address some of the above;
please feel free to go ahead with further changes.

Thanks,
Gerald


diff --git a/htdocs/gcc-10/changes.html b/htdocs/gcc-10/changes.html
index de550813..f0f0d312 100644
--- a/htdocs/gcc-10/changes.html
+++ b/htdocs/gcc-10/changes.html
@@ -219,21 +219,21 @@ a work-in-progress.</p>
       <li>
         A blank format item at the end of a format specification, i.e. nothing
         following the final comma, is allowed.  Use the option
-        <code>-fdec-blank-format-item</code>, this options is implied with
+        <code>-fdec-blank-format-item</code>; this option is implied with
         <code>-fdec</code>.
       </li>
       <li>
         The existing support for <code>AUTOMATIC</code> and <code>STATIC</code>
         attributes has been extended to allow variables with the
         <code>AUTOMATIC</code> attribute to be used in <code>EQUIVALENCE</code>
-        statements. Use <code>-fdec-static</code>, this option is implied by
+        statements. Use <code>-fdec-static</code>; this option is implied by
         <code>-fdec</code>.
       </li>
       <li>
         Allow character literals in assignments and <code>DATA</code> statements
         for numeric (<code>INTEGER</code>, <code>REAL</code>, or
         <code>COMPLEX</code>) or <code>LOGICAL</code> variables.  Use the option
-        <code>-fdec-char-conversions</code>, this options is implied with
+        <code>-fdec-char-conversions</code>; this option is implied with
         <code>-fdec</code>.
       </li>
       <li>