From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gdb-return-36239-listarch-gdb=sources.redhat.com@sourceware.org>
Received: (qmail 28158 invoked by alias); 9 Nov 2009 17:44:53 -0000
Received: (qmail 28150 invoked by uid 22791); 9 Nov 2009 17:44:52 -0000
X-SWARE-Spam-Status: No, hits=-1.7 required=5.0 	tests=AWL,BAYES_05
X-Spam-Check-By: sourceware.org
Received: from rock.gnat.com (HELO rock.gnat.com) (205.232.38.15)     by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Mon, 09 Nov 2009 17:44:44 +0000
Received: from localhost (localhost.localdomain [127.0.0.1]) 	by filtered-rock.gnat.com (Postfix) with ESMTP id 3788C2BAC4E 	for <gdb@sourceware.org>; Mon,  9 Nov 2009 12:44:43 -0500 (EST)
Received: from rock.gnat.com ([127.0.0.1]) 	by localhost (rock.gnat.com [127.0.0.1]) (amavisd-new, port 10024) 	with LMTP id SJGjC7ZJDwcv for <gdb@sourceware.org>; 	Mon,  9 Nov 2009 12:44:43 -0500 (EST)
Received: from joel.gnat.com (localhost.localdomain [127.0.0.1]) 	by rock.gnat.com (Postfix) with ESMTP id EEB072BAC19 	for <gdb@sourceware.org>; Mon,  9 Nov 2009 12:44:42 -0500 (EST)
Received: by joel.gnat.com (Postfix, from userid 1000) 	id 6F2F2F5905; Mon,  9 Nov 2009 09:44:27 -0800 (PST)
Date: Mon, 09 Nov 2009 18:48:00 -0000
From: Joel Brobecker <brobecker@adacore.com>
To: gdb@sourceware.org
Subject: Thoughts on the GDB "documentation" web page
Message-ID: <20091109174427.GR22192@adacore.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.18 (2008-05-17)
Mailing-List: contact gdb-help@sourceware.org; run by ezmlm
Precedence: bulk
List-Id: <gdb.sourceware.org>
List-Subscribe: <mailto:gdb-subscribe@sourceware.org>
List-Archive: <http://sourceware.org/ml/gdb/>
List-Post: <mailto:gdb@sourceware.org>
List-Help: <mailto:gdb-help@sourceware.org>, <http://sourceware.org/ml/#faqs>
Sender: gdb-owner@sourceware.org
X-SW-Source: 2009-11/txt/msg00095.txt.bz2

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