Re: Manual structure

[ludo@gnu.org (Ludovic Courtès)]

Andreas Enge <andreas@enge.fr> skribis:

> I would like to suggest moving some chapters and sections around in the
> manual. For keeping this short, I will refer to the section numbers.
> My main motivation are the four digits now denoting subsections in 7;
> this is an indication that we are putting too much into this chapter.
> Notice that this chapter, "GNU Distribution", has been introduced in the
> beginning to speak about the packages of Guix; now it is more concerned with
> GuixSD. Loosely speaking, I would like to strip off the highest level of 7
> and make subchapters of 7.1, 7.2 and so on.
>
> Moreover, I see the manual as having three big parts:
> - introduction (chapter 1, well, so is is rather small)
> - Guix (chapters 2-6 and 7.3-7.8)
> - GuixSD (chapters 7.1 and 7.2)

Texinfo allows the addition of “part pages” so we could use that (info
"(texinfo) @part").

> I did not think about 8 and where it belongs.

I think “Contributing” is fine as a top-level chapter.  Maybe we should
move it after the introduction though?  Or leave it where it is.

> Concretely, I suggest the following:
> - Rename "7.6 Packaging Guidelines" to "Packages", and move it one level up
>   between the current 6 and 7 as the new chapter 7. Somehow integrate 7.3 
>   to 7.8 here.

Sounds good.

> - Move 7.1 and 7.2 to new chapters 8 and 9.

(So 7.1 “System Installation” becomes a chapter on its own, and 7.2
“System Configuration” becomes the next chapter, right?)

Sounds good.

> Changing the layout is made more difficult by the fact that all menus
> are hand-coded; do I remember wrongly that this can be done automatically
> in texinfo? If yes, it would be easier to make such a change first.

Yes, menus are a bit of a pain.  Currently we keep them up-to-date with
Emacs’s functions.  Texinfo 6.1 can generate them with “@validatemenus
off” (info "(texinfo) Writing a Menu"), but without hints in menu
entries, which isn’t nice.

The difficulty in implementing the change will be to make sure that
nothing is lost.  That is, the commit that implements the change should
do nothing beyond s/@section/@chapter/ and related changes.

Once this is done, I’d like to have one file per chapter.

Anyway, this restructuring is long overdue, so thanks for giving it some
thoughts!  :-)

Ludo’.