GNU bug report logs - #53287
[PATCH] doc: Document the documentation process.

Previous Next

Full log

View this message in rfc822 format

From: Ludovic Courtès <ludo <at> gnu.org>
To: jgart <jgart <at> dismail.de>
Cc: 53287 <at> debbugs.gnu.org
Subject: [bug#53287] [PATCH] doc: Document the documentation process.
Date: Fri, 21 Jan 2022 22:06:25 +0100

Hi!

jgart <jgart <at> dismail.de> skribis:

> * doc/contributing.texi (Contributing): Add documentation documentation.
>
> Co-authored-by: jgart <jgart <at> dismail.de>
> Julien Lepiller <julien <at> lepiller.eu>
> Matt Trzcinski <matt <at> excalamus.com>
> Fabio Natali <me <at> fabionatali.com>
> Gabor Boskovits <boskovits <at> gmail.com>

That’s a much welcome addition!

Overall it LGTM.  I have minor comments to complement what zimoun
already wrote:

> --- a/doc/contributing.texi
> +++ b/doc/contributing.texi
> @@ -30,6 +30,7 @@ choice.
>  * Commit Access::               Pushing to the official repository.
>  * Updating the Guix Package::   Updating the Guix package definition.
>  * Translating Guix::            Make Guix speak your native language.
> +* Documenting Guix::            Improving documentation in GNU Guix.
>  @end menu

I’d move this section before “Translating Guix” because that
conceptually happens before.

Note that you need to add the line above also in the other menus that
show this section.  In Emacs that’s M-x texinfo-all-menus-update I
think, but otherwise you can copy/paste it by hand…  (Menus are one of
the bad things of Texinfo.)

Last, how about changing the title to “Writing Documentation” or
something along these lines?  (In general I like to not repeat “Guix”
everywhere because it’s implicit.)

> +Guix is documented using the Texinfo system.  However, if you are not

I’d remove “However”.

> +To modify the documentation, you need to edit @file{doc/guix.texi} and
> +@file{doc/contributing.texi} (which contains this documentation
> +section), or @file{doc/guix-cookbook.texi} for the cookbook.  If
> +you compiled the Guix repository before, you will have
> +many more @file{.texi} files that are translations of these
> +documents.  Do not modify them, the translation is managed through
> +@uref{https://translate.fedoraproject.org/projects/guix, Weblate},

Replace comma with a period…

> +@pxref{Translating Guix} for more information.

… and pxref with xref.

> +To render your documentation changes, we recommend to execute one of
> +the following commands:

What about:

  To render documentation, you must first make sure that you ran
  @command{./configure} in your source tree (@pxref{Running Guix Before
  It Is Installed}).  After than you can run one of the following
  commands:

?

> +@itemize
> +@item @samp{make doc/guix.info} to compile the info manual.

s/info manual/Info manual/

> +@item @samp{make doc/guix-cookbook.info} for the cookbook info manual.

Likewise.

Could you send an updated patch?

Thumbs up to everyone who participated in this meetup!

Ludo’.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.