[wwwdocs, patch] gcc-4.9/changes.html: Add quip about "#pragma GCC ivdep" and update Fortran section

[wwwdocs, patch] gcc-4.9/changes.html: Add quip about "#pragma GCC ivdep" and update Fortran section

[Tobias Burnus]

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

Dear Gerald, dear all,

the patch adds a quip about the new "#pragma GCC ivdep" to the release 
notes. Additionally, I updated the Fortran section based on the changes 
accumulated on http://gcc.gnu.org/wiki/GFortran#news

Any comments? Or is the patch OK?

Tobias

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

Index: htdocs/gcc-4.9/changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.9/changes.html,v
retrieving revision 1.28
diff -u -p -r1.28 changes.html
--- htdocs/gcc-4.9/changes.html	3 Oct 2013 14:15:36 -0000	1.28
+++ htdocs/gcc-4.9/changes.html	24 Oct 2013 19:44:28 -0000
@@ -84,6 +84,13 @@
 
     <b>test.C:2:46:</b> <b style='color:red'>error:</b> incomplete type &lsquo;<b>X&lt;100&gt;</b>&rsquo; used in nested name specifier
     </pre></li>
+
+    <li>With the new <a
+    href="http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html"
+    ><code>#pragma GCC ivdep</code></a>, the user can assert that there are no
+    loop-carried dependencies which would prevent that consecutive iterations of
+    the following loop can be executed concurrently with SIMD (single instruction
+    multiple data) instructions.</li>
   </ul>           
 
 <!--
@@ -173,13 +180,18 @@ void f(int n) {
           trying to mix old code with new code will usually give an error
           message.)</li>
       </ul></li>
+      <li>GNU Fortran no longer deallocates allocatable variables or
+        allocatable components of variables declared in the main program. The
+        Fortran standard states since 2008 explicitly that variables declared
+        in the Fortran main program automatically have the <code>SAVE</code>
+        attribute.</li>
     </ul></li>
     <li>The deprecated command-line option <code>-fno-whole-file</code>
       has been removed. (<code>-fwhole-file</code> is the default since
       GCC 4.6.) <code>-fwhole-file</code>/<code>-fno-whole-file</code>
       continue to be accepted but do not influence the code generation.</li>
     <li>The compiler no longer unconditionally warns
-      about <code>DO</code>loops with zero iterations.  This warning is now
+      about <code>DO</code> loops with zero iterations.  This warning is now
       controlled by the <code>-Wzerotrips</code> option, which is implied by
       <code>-Wall</code>.</li>
     <li>The new <code>NO_ARG_CHECK</code> attribute of the <a

Re: [wwwdocs, patch] gcc-4.9/changes.html: Add quip about "#pragma GCC ivdep" and update Fortran section

[Gerald Pfeifer]

Hi Tobias,

On Thu, 24 Oct 2013, Tobias Burnus wrote:
> Any comments? Or is the patch OK?

thanks for doing this.

Index: htdocs/gcc-4.9/changes.html
===================================================================
+    <li>With the new <a
+    href="http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html"
+    ><code>#pragma GCC ivdep</code></a>, the user can assert that there are no
+    loop-carried dependencies which would prevent that consecutive iterations of
+    the following loop can be executed concurrently with SIMD (single instruction
+    multiple data) instructions.</li>

That would flow a bit nicer if you say "...prevent concurrent execution 
of consecutive iterations using..." or something like that, I believe? 

+        allocatable components of variables declared in the main program. The
+        Fortran standard states since 2008 explicitly that variables declared
+        in the Fortran main program automatically have the <code>SAVE</code>
+        attribute.</li>

How about "Since 2008 the Fortran standard..." or "Fortran 2008 and later 
standards..." ?

+      about <code>DO</code> loops with zero iterations.  This warning is now

Good catch!

The patch looks good if you consider my comments (which is not 
necessarily the same as following all of them ;-).

Gerald

Re: [wwwdocs, patch] gcc-4.9/changes.html: Add quip about "#pragma GCC ivdep" and update Fortran section

[Tobias Burnus]

Gerald Pfeifer wrote:
> On Thu, 24 Oct 2013, Tobias Burnus wrote:
>> Any comments? Or is the patch OK?
> thanks for doing this.

Thanks for looking at the patch. However, the patch has a link problem. 
The documentation is at
    http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html

That's also the link I use in the changes.html file. However, some 
script changes the link to:
    http://gcc.gnu.org/onlinedocs/gcc/Loop-Specific-Pragmas.html
which won't work. Try yourself at http://gcc.gnu.org/gcc-4.9/changes.html


Actually, a similar issue was reported at 
http://gcc.gnu.org/ml/gcc-help/2013-10/msg00132.html

Does anyone know which script modifies those links?

Tobias

wwwdocs: Broken links due to the preprocess script (was: Re: [wwwdocs, patch] gcc-4.9/changes.html: Add quip about "#pragma GCC ivdep" and update Fortran section)

[Tobias Burnus]

Tobias Burnus wrote:
> Thanks for looking at the patch. However, the patch has a link 
> problem. The documentation is at
> http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html
>
> That's also the link I use in the changes.html file. However, some 
> script changes the link to:
>    http://gcc.gnu.org/onlinedocs/gcc/Loop-Specific-Pragmas.html
> which won't work. Try yourself at http://gcc.gnu.org/gcc-4.9/changes.html
>
>
> Actually, a similar issue was reported at 
> http://gcc.gnu.org/ml/gcc-help/2013-10/msg00132.html

The reason for the broken links are the following lines in the 
/www/bin/preprocess script: 
http://gcc.gnu.org/cgi-bin/cvsweb.cgi/wwwdocs/bin/preprocess.diff?r1=1.38&r2=1.39&f=h

Gerald, do you still know why you added it 9 years ago? The commit 
comment is "Use sed to work around makeinfo 4.7 brokenness."

I think "makeinfo" is still broken, but those pages do not seem to go 
through the preprocess script, which means that only links to that page 
will change to a hyphen, breaking the links.

Do you think it would be sensible to remove those lines again - or, 
alternatively, to run a similar script (e.g. "perl -i -e 's/_002d/-/g' 
`find onlinedocs -name \*.html`) on the onlinedocs/.

I think the impact of the the former on links is smaller. (One still 
needs to re-run the script on those files to restore the links.)

Tobias

*ping* Re: wwwdocs: Broken links due to the preprocess script

[Tobias Burnus]

On October 25, 2013 22:32, Tobias Burnus wrote:
> Tobias Burnus wrote:
>> Thanks for looking at the patch. However, the patch has a link 
>> problem. The documentation is at
>> http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html
>>
>> That's also the link I use in the changes.html file. However, some 
>> script changes the link to:
>>    http://gcc.gnu.org/onlinedocs/gcc/Loop-Specific-Pragmas.html
>> which won't work. Try yourself at 
>> http://gcc.gnu.org/gcc-4.9/changes.html
>>
>>
>> Actually, a similar issue was reported at 
>> http://gcc.gnu.org/ml/gcc-help/2013-10/msg00132.html
>
> The reason for the broken links are the following lines in the 
> /www/bin/preprocess script: 
> http://gcc.gnu.org/cgi-bin/cvsweb.cgi/wwwdocs/bin/preprocess.diff?r1=1.38&r2=1.39&f=h
>
> Gerald, do you still know why you added it 9 years ago? The commit 
> comment is "Use sed to work around makeinfo 4.7 brokenness."
>
> I think "makeinfo" is still broken, but those pages do not seem to go 
> through the preprocess script, which means that only links to that 
> page will change to a hyphen, breaking the links.
>
> Do you think it would be sensible to remove those lines again - or, 
> alternatively, to run a similar script (e.g. "perl -i -e 's/_002d/-/g' 
> `find onlinedocs -name \*.html`) on the onlinedocs/.
>
> I think the impact of the the former on links is smaller. (One still 
> needs to re-run the script on those files to restore the links.)
>
> Tobias
>

Re: *ping* Re: wwwdocs: Broken links due to the preprocess script

[Gerald Pfeifer]

Working on it.  I hope to have a patch within the next 48 hours.

Gerald

Re: wwwdocs: Broken links due to the preprocess script

[Gerald Pfeifer]

Hi Tobias,

On Fri, 25 Oct 2013, Tobias Burnus wrote:
>> http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html
>> However, some script changes the link to:
>>    http://gcc.gnu.org/onlinedocs/gcc/Loop-Specific-Pragmas.html
>> which won't work. Try yourself at http://gcc.gnu.org/gcc-4.9/changes.html
>>
>> Actually, a similar issue was reported at
>> http://gcc.gnu.org/ml/gcc-help/2013-10/msg00132.html
> The reason for the broken links are the following lines in the
> /www/bin/preprocess script:
> http://gcc.gnu.org/cgi-bin/cvsweb.cgi/wwwdocs/bin/preprocess.diff?r1=1.38&r2=1.39&f=h
> 
> Gerald, do you still know why you added it 9 years ago? The commit 
> comment is "Use sed to work around makeinfo 4.7 brokenness."

yes, I do recall.

This was to work around a less then well advised change in makeinfo 
that replaced "-" in the local part of URLs by encoding it as "_002d".  
I firmly believe that this approach creates ugly and harder to use URLs 
for what I consider theoretical benefits only.

Cf. #alpha_002a_002d_002a_002d_002a vs  #alpha*-*-*, for a real example.

Here are some historical references

  http://gcc.gnu.org/ml/gcc/2004-09/msg00222.html
  http://gcc.gnu.org/ml/gcc/2004-09/msg00219.html

> I think "makeinfo" is still broken, but those pages do not seem to go 
> through the preprocess script, which means that only links to that page 
> will change to a hyphen, breaking the links.
> 
> Do you think it would be sensible to remove those lines again - or,
> alternatively, to run a similar script (e.g. "perl -i -e 's/_002d/-/g' `find
> onlinedocs -name \*.html`) on the onlinedocs/.

From all I can tell, we should do the latter, that is, ensure that our
other web pages (/onlinedocs) are adjusted properly as well.

And maintainer-scripts/update_web_docs_svn was supposed to do that,
alas I just realize it is only handling wwwdocs/htdocs, not what we
generate for /onlinedocs.

Below you'll find a patch for maintainer-scripts/update_web_docs_svn
which I tested on gcc.gnu.org and the current documentation pages (not 
those for older releases) are adjusted now.  

Among others this fixes the link you reported above (though adjusting
gcc-4.9/changes.html directly is now a logical next step).

Thoughts?

Gerald


2013-12-02  Gerald Pfeifer  <gerald@pfeifer.com> 
 
        * update_web_docs_svn: Work around makeinfo generated file names 
        and references with "_002d" instead of "-". 

Index: maintainer-scripts/update_web_docs_svn
===================================================================
--- update_web_docs_svn	(revision 205584)
+++ update_web_docs_svn	(working copy)
@@ -172,6 +172,19 @@
   fi
 done
 
+# Work around makeinfo generated file names and references with
+# "_002d" instead of "-".
+find . -name '*.html' | while read f; do
+  # Do this for the contents of each file.
+  sed -i -e 's/_002d/-/g' "$f"
+  # And rename files if necessary.
+  ff=`echo $f | sed -e 's/_002d/-/g'`;
+  if [ "$f" != "$ff" ]; then
+    printf "Renaming %s to %s\n" "$f" "$ff" 
+    mv "$f" "$ff"
+  fi
+done
+
 # Then build a gzipped copy of each of the resulting .html, .ps and .tar files
 for file in */*.html *.ps *.pdf *.tar; do
   cat $file | gzip --best > $file.gz

Re: wwwdocs: Broken links due to the preprocess script

[Tobias Burnus]

Gerald Pfeifer wrote:
> Below you'll find a patch for maintainer-scripts/update_web_docs_svn
> which I tested on gcc.gnu.org and the current documentation pages (not
> those for older releases) are adjusted now.
>
> Among others this fixes the link you reported above (though adjusting
> gcc-4.9/changes.html directly is now a logical next step).
>
> Thoughts?

Looks good to me. (I fully concur that the _002d is ugly.)

Tobias

Re: wwwdocs: Broken links due to the preprocess script

[Gerald Pfeifer]

On Mon, 2 Dec 2013, Tobias Burnus wrote:
> Looks good to me. (I fully concur that the _002d is ugly.)

Okay, so I applied this patch plus the one below to adjust 
gcc-4.9/changes.html accordingly.  (The first anchor there
is not stable, but for other reasons.)

Thanks for pushing for this fix!

Gerald


Index: gcc-4.9/changes.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/gcc-4.9/changes.html,v
retrieving revision 1.43
diff -u -3 -p -r1.43 changes.html
--- gcc-4.9/changes.html	30 Nov 2013 16:36:59 -0000	1.43
+++ gcc-4.9/changes.html	2 Dec 2013 21:42:24 -0000
@@ -110,7 +110,7 @@
   <ul>
     <li>Support for colorizing diagnostics emitted by GCC has been added.
     The <code><a
-    href="http://gcc.gnu.org/onlinedocs/gcc/Language-Independent-Options.html#index-fdiagnostics_002dcolor-239"
+    href="http://gcc.gnu.org/onlinedocs/gcc/Language-Independent-Options.html#index-fdiagnostics-color-246"
     >-fdiagnostics-color=auto</a></code> will enable it when
     outputting to terminals, <code>-fdiagnostics-color=always</code>
     unconditionally.  The <code>GCC_COLORS</code> environment variable
@@ -136,7 +136,7 @@
     </pre></li>
 
     <li>With the new <a
-    href="http://gcc.gnu.org/onlinedocs/gcc/Loop_002dSpecific-Pragmas.html"
+    href="http://gcc.gnu.org/onlinedocs/gcc/Loop-Specific-Pragmas.html"
     ><code>#pragma GCC ivdep</code></a>, the user can assert that there are no
     loop-carried dependencies which would prevent concurrent execution of
     consecutive iterations using SIMD (single instruction multiple data)

Re: wwwdocs: Broken links due to the preprocess script

[Tobias Burnus]

Gerald Pfeifer wrote:
> Okay, so I applied this patch plus the one below to adjust
> gcc-4.9/changes.html accordingly.  (The first anchor there
> is not stable, but for other reasons.)

But it should be sufficient to check them before the release and then 
one is fine as the links should refer to the released versions per 
item13 of http://gcc.gnu.org/releasing.html (that's why I proposed to 
add that item).


Talking about links like 
http://gcc.gnu.org/onlinedocs/gcc/Language-Independent-Options.html#index-fdiagnostics-color-246

What I always disliked that it doesn't linke to the @item 
"|-fdiagnostics-color[=WHEN]" but to the first paragraph after the 
@item. That makes somewhat sense if one looks at the source code:

@item -fdiagnostics-color[=@var{WHEN}]
@itemx -fno-diagnostics-color
@opindex fdiagnostics-color
@cindex highlight, color, colour
@vindex GCC_COLORS @r{environment variable}
Use color ...

Actually, it also makes sense if one reads the texi doc, 
http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Index-Entries 
: "||Index entries should precede the visible material that is being 
indexed. [...] ||Among other reasons, that way following indexing links 
(in whatever context) ends up before the material, where readers want to 
be, instead of after."


Thus, it seems as we should go through all of GCC's *texi files and swap 
the order of @item and @*index.

Tobias
|