From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Manual structure Date: Sun, 06 Mar 2016 15:05:08 +0100 Message-ID: <87fuw3r9bf.fsf@gnu.org> References: <20160305154245.GA25307@solar> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:57337) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1acZJ5-0006TV-2y for guix-devel@gnu.org; Sun, 06 Mar 2016 09:05:15 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1acZJ1-0006ZA-2u for guix-devel@gnu.org; Sun, 06 Mar 2016 09:05:15 -0500 In-Reply-To: <20160305154245.GA25307@solar> (Andreas Enge's message of "Sat, 5 Mar 2016 16:42:45 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Andreas Enge Cc: guix-devel@gnu.org Andreas Enge 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 w= ith > 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 =E2=80=9Cpart pages=E2=80=9D so we could use= that (info "(texinfo) @part"). > I did not think about 8 and where it belongs. I think =E2=80=9CContributing=E2=80=9D is fine as a top-level chapter. May= be 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= =20 > to 7.8 here. Sounds good. > - Move 7.1 and 7.2 to new chapters 8 and 9. (So 7.1 =E2=80=9CSystem Installation=E2=80=9D becomes a chapter on its own,= and 7.2 =E2=80=9CSystem Configuration=E2=80=9D 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=E2=80=99s functions. Texinfo 6.1 can generate them with =E2=80=9C@va= lidatemenus off=E2=80=9D (info "(texinfo) Writing a Menu"), but without hints in menu entries, which isn=E2=80=99t 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=E2=80=99d like to have one file per chapter. Anyway, this restructuring is long overdue, so thanks for giving it some thoughts! :-) Ludo=E2=80=99.