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

[christophe . jarry]

> 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.

Ok.

> 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.

Ok.

> 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.

Ok, thanks for those explanations.

Cheers,

Christophe