updates on the GDB online documentation

updates on the GDB online documentation

[Joel Brobecker]

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

Re: updates on the GDB online documentation

[Pedro Alves]

On Monday 09 November 2009 17:33:00, Joel Brobecker wrote:
> 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.

I don't object to this, but I want to note that IMO, this sidesteps
a more fundamental problem that is:

 1 - currently sources documentation is too prominent.
     People tend to link to current development sources, without
     realizing it, when they should be linking to a particular
     release's docs, and those should be stable forever (or as much
     as possible anyway), but aren't.

 2 - As I noted in the other email, an url like:

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

   , would never have this stableness problem, even if we switched
   docs of newer releases to makeinfo or whatever tool we find
   is better in 2020.  That is, an absolute "6.8", not
   "previous release" or some other non-absolute term.  If we do decide
   to keep older manuals up in the webpage (as I hope we do), we can't
   also assume that newer makeinfo/texinfo's grok older manuals
   correctly.  Note we shouldn't need that --- once a manual is
   upload, it should not need regenerating again.

-- 
Pedro Alves

Re: updates on the GDB online documentation

[Tom Tromey]

>>>>> "Pedro" == Pedro Alves <pedro@codesourcery.com> writes:

Pedro>  1 - currently sources documentation is too prominent.
Pedro>      People tend to link to current development sources, without
Pedro>      realizing it, when they should be linking to a particular
Pedro>      release's docs, and those should be stable forever (or as much
Pedro>      as possible anyway), but aren't.

FWIW, GCC does this nicely, see:

http://gcc.gnu.org/onlinedocs/

In particular it is nicely separated by version, with the development
docs at the end, where you're unlikely to click on them by mistake.

Tom

RE: updates on the GDB online documentation

[Marc Khouzam]

>  1 - currently sources documentation is too prominent.
>      People tend to link to current development sources, without
>      realizing it, when they should be linking to a particular
>      release's docs, and those should be stable forever (or as much
>      as possible anyway), but aren't.

I agree.

It took me a while to realize that my bookmark titled
"GDB documentation", was pointing to a 'live' document and not the latest GDB.
(I had created the bookmark when I was first starting to use GDB).

Marc

Re: updates on the GDB online documentation

[Joel Brobecker]

> 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.

OK - this part is taken care of.  This nicely simplified the script
in addition to allowing us to get rid of texi2html.  Documentation
for the head and branch have been regenerated.

I will work on the structure based on the recomendations I received
when I have a moment.

-- 
Joel