This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
updates on the GDB online documentation
- From: Joel Brobecker <brobecker at adacore dot com>
- To: gdb at sourceware dot org
- Date: Mon, 9 Nov 2009 09:33:00 -0800
- Subject: updates on the GDB online documentation
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