From: ludo@gnu.org (Ludovic Courtès)
To: Andreas Enge <andreas@enge.fr>
Cc: guix-devel@gnu.org
Subject: Re: Manual structure
Date: Sun, 06 Mar 2016 15:05:08 +0100 [thread overview]
Message-ID: <87fuw3r9bf.fsf@gnu.org> (raw)
In-Reply-To: <20160305154245.GA25307@solar> (Andreas Enge's message of "Sat, 5 Mar 2016 16:42:45 +0100")
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’.
prev parent reply other threads:[~2016-03-06 14:05 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-03-05 15:42 Manual structure Andreas Enge
2016-03-06 4:17 ` myglc2
2016-03-06 14:05 ` Ludovic Courtès [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fuw3r9bf.fsf@gnu.org \
--to=ludo@gnu.org \
--cc=andreas@enge.fr \
--cc=guix-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).