updates on the GDB online documentation

[Joel Brobecker <brobecker at adacore dot com>]

Hello everyone,

I am planning on committing a change that will have a slight effect
on the way the HTML version of the GDB documentation is generated.
Without going into too many details, the standard way of building
the HTML documentation is by using makeinfo.  But for some reason,
we generate the documentation on our website using texi2html.
Doug Evans remarked that one of the issues with the texi2html is that
it uses numbers in its URLs, making the URLs unstable over time.
For instance:

    http://www.sourceware.org/gdb/current/onlinedocs/gdb_5.html#SEC21

Switching back to using makeinfo will improve the situation, as
the HTML files are now named using the node name, or the chapter/name
section (not sure which):

    Automatic-Overlay-Debugging.html

I will try to commit this change tomorrow.

Regarding the lack of index/table-of-contents in the GDB documentation,
it looks like an issue with the texinfo tools on the machine where
the documentation is generated. I sent an email to overseers about that.
Hopefully we'll get to the bottom of this.

A couple of separate issues, that can be handled independenly:

  1. I think that the way the online documentation is organized is
     confusing.  More precisely, I find the location of the documentation
     to be confusing.

       HEAD docs    -> gdb/current/onlinedocs
       BRANCH docs  -> gdb/onlinedocs
       RELEASE docs -> download/onlinedocs

     How about a different organization, something like this:

       HEAD docs    -> onlinedocs/current or onlinedocs/head
       BRANCH docs  -> onlinedocs/branch
       RELEASE docs -> onlinedocs/release or onlinedocs/released
                       or onlinedocs/last-release

     I don't think that the name of the directory where the docs are
     stored is extrement important, as long as the text that leads
     to them is.

  2. That brings me to my next topic: Actually, I'll discuss that
     separately, as I think it will need a little bit of dicussion.
     I don't want to mix everything too much.

-- 
Joel