mbox series

[bug#34156,0/4] Re-organize the manual

Message ID 20190121104741.14511-1-ludo@gnu.org
Headers show
Series Re-organize the manual | expand

Message

Ludovic Courtès Jan. 21, 2019, 10:47 a.m. UTC 
Hello Guix!

This is the great season cleanup of the manual.  I think it provides
a clearer view of what’s available.  Until now, the top-level chapters
were:

--8<---------------cut here---------------start------------->8---
* Introduction::                What is Guix about?
* Installation::                Installing Guix.
* Package Management::          Package installation, upgrade, etc.
* Programming Interface::       Using Guix in Scheme.
* Utilities::                   Package management commands.
* GNU Distribution::            Software for your friendly GNU system.
* Contributing::                Your help needed!
--8<---------------cut here---------------end--------------->8---

With these changes, that becomes:

--8<---------------cut here---------------start------------->8---
* Introduction::                What is Guix about?
* Installation::                Installing Guix.
* System Installation::         Installing the whole operating system.
* Package Management::          Package installation, upgrade, etc.
* Programming Interface::       Using Guix in Scheme.
* Utilities::                   Package management commands.
* System Configuration::        Configuring the operating system.
* Documentation::               Browsing software user manuals.
* Installing Debugging Files::  Feeding the debugger.
* Security Updates::            Deploying security fixes quickly.
* Bootstrapping::               GNU/Linux built from scratch.
* Porting::                     Targeting another platform or kernel.
* Contributing::                Your help needed!
--8<---------------cut here---------------end--------------->8---

Things about “the distro” in a broad sense are no longer hidden
under “GNU Distribution” and the introduction no longer ignores
Guix System.

Next up I’d like us to get rid of these catch-all “Utilities”
section and instead organize things by activities, such as
“Development”, “Distributing Substitutes”, and “Managing Storage
Space”.

Later I’d like to move each chapter to its own .texi file, which
will be nicer and will help Emacs build menus (currently it’s
confused because only one chapter leaves in a separate file.)

Thoughts?

Ludo’.

Ludovic Courtès (4):
  doc: Move sections under "GNU Distribution" one level higher.
  doc: Move "System Installation" right after "Installation".
  doc: Move "Packaging Guidelines" under "Contributing".
  doc: Move "Package Modules" under "Programming Interface".

 doc/contributing.texi |  450 ++++++++
 doc/guix.texi         | 2254 ++++++++++++++++-------------------------
 2 files changed, 1336 insertions(+), 1368 deletions(-)

Comments

Ludovic Courtès Jan. 22, 2019, 10:20 p.m. UTC | #1 
Ludovic Courtès <ludo@gnu.org> skribis:

>   doc: Move sections under "GNU Distribution" one level higher.
>   doc: Move "System Installation" right after "Installation".
>   doc: Move "Packaging Guidelines" under "Contributing".
>   doc: Move "Package Modules" under "Programming Interface".

Ricardo and Julien were almost enthusiastic about this change on IRC
;-), so I’ve just pushed it.

Ludo’.
Ricardo Wurmus Jan. 23, 2019, 8:21 a.m. UTC | #2 
Ludovic Courtès <ludo@gnu.org> writes:

> Ludovic Courtès <ludo@gnu.org> skribis:
>
>>   doc: Move sections under "GNU Distribution" one level higher.
>>   doc: Move "System Installation" right after "Installation".
>>   doc: Move "Packaging Guidelines" under "Contributing".
>>   doc: Move "Package Modules" under "Programming Interface".
>
> Ricardo and Julien were almost enthusiastic about this change on IRC
> ;-), so I’ve just pushed it.

Yay, thanks for the work!