http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Gerald Pfeifer]

Working on the link consistency of the http://gcc.gnu.org, I ran into
a couple of links on the libstdc++ side that are in need of a bit love.
It would be great could one of you libstdc++ guys look into those.

http://gcc.gnu.org/onlinedocs/libstdc++/ext/parallel_mode.html

           * http://gcc.gnu.org/onlinedocs/libgomp
           --> trailing slash missing

http://gcc.gnu.org/onlinedocs/libstdc++/parallel_mode.html

           * http://gcc.gnu.org/onlinedocs/libgomp
           --> trailing slash missing

http://gcc.gnu.org/onlinedocs/libstdc++/faq.html

           * http://developer.kde.org/~sewardj/
           --> now at http://valgrind.org/

http://gcc.gnu.org/onlinedocs/libstdc++/api.html

           * http://fsf.org/
           -> http://www.fsf.org/

http://gcc.gnu.org/onlinedocs/libstdc++/faq.html

           * http://gcc.gnu.org/onlinedocs/17_intro/contribute.html
           * http://gcc.gnu.org/onlinedocs/18_support/howto.html
           * http://gcc.gnu.org/onlinedocs/19_diagnostics/howto.html
           * http://gcc.gnu.org/onlinedocs/21_strings/howto.html
           * http://gcc.gnu.org/onlinedocs/23_containers/howto.html
           * http://gcc.gnu.org/onlinedocs/debug.html
           * http://gcc.gnu.org/onlinedocs/ext/howto.html

Thanks,
Gerald

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Paolo Carlini]

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

Hi Gerald,
> Working on the link consistency of the http://gcc.gnu.org, I ran into
> a couple of links on the libstdc++ side that are in need of a bit love.
> It would be great could one of you libstdc++ guys look into those.
>   
Should be all fixed with the below, applied mainline and 4_3-branch.

Thanks for the heads up!
Paolo.

///////////////////

[-- Attachment #2: CL_doc --]
[-- Type: text/plain, Size: 280 bytes --]

2008-03-23  Paolo Carlini  <pcarlini@suse.de>

	* doc/xml/faq.xml: Fix various links.
	* doc/xml/api.xml: Likewise.
	* doc/xml/manual/parallel_mode.xml: Likewise.
	* doc/html/faq.html: Regenerate.
	* doc/html/api.html: Likewise.
	* doc/html/manual/bk01pt12ch31s03.html: Likewise.

[-- Attachment #3: patch_doc --]
[-- Type: text/plain, Size: 5587 bytes --]

Index: doc/xml/faq.xml
===================================================================
--- doc/xml/faq.xml	(revision 133462)
+++ doc/xml/faq.xml	(working copy)
@@ -130,8 +130,8 @@
   </question>
   <answer id="a-how">
     <para>
-    Here is <ulink url="../17_intro/contribute.html">a page devoted to
-    this topic</ulink>. Subscribing to the mailing list (see above, or
+    Here is <link linkend="appendix.contrib">a page devoted to
+    this topic</link>. Subscribing to the mailing list (see above, or
     the homepage) is a very good idea if you have something to
     contribute, or if you have spare time and want to
     help. Contributions don't have to be in the form of source code;
@@ -400,7 +400,7 @@
     <para>
       If the only functions from <filename>libstdc++.a</filename>
       which you need are language support functions (those listed in
-      <ulink url="../18_support/howto.html">clause 18</ulink> of the
+      <link linkend="manual.support">clause 18</link> of the
       standard, e.g., <function>new</function> and
       <function>delete</function>), then try linking against
       <filename>libsupc++.a</filename>, which is a subset of
@@ -785,13 +785,13 @@
     reason is that the state flags are <emphasis>not</emphasis> cleared
     on a successful call to open().  The standard unfortunately did
     not specify behavior in this case, and to everybody's great sorrow,
-    the <ulink url="../ext/howto.html#5">proposed LWG resolution in
-      DR #22</ulink> is to leave the flags unchanged.  You must insert a call
+    the <link linkend="manual.intro.status.bugs">proposed LWG resolution in
+      DR #22</link> is to leave the flags unchanged.  You must insert a call
     to <function>fs.clear()</function> between the calls to close() and open(),
     and then everything will work like we all expect it to work.
     <emphasis>Update:</emphasis> for GCC 4.0 we implemented the resolution
-    of <ulink url="../ext/howto.html#5">DR #409</ulink> and open() now calls
-    <function>clear()</function> on success!
+    of <link linkend="manual.intro.status.bugs">DR #409</link> and open() 
+    now calls <function>clear()</function> on success!
     </para> 
   </answer>
 </qandaentry>
@@ -895,7 +895,7 @@
     <para>
     More information, including how to optionally enable/disable the
     checks, is available
-    <ulink url="../19_diagnostics/howto.html#3">here</ulink>.
+    <link linkend="manual.diagnostics.concept_checking">here</link>.
     </para> 
   </answer>
 </qandaentry>
@@ -940,13 +940,13 @@
     <para>
     A few people have reported that the standard containers appear
     to leak memory when tested with memory checkers such as
-    <ulink url="http://developer.kde.org/~sewardj/">valgrind</ulink>.
+    <ulink url="http://valgrind.org/">valgrind</ulink>.
     The library's default allocators keep free memory in a pool
     for later reuse, rather than returning it to the OS.  Although
     this memory is always reachable by the library and is never
     lost, memory debugging tools can report it as a leak.  If you
     want to test the library for memory leaks please read
-    <ulink url="../debug.html#mem">Tips for memory leak hunting</ulink>
+    <link linkend="debug.memory">Tips for memory leak hunting</link>
     first.
     </para> 
   </answer>
@@ -961,7 +961,7 @@
   <answer id="a-list_size_on">
     <para>
     See
-    the <ulink url="../23_containers/howto.html#6">Containers</ulink>
+    the <link linkend="manual.containers">Containers</link>
     chapter.
     </para> 
   </answer>
@@ -981,7 +981,7 @@
     patches</ulink> that covers the procedure, but for libstdc++ you
     should also send the patch to our mailing list in addition to
     the GCC patches mailing list.  The libstdc++
-    <ulink url="../17_intro/contribute.html">contributors' page</ulink>
+    <link linkend="appendix.contrib">contributors' page</link>
     also talks about how to submit patches.
     </para>
     <para>
@@ -1237,8 +1237,8 @@
     The copy will take O(n) time and the swap is constant time.
     </para>
     <para>
-    See <ulink url="../21_strings/howto.html#6">Shrink-to-fit
-    strings</ulink> for a similar solution for strings.
+    See <link linkend="strings.string.shrink">Shrink-to-fit
+    strings</link> for a similar solution for strings.
     </para> 
   </answer>
 </qandaentry>
Index: doc/xml/api.xml
===================================================================
--- doc/xml/api.xml	(revision 133462)
+++ doc/xml/api.xml	(working copy)
@@ -15,7 +15,7 @@
       2008
     </year>
     <holder>
-      <ulink url="http://fsf.org">FSF
+      <ulink url="http://www.fsf.org/">FSF
       </ulink>
     </holder>
   </copyright>
Index: doc/xml/manual/parallel_mode.xml
===================================================================
--- doc/xml/manual/parallel_mode.xml	(revision 133462)
+++ doc/xml/manual/parallel_mode.xml	(working copy)
@@ -116,7 +116,7 @@
 <para>
   To use the libstdc++ parallel mode, compile your application with
   the compiler flag <constant>-D_GLIBCXX_PARALLEL -fopenmp</constant>. This
-  will link in <code>libgomp</code>, the GNU OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp">implementation</ulink>,
+  will link in <code>libgomp</code>, the GNU OpenMP <ulink url="http://gcc.gnu.org/onlinedocs/libgomp/">implementation</ulink>,
   whose presence is mandatory. In addition, hardware capable of atomic
   operations is mandatory. Actually activating these atomic
   operations may require explicit compiler flags on some targets

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Benjamin Kosnik]

Thanks Paolo for fixing up the links as requested by Gerald.

> Working on the link consistency of the http://gcc.gnu.org, I ran into
> a couple of links on the libstdc++ side that are in need of a bit
> love. It would be great could one of you libstdc++ guys look into
> those.

All the links your reference later in your email are actually dead
links, from the documentation pre-Docbook. IMHO they should not be part
of the libstdc++ online docs at all, but I don't know how to remove
them.

The current libstdc++ html docs are in the
sources here: gcc/libstdc++-v3/doc/html

I don't know what should be done about the gcc online web pages. You
can either remove the dead links, and just use the generated html
pages, or try to come up with some mapping between the old links and
the new layout.

best,
benjamin

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Gerald Pfeifer]

On Sun, 23 Mar 2008, Paolo Carlini wrote:
>> Working on the link consistency of the http://gcc.gnu.org, I ran into
>> a couple of links on the libstdc++ side that are in need of a bit love.
>> It would be great could one of you libstdc++ guys look into those.
> Should be all fixed with the below, applied mainline and 4_3-branch.

Thanks a lot, Paolo!  I'm going to run a new check later this month
and will let you guys know if we missed anything.

On Mon, 24 Mar 2008, Benjamin Kosnik wrote:
> All the links your reference later in your email are actually dead
> links, from the documentation pre-Docbook. IMHO they should not be part
> of the libstdc++ online docs at all, but I don't know how to remove
> them.

That should happen automatically, as far as I can tell, now that Paolo
has adjusted a number of links.  I'll keep an eye on it.

Gerald

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Benjamin Kosnik]

> > All the links your reference later in your email are actually dead
> > links, from the documentation pre-Docbook. IMHO they should not be
> > part of the libstdc++ online docs at all, but I don't know how to
> > remove them.
> 
> That should happen automatically, as far as I can tell, now that Paolo
> has adjusted a number of links.  I'll keep an eye on it.

No. 

I don't think I clearly explained this to you. For that, I am sorry.

From what I can tell, the links to libstdc++ documentation on the gcc
web site are generated from the gcc/libstdc++-v3/doc/html directory.
This is fine, I guess. But the problem is that when this directory
structure changed, none of the old files were deleted. Instead, we had
the old and new documents "live" in one directory. This is a bug.

On March 31, I moved all the old content into a director called
"dated." Or, at least all the stuff I could move: 

www/gcc/htdocs/onlinedocs/libstdc++/dated

is the repository for all the old docs. In addition, ext/pb_assoc
should be moved in to that as well, but I am lacking permissions to do
this. 

-benjamin

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Gerald Pfeifer]

On Wed, 9 Apr 2008, Benjamin Kosnik wrote:
> From what I can tell, the links to libstdc++ documentation on the gcc
> web site are generated from the gcc/libstdc++-v3/doc/html directory.
> This is fine, I guess. But the problem is that when this directory
> structure changed, none of the old files were deleted. Instead, we had
> the old and new documents "live" in one directory. This is a bug.

Yes, and no.  I think there are two issues here.  The one you are pointing 
out, the other the fact that we changed existing URLs (some of them old or 
"prominent" ones with external links towards them). 

I believe you have mostly addressed the first, and I'll try to help with
the second.

> On March 31, I moved all the old content into a director called
> "dated." Or, at least all the stuff I could move: 
> 
> www/gcc/htdocs/onlinedocs/libstdc++/dated
> 
> is the repository for all the old docs. In addition, ext/pb_assoc
> should be moved in to that as well, but I am lacking permissions to
> do this. 

I've moved ext/pb_assoc now.  Looking in the libstdc++ directory, there 
are a couple of further files/directories I'm not sure about:

  -rw-r--r--   1 bkoz     gcc   1862 Feb 12 20:27 bk02.html
  -rw-r--r--   1 gccadmin gcc    724 Apr 12 00:55 bk02.html.gz
  -rw-r--r--   1 bkoz     gcc   1821 Feb 12 20:27 bk03.html
  -rw-r--r--   1 gccadmin gcc    717 Apr 12 00:55 bk03.html.gz
  drwxr-sr-x   2 bkoz     gcc 114688 Feb 13 21:39 libstdc++-html.20080213
  drwxr-sr-x   2 bkoz     gcc 258048 Mar 26 06:05 libstdc++-html.20080326
  drwxr-sr-x   2 bkoz     gcc 237568 Jan 18 06:49 libstdc++-html-USERS-20080118

As part of addressing the second issue, I will commit the patch below
in a minute which adjust our internal links as well as redirecting all
external ones and bookmarks.

Gerald

Index: faq.html
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/faq.html,v
retrieving revision 1.205
diff -u -3 -p -r1.205 faq.html
--- faq.html	9 Sep 2007 17:38:18 -0000	1.205
+++ faq.html	12 Apr 2008 23:20:19 -0000
@@ -20,7 +20,7 @@ and the <a href="http://www.fortran.com/
 Information page</a>.</p>
 
 <p>Other GCC-related FAQs: 
-   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html">
+   <a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq.html">
      libstdc++-v3</a>, and 
    <a href="http://gcc.gnu.org/java/faq.html">GCJ</a>.</p>
 
Index: .htaccess
===================================================================
RCS file: /cvs/gcc/wwwdocs/htdocs/.htaccess,v
retrieving revision 1.23
retrieving revision 1.25
diff -u -3 -p -r1.23 -r1.25
--- .htaccess	12 Apr 2008 22:41:15 -0000	1.23
+++ .htaccess	12 Apr 2008 23:24:21 -0000	1.25
@@ -24,6 +24,7 @@ Redirect permanent /libstdc++/links.html
 Redirect permanent /onlinedocs/g77_news.html	http://gcc.gnu.org/onlinedocs/g77/News.html
 Redirect permanent /onlinedocs/g77_bugs.html	http://gcc.gnu.org/onlinedocs/g77/Trouble.html
 Redirect permanent /onlinedocs/g77/		http://gcc.gnu.org/onlinedocs/gcc-3.4.6/g77/
+Redirect permanent /onlinedocs/libstdc++/faq/index.html http://gcc.gnu.org/onlinedocs/libstdc++/faq.html
 
 Redirect permanent /c9xstatus.html		http://gcc.gnu.org/c99status.html
 Redirect permanent /cvswrite.html		http://gcc.gnu.org/svnwrite.html

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Gerald Pfeifer]

On Sun, 13 Apr 2008, Gerald Pfeifer wrote:
> Yes, and no.  I think there are two issues here.  The one you are pointing 
> out, the other the fact that we changed existing URLs (some of them old or 
> "prominent" ones with external links towards them). 
> 
> I believe you have mostly addressed the first, and I'll try to help with
> the second.

Some changes I have committed already or plan to commit shortly, but
there are some where I'd appreciate some help.

As a consequence of the restructuring of the libstdc++ documentation,
the following prominent links are broken.  Do you have current 
replacements for these?

  http://gcc.gnu.org/onlinedocs/libstdc++/parallel_mode.html
  http://gcc.gnu.org/onlinedocs/libstdc++/ext/parallel_mode.html
  http://gcc.gnu.org/onlinedocs/libstdc++/ext/tr1.html

Thanks,

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Benjamin Kosnik]

> I've moved ext/pb_assoc now.  Looking in the libstdc++ directory,
> there are a couple of further files/directories I'm not sure about:
> 
>   -rw-r--r--   1 bkoz     gcc   1862 Feb 12 20:27 bk02.html
>   -rw-r--r--   1 gccadmin gcc    724 Apr 12 00:55 bk02.html.gz
>   -rw-r--r--   1 bkoz     gcc   1821 Feb 12 20:27 bk03.html
>   -rw-r--r--   1 gccadmin gcc    717 Apr 12 00:55 bk03.html.gz
>   drwxr-sr-x   2 bkoz     gcc 114688 Feb 13 21:39

these are new, and part of the auto-generated html from the docbook xml
files. They should stay.

> libstdc++-html.20080213 drwxr-sr-x   2 bkoz     gcc 258048 Mar 26
> 06:05 libstdc++-html.20080326 drwxr-sr-x   2 bkoz     gcc 237568 Jan
> 18 06:49 libstdc++-html-USERS-20080118

These are just the latest doxygen files, ie things that
the "latest-doxgen" symlink finds.

We really only need what's current (ie, 20080326). (I was keeping some
of the older ones around because sometimes output changes depending on
doxygen version, and I wanted a quick way to check. However, the
20080328 version is correct.)

> As part of addressing the second issue, I will commit the patch below
> in a minute which adjust our internal links as well as redirecting all
> external ones and bookmarks.

Thanks!

-benjamin

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Benjamin Kosnik]

> Some changes I have committed already or plan to commit shortly, but
> there are some where I'd appreciate some help.

Sure.
 
> As a consequence of the restructuring of the libstdc++ documentation,
> the following prominent links are broken.  Do you have current 
> replacements for these?
> 
>   http://gcc.gnu.org/onlinedocs/libstdc++/parallel_mode.html
>   http://gcc.gnu.org/onlinedocs/libstdc++/ext/parallel_mode.html

http://gcc.gnu.org/onlinedocs/libstdc++/manual/parallel_mode.html

>   http://gcc.gnu.org/onlinedocs/libstdc++/ext/tr1.html

http://gcc.gnu.org/onlinedocs/libstdc++/manual/bk01pt01ch01.html#manual.intro.status.standard.tr1

Sadly, this link is pretty weak compared to the old one's simplicity.
Instead, I wanted this URL:

http://gcc.gnu.org/onlinedocs/libstdc++/manual/status_cxxtr1.html

(see doc/xml/manual/status_cxxtr1.xml's <?dbhtml
filename="standard_cxxtr1.html"?> markup. I don't know why this is not
working, probably due to the type of document (sec2)?)

-benjamin

Re: http://gcc.gnu.org/onlinedocs/libstdc++/ needs a bit of help

[Gerald Pfeifer]

On Fri, 18 Apr 2008, Benjamin Kosnik wrote:
>> libstdc++-html.20080213 drwxr-sr-x   2 bkoz     gcc 258048 Mar 26
>> 06:05 libstdc++-html.20080326 drwxr-sr-x   2 bkoz     gcc 237568 Jan
>> 18 06:49 libstdc++-html-USERS-20080118
> 
> These are just the latest doxygen files, ie things that
> the "latest-doxgen" symlink finds.
> 
> We really only need what's current (ie, 20080326). (I was keeping some
> of the older ones around because sometimes output changes depending on
> doxygen version, and I wanted a quick way to check. However, the
> 20080328 version is correct.)

I see a new version now.  Will it be okay to remove

  drwxr-sr-x   2 bkoz     gcc 114688 Feb 13 21:39 libstdc++-html.20080213
  drwxr-sr-x   2 bkoz     gcc 258048 Mar 26 06:05 libstdc++-html.20080326

and

  drwxr-sr-x   2 bkoz     gcc 237568 Jan 18 06:49 libstdc++-html-USERS-20080118

Do you see any chance to integrate the building of this documentation 
into the generation of the regular release-specific documentation and
perhaps have the documents under those subdirectories instead of having
this under libstdc++?  That would make things more consistent, but I do
not know how hard this will be.

Gerald