This is the mail archive of the gdb@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Thoughts on the GDB "documentation" web page


This is regarding: http://www.sourceware.org/gdb/documentation/

I find the "documentations page" not as straightforward as I'd like it
to be.  In particular, the "Online GDB Manuals" sections, which looks
like this:

     |  Online GDB manuals
     |  Documentation generated from the <URL: current_cvs>current</URL> 
     |  sources are available online:
     |
     |  <URL: GDB TOC>GDB User Manual<URL> (<URL: PDF>gziped</URL> PDF)
     |      Describes how to use GDB.
     |      Translations are also available:
     |        * Japanese, by Kazuhisa Ichikawa as part of KI's
     |          Unofficial GNU Manual Translation Project.
     |        * Russian, by Dmitry Sivachenko.
     |
     |  <URL: GDB Internals TOC>GDB Internals Manual</URL> (gziped PDF)
     |      Technical details of the internals of GDB.
     |
     |  The documentation is also available for <URL: head-onlinedocs>
     |  download</URL> in a number of different formats including (HTML,
     |  DVI, PS and PDF).
     |
     |  Versions of the documentation generated from the last 
     |  <URL:release-onlinedocs>release</URL> and most recent 
     |  <URL:branch-onlinedocs>branch</URL> are also available.

    What I find confusing is how to get to the "onlinedocs" page
    for the HEAD.  It takes careful reading every single time I go
    to that page to find the link (clicking on "download").  Similarly,
    it takes careful reading to find where the release and branch
    documentation is located.  It would be nice to make everything 
    a little more structured.

I would like to reorganize this a little.  Here is what the entire
page looks like, right now:

    |           GDB Documentation
    |
    |   Printed Manuals
    |   <one-line explaining how to get printed manuals from the GNU Press>
    |
    |   Online GDB Manuals
    |   <see above>
    |
    |   Reference Materials
    |   Additional documentation includes:
    |   [...]
    |
    |   GDB interfaces and standards
    |   [...]

I am not sure I have been able to come up with anything better, so
suggestions always welcome.  Here is what I propose. Revamp the page
as follow:

    |                  GDB Documentation
    |
    |    <URL>GDB User Manual</URL>    <URL>GDB Internals Manual</URL>
    |    (gzipped <URL>PDF</URL>)      (gzipped <URL>PDF</URL>)
    |    Describes how to use GDB.     Technical details of the internals
    |                                  of GDB.
    |
    |    Online GDB Documentation
    |    GDB provides a set of documents (including manuals) that are
    |    available from the links below:
    |      * For the <URL>last release</URL>
    |      * For the <URL>head branch</URL>
    |      * For the currently active <URL>branch</URL>
    |
    |    Printed Manuals
    |    <contents unchanged>
    |
    |    Translated manuals
    |    Translations of the GDB manual are also available:
    |      [...]

Thoughts?



-- 
Joel


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]