Re: updates on the GDB online documentation

[Pedro Alves <pedro at codesourcery dot com>]

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