Re: [bug-gsrc] Documentation: Table of contents and Detailed node listing have different layouts

[Brandon Invergo]

Hi Christophe,

> According to GSRC 2013.10.06 documentation available at
> http://www.gnu.org/software/gsrc/manual/html_node/index.html, the
> table of contents and the detailed node listing of GSRC manual differ
> on the following parts:
>
> * Table of contents:
>
>     Appendix A Technical information
>         A.1 The GSRC build system
>         A.2 Anatomy of a GSRC Makefile
>             A.2.1 Metadata variables
>             A.2.2 Build variables
>             A.2.3 Build recipes
>             A.2.4 A simple example
>             A.2.5 A complex example
>
> * Detailed node listing:
>
> Technical information
>
> • The GSRC build system:
> • Anatomy of a GSRC Makefile:
>
> Anatomy of a GSRC Makefile
>
> • Metadata variables:
> • Build variables:
> • Build recipes:
> • A simple example:
> • A complex example:

This is correct (and in fact, these menus were automatically generated
by the texinfo mode for Emacs that is distributed with texinfo).  The
detailed node listing lists the sub-nodes of each node.  So, first, the
sub-nodes of the chapter "Technical information" are listed, and then
the sub-nodes of section "Anatomy of a GSRC Makefile" are listed.  

On the HTML version of the manual (also generated automatically via an
official GNU script), the detailed node listing isn't really useful,
since the main table of contents supports nested items.  If you view the
documentation in the info reader, however, you see this:

    * Menu:
    
    * Introduction::
    * Getting started::
    * Advanced configuration::
    * Technical information::
    * GNU Free Documentation License::
    
     -- The Detailed Node Listing --
    
    Introduction
    
    * Building GNU packages::
    
    (etc.)

Only the top-level chapter names are listed in the main menu.  By
including the detailed node listing, all the section and sub-section
titles can easily be seen from the top-level page in the info reader,
which otherwise wouldn't be possible.

> Moreover, I think that "Technical information" should be a chapter
> instead of an appendix.

I disagree.  The average user of GSRC, no matter how technically
knowledgeable they may be, does not need to know about the inner details
of the system to use it.  That information is primarily useful for
anyone else who may be adding/maintaining packages in GSRC.  I wrote it
and included it in the main documentation because, when I took over
maintenance of GSRC, I had to dig up ancient documentation on GAR and to
read the GSRC source code to figure out exactly how everything was
working.  I figured that if anyone ever started helping out or if, for
whatever reason, I had to step down as maintainer, having such
documentation readily available would be useful.

However, since for most people that chapter might only satisfy curiosity
and does not assist in the usage of the system, it should only be an
appendix.  Including it as a chapter might incorrectly imply that it is
necessary to read and understand it before using GSRC.

Cheers,
Brandon

-- 
Brandon Invergo
http://brandon.invergo.net

pgpnVMvH9YACS.pgp
Description: PGP signature