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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 53287 in the body.
You can then email your comments to 53287 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: guix-patches <at> gnu.org
Cc: Guix Together <jgart <at> dismail.de>
Subject: [PATCH] doc: Document the documentation process.
Date: Sat, 15 Jan 2022 13:08:48 -0500

From: Guix Together <jgart <at> dismail.de>

* 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>
---

Hi Guixers,

Here is our work from today's documentation meetup.

all best,

 doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9f97788c0b..101b693412 100644
--- 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
 
 @node Building from Git
@@ -1905,3 +1906,43 @@ differs for the various components.
       be updated accordingly (see @file{website/i18n-howto.txt} for more
       information on the process).
 @end itemize
+
+@cindex documentation
+@node Documenting Guix
+@section Documenting Guix
+
+Guix is documented using the Texinfo system.  However, if you are not
+yet familiar with it, we accept contributions for documentation in most
+formats.  That includes plain text, markdown, org-mode, etc...
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}.  Prepend @code{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above.  @xref{Submitting Patches} for more information on
+how to send your patches.
+
+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},
+@pxref{Translating Guix} for more information.
+
+To render your documentation changes, we recommend to execute one of
+the following commands:
+
+@itemize
+@item @command{make doc/guix.info} to compile the info manual.
+      You can check it with @command{info doc/guix.info}.
+@item @command{make doc/guix.html} to compile the HTML version.
+      You can point your browser to the relevant file in the
+      @file{doc/guix.html} directory.
+@item @command{make doc/guix-cookbook.info} for the cookbook info manual.
+@item @command{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
-- 
2.34.1

Message #8 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: 53287 <at> debbugs.gnu.org
Cc: Gabor Boskovits <boskovits <at> gmail.com>, Julien Lepiller <julien <at> lepiller.eu>,
 jgart <jgart <at> dismail.de>, Fabio Natali <me <at> fabionatali.com>,
 Matt Trzcinski <matt <at> excalamus.com>
Subject: [PATCH v2] doc: Document the documentation process.
Date: Sat, 15 Jan 2022 14:27:39 -0500

* doc/contributing.texi (Contributing): Add documentation documentation.

Co-authored-by: jgart <jgart <at> dismail.de>
Co-authored-by: Julien Lepiller <julien <at> lepiller.eu>
Co-authored-by: Matt Trzcinski <matt <at> excalamus.com>
Co-authored-by: Fabio Natali <me <at> fabionatali.com>
Co-authored-by: Gabor Boskovits <boskovits <at> gmail.com>
---

Here's a small fix that ngz suggested over irc.

I also changed the committer to whereiseveryone and the email to
use our public inbox instead of my own personal email. The commit
"Co-authored-by:" statements where also missing from the previous
patch. It had just the co-author's name and emails that I had pasted.

all best,

jgart

https://whereiseveryone.srht.site/
gemini://whereiseveryone.srht.site/

 doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9f97788c0b..101b693412 100644
--- 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
 
 @node Building from Git
@@ -1905,3 +1906,43 @@ differs for the various components.
       be updated accordingly (see @file{website/i18n-howto.txt} for more
       information on the process).
 @end itemize
+
+@cindex documentation
+@node Documenting Guix
+@section Documenting Guix
+
+Guix is documented using the Texinfo system.  However, if you are not
+yet familiar with it, we accept contributions for documentation in most
+formats.  That includes plain text, markdown, org-mode, etc...
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}.  Prepend @code{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above.  @xref{Submitting Patches} for more information on
+how to send your patches.
+
+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},
+@pxref{Translating Guix} for more information.
+
+To render your documentation changes, we recommend to execute one of
+the following commands:
+
+@itemize
+@item @command{make doc/guix.info} to compile the info manual.
+      You can check it with @command{info doc/guix.info}.
+@item @command{make doc/guix.html} to compile the HTML version.
+      You can point your browser to the relevant file in the
+      @file{doc/guix.html} directory.
+@item @command{make doc/guix-cookbook.info} for the cookbook info manual.
+@item @command{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
-- 
2.34.1

Message #11 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: 53287 <at> debbugs.gnu.org
Cc: jgart <jgart <at> dismail.de>
Subject: [PATCH v3] doc: Document the documentation process.
Date: Sat, 15 Jan 2022 14:45:22 -0500

* 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>
---
 doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index 9f97788c0b..84ac478269 100644
--- 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
 
 @node Building from Git
@@ -1905,3 +1906,43 @@ differs for the various components.
       be updated accordingly (see @file{website/i18n-howto.txt} for more
       information on the process).
 @end itemize
+
+@cindex documentation
+@node Documenting Guix
+@section Documenting Guix
+
+Guix is documented using the Texinfo system.  However, if you are not
+yet familiar with it, we accept contributions for documentation in most
+formats.  That includes plain text, Markdown, Org, etc...
+
+Documentation contributions can be sent to
+@email{guix-patches@@gnu.org}.  Prepend @samp{[DOCUMENTATION]} to the
+subject.
+
+When you need to make more than a simple addition to the documentation,
+we prefer that you send a proper patch as opposed to sending an email
+as described above.  @xref{Submitting Patches} for more information on
+how to send your patches.
+
+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},
+@pxref{Translating Guix} for more information.
+
+To render your documentation changes, we recommend to execute one of
+the following commands:
+
+@itemize
+@item @samp{make doc/guix.info} to compile the info manual.
+      You can check it with @command{info doc/guix.info}.
+@item @samp{make doc/guix.html} to compile the HTML version.
+      You can point your browser to the relevant file in the
+      @file{doc/guix.html} directory.
+@item @samp{make doc/guix-cookbook.info} for the cookbook info manual.
+@item @samp{make doc/guix-cookbook.html} for the cookbook HTML version.
+@end itemize
+
-- 
2.34.1

Message #14 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: Oliver Propst <oliver.propst <at> fripost.org>
Cc: Guix Devel <guix-devel <at> gnu.org>, 53287 <at> debbugs.gnu.org
Subject: Re: Guix Documentation Meetup This Saturday (January 15)
Date: Sat, 15 Jan 2022 15:17:05 -0500

On Tue, 11 Jan 2022 11:29:44 -0500 jgart <jgart <at> dismail.de> wrote:
> On Tue, 11 Jan 2022 17:23:38 +0100 Oliver Propst <oliver.propst <at> fripost.org> wrote:
> > On 2022-01-11 17:01, jgart wrote:
> > > Hi Guixers,
> > 
> > Hi Jgart thanks for the *note.
> > 
> > *will try to attend the meeting.
> 
> Hi Oliver,
> 
> Cool, hope to see you there!
> 
> all best,
> 
> jgart
> 

Hi Guixers,

We had a great turn out and insightful discussions about contibuting to and
documenting Guix.

Here are the notes and chat log the people added to BBB from today's
Guix Documentation Meetup:

https://paste.sr.ht/~whereiseveryone/69bad7722fad84edb1d6bed1f2c95b6e138f8154

https://paste.sr.ht/~whereiseveryone/11142d27dbe26732a8f5745e918ead9014b848f6

Our patch to upstream:

https://issues.guix.gnu.org/53287

Hope to catch you on the next one!

all best,

jgart

Message #17 received at submit <at> debbugs.gnu.org (full text, mbox):

From: zimoun <zimon.toutoune <at> gmail.com>
To: jgart via Guix-patches via <guix-patches <at> gnu.org>, 53287 <at> debbugs.gnu.org
Cc: jgart <jgart <at> dismail.de>
Subject: Re: [bug#53287] [PATCH v3] doc: Document the documentation process.
Date: Mon, 17 Jan 2022 17:31:31 +0100

Hi,

On Sat, 15 Jan 2022 at 14:45, jgart via Guix-patches via <guix-patches <at> gnu.org> wrote:

> * doc/contributing.texi (Contributing): Add documentation documentation.

[...]

> +Guix is documented using the Texinfo system.  However, if you are not
> +yet familiar with it, we accept contributions for documentation in most
> +formats.  That includes plain text, Markdown, Org, etc...

It is ellipses or etc. not both. :-)  

    +formats.  That includes plain text, Markdown, Org, etc.

(And no double period after an abbreviation. :-))


All LGTM.  Thanks for this collaborative contribution.


Cheers,
simon

Message #23 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: jgart <jgart <at> dismail.de>
Cc: 53287 <at> debbugs.gnu.org
Subject: Re: 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’.

Message #26 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: Julien Lepiller <julien <at> lepiller.eu>, 53287 <at> debbugs.gnu.org,
 zimoun <zimon.toutoune <at> gmail.com>
Date: Tue, 25 Jan 2022 02:27:31 -0500

Lepiller <julien <at> lepiller.eu>, Matt Trzcinski <matt <at> excalamus.com>,
Fabio Natali <me <at> fabionatali.com>, Gabor Boskovits <boskovits <at> gmail.com>
Bcc:
Subject: Re: bug#53287: [PATCH] doc: Document the documentation process.
Reply-To:
In-Reply-To: <87wnis3ijy.fsf_-_ <at> gnu.org>

On Fri, 21 Jan 2022 22:06:25 +0100 Ludovic Courtès <ludo <at> gnu.org> wrote:
> Could you send an updated patch?

Hi Zimoun and Ludo,

Thank you for the reviews! It is much appreciated.

I'll get back to you soon regarding an updated patch. I'll probably be able to 
work on this again this coming weekend once my time frees up.

If anyone from the meetup would like to send an updated patch before
then feel free to do so.

> Thumbs up to everyone who participated in this meetup!

Thank you! Much appreciated. 

I'm looking to forward to more Guix hacking with everyone.

all best,

jgart

Message #29 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: Luis Felipe <luis.felipe.la <at> protonmail.com>
To: "53287 <at> debbugs.gnu.org" <53287 <at> debbugs.gnu.org>
Subject: [PATCH] doc: Document the documentation process.
Date: Fri, 08 Apr 2022 18:26:54 +0000

[Message part 1 (text/plain, inline)]

Hi,

I attach an updated patch with the changes suggested by zimoun and Ludovic.

Cheers,

---
Luis Felipe López Acevedo

[0001-doc-Document-the-documentation-process.patch (text/x-patch, attachment)]

[publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc (application/pgp-keys, attachment)]

[signature.asc (application/pgp-signature, attachment)]

Message #32 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
To: Luis Felipe <luis.felipe.la <at> protonmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, jgart <jgart <at> dismail.de>,
 "53287-done <at> debbugs.gnu.org" <53287 <at> debbugs.gnu.org>,
 zimoun <zimon.toutoune <at> gmail.com>
Subject: Re: bug#53287: [PATCH] doc: Document the documentation process.
Date: Thu, 07 Jul 2022 14:42:53 -0400

Hello,

Luis Felipe <luis.felipe.la <at> protonmail.com> writes:

> Hi,
>
> I attach an updated patch with the changes suggested by zimoun and Ludovic.
>
> Cheers,

Pushed as e103d61485.

Thanks!

Maxim

Message #35 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: Luis Felipe <luis.felipe.la <at> protonmail.com>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>, jgart <jgart <at> dismail.de>,
 "53287-done <at> debbugs.gnu.org" <53287 <at> debbugs.gnu.org>,
 zimoun <zimon.toutoune <at> gmail.com>
Subject: Re: bug#53287: [PATCH] doc: Document the documentation process.
Date: Thu, 07 Jul 2022 21:41:48 +0000

[Message part 1 (text/plain, inline)]

Thank you, Maxim.

[publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc (application/pgp-keys, attachment)]

[signature.asc (application/pgp-signature, attachment)]

Message #38 received at 53287 <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: Luis Felipe <luis.felipe.la <at> protonmail.com>
Cc: Ludovic Courtès <ludo <at> gnu.org>,
 "53287-done <at> debbugs.gnu.org" <53287 <at> debbugs.gnu.org>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, zimoun <zimon.toutoune <at> gmail.com>
Subject: Re: bug#53287: [PATCH] doc: Document the documentation process.
Date: Thu, 7 Jul 2022 18:55:37 -0500

On Thu, 07 Jul 2022 21:41:48 +0000 Luis Felipe <luis.felipe.la <at> protonmail.com> wrote:
> Thank you, Maxim.

Thank you!

all best,

jgart

https://whereis.みんな/

Message #43 received at 53287-done <at> debbugs.gnu.org (full text, mbox):

From: jgart <jgart <at> dismail.de>
To: 53287-done <at> debbugs.gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>, jgart <jgart <at> dismail.de>,
 Luis Felipe <luis.felipe.la <at> protonmail.com>,
 Maxim Cournoyer <maxim.cournoyer <at> gmail.com>, zimoun <zimon.toutoune <at> gmail.com>
Subject: Re: [PATCH] doc: Document the documentation process.
Date: Sat, 29 Jun 2024 01:52:44 -0500

Hi all,

I'm closing this issue since it looks like Maxim merged a commit a while
ago resolving it. Thanks!

all best,

jgart

Previous Next

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