This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: updates on the GDB online documentation
- From: Pedro Alves <pedro at codesourcery dot com>
- To: gdb at sourceware dot org
- Cc: Joel Brobecker <brobecker at adacore dot com>
- Date: Mon, 9 Nov 2009 19:39:30 +0000
- Subject: Re: updates on the GDB online documentation
- References: <20091109173300.GQ22192@adacore.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