Manual structure

Manual structure

[Andreas Enge]

Hello,

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)
I did not think about 8 and where it belongs.

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.
- Move 7.1 and 7.2 to new chapters 8 and 9.

What do you think?

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.

Andreas

Re: Manual structure

[myglc2]

Andreas Enge <andreas@enge.fr> writes:
[...]
> 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.
> - Move 7.1 and 7.2 to new chapters 8 and 9.
>
> What do you think?

Great idea. While you are at it, please consider additional changes to
reorganize sections by package management vs system configuration and
users vs coders, perhaps along the lines shown below. Current section
numbers in ()'s.

* GNU GUIX Ref Man

** intro (1)

** Using Guix package management (3.1)
*** Installation
**** from Binary (2.1)
**** from Source (2.2, 2.3, 2.4, 2.5)
*** Package Management
**** Application Setup (2.6)
**** Package Management (3, 7.4)

** Using Guix System Distribution (7)
*** Installation
**** By USB (7.1)
**** Converting Guix to GuixSD (TK)
*** System Configuration (7.2)

** Using Guix Commands (6, 7.2.13)

** Using the Guix in Emacs (4)

** Coding in Guix
*** Building from Git (8.1, 8.2, 8.3)
*** programming interface (5)
*** packaging guidelines (7.5, 7.6)
*** system configuration (7.7, 7.8)
*** submitting code (8.4, 8.5)
*** debugging (7.3)

** acknowledgements
** appendix
** concept index
** programming index
** glossary (TK)

Re: Manual structure

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