[PATCH] doc: Document the documentation process.

  • Done
  • quality assurance status badge
Details
5 participants
  • jgart
  • Ludovic Courtès
  • Luis Felipe
  • Maxim Cournoyer
  • zimoun
Owner
unassigned
Submitted by
jgart
Severity
normal
J
J
jgart wrote on 15 Jan 2022 19:08
(address . guix-patches@gnu.org)(name . Guix Together)(address . jgart@dismail.de)
20220115180847.31250-1-jgart@dismail.de
From: Guix Together <jgart@dismail.de>

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

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

Hi Guixers,

Here is our work from today's documentation meetup.

all best,

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

Toggle diff (58 lines)
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
J
J
jgart wrote on 15 Jan 2022 20:27
[PATCH v2] doc: Document the documentation process.
(address . 53287@debbugs.gnu.org)
20220115192738.1461-1-jgart@dismail.de
* doc/contributing.texi (Contributing): Add documentation documentation.

Co-authored-by: jgart <jgart@dismail.de>
Co-authored-by: Julien Lepiller <julien@lepiller.eu>
Co-authored-by: Matt Trzcinski <matt@excalamus.com>
Co-authored-by: Fabio Natali <me@fabionatali.com>
Co-authored-by: Gabor Boskovits <boskovits@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

gemini://whereiseveryone.srht.site/

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

Toggle diff (58 lines)
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
J
J
jgart wrote on 15 Jan 2022 20:45
[PATCH v3] doc: Document the documentation process.
(address . 53287@debbugs.gnu.org)(name . jgart)(address . jgart@dismail.de)
20220115194521.2158-1-jgart@dismail.de
* doc/contributing.texi (Contributing): Add documentation documentation.

Co-authored-by: jgart <jgart@dismail.de>
Julien Lepiller <julien@lepiller.eu>
Matt Trzcinski <matt@excalamus.com>
Fabio Natali <me@fabionatali.com>
Gabor Boskovits <boskovits@gmail.com>
---
doc/contributing.texi | 41 +++++++++++++++++++++++++++++++++++++++++
1 file changed, 41 insertions(+)

Toggle diff (58 lines)
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
J
J
jgart wrote on 15 Jan 2022 21:17
Re: Guix Documentation Meetup This Saturday (January 15)
(name . Oliver Propst)(address . oliver.propst@fripost.org)
20220115151705.GB2736@gac.attlocal.net
On Tue, 11 Jan 2022 11:29:44 -0500 jgart <jgart@dismail.de> wrote:
Toggle quote (17 lines)
> On Tue, 11 Jan 2022 17:23:38 +0100 Oliver Propst <oliver.propst@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:



Our patch to upstream:


Hope to catch you on the next one!

all best,

jgart
Z
Z
zimoun wrote on 17 Jan 2022 17:31
Re: [bug#53287] [PATCH v3] doc: Document the documentation process.
(name . jgart)(address . jgart@dismail.de)
8635lmfhng.fsf@gmail.com
Hi,

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

Toggle quote (2 lines)
> * doc/contributing.texi (Contributing): Add documentation documentation.

[...]

Toggle quote (4 lines)
> +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
L
L
Ludovic Courtès wrote on 21 Jan 2022 22:06
Re: bug#53287: [PATCH] doc: Document the documentation process.
(name . jgart)(address . jgart@dismail.de)(address . 53287@debbugs.gnu.org)
87wnis3ijy.fsf_-_@gnu.org
Hi!

jgart <jgart@dismail.de> skribis:

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

That’s a much welcome addition!

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

Toggle quote (9 lines)
> --- 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.)

Toggle quote (2 lines)
> +Guix is documented using the Texinfo system. However, if you are not

I’d remove “However”.

Toggle quote (8 lines)
> +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…

Toggle quote (2 lines)
> +@pxref{Translating Guix} for more information.

… and pxref with xref.

Toggle quote (3 lines)
> +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:

?

Toggle quote (3 lines)
> +@itemize
> +@item @samp{make doc/guix.info} to compile the info manual.

s/info manual/Info manual/

Toggle quote (2 lines)
> +@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’.
J
J
jgart wrote on 25 Jan 2022 08:27
(no subject)
(name . Ludovic Courtès)(address . ludo@gnu.org)
20220125022731.GB6597@gac.attlocal.net
Lepiller <julien@lepiller.eu>, Matt Trzcinski <matt@excalamus.com>,
Fabio Natali <me@fabionatali.com>, Gabor Boskovits <boskovits@gmail.com>
Bcc:
Subject: Re: bug#53287: [PATCH] doc: Document the documentation process.
Reply-To:
In-Reply-To: <87wnis3ijy.fsf_-_@gnu.org>

On Fri, 21 Jan 2022 22:06:25 +0100 Ludovic Courtès <ludo@gnu.org> wrote:
Toggle quote (2 lines)
> 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.

Toggle quote (2 lines)
> 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
L
L
Luis Felipe wrote on 8 Apr 2022 20:26
[PATCH] doc: Document the documentation process.
(name . 53287@debbugs.gnu.org)(address . 53287@debbugs.gnu.org)
g9ZUmzckZuQLZFM5lTXP9qxTXClj8JDjrmRQusl386M0LRLLsCo9vWJGWkYjEtwEh0JD2URIAXEfTeGhG8pqaL4G0MtLrW6-BWWoy9--UjY=@protonmail.com
Hi,

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

Cheers,

---
Luis Felipe López Acevedo
From c808d0d2c20e659273e8019240a6391ed6a9f1da Mon Sep 17 00:00:00 2001
From: jgart <jgart@dismail.de>
Date: Sat, 15 Jan 2022 14:45:22 -0500
Subject: [PATCH] doc: Document the documentation process.

* doc/contributing.texi (Contributing): Add Writing Documentation section.

Co-authored-by: jgart <jgart@dismail.de>
Julien Lepiller <julien@lepiller.eu>
Matt Trzcinski <matt@excalamus.com>
Fabio Natali <me@fabionatali.com>
Gabor Boskovits <boskovits@gmail.com>
---
doc/contributing.texi | 42 ++++++++++++++++++++++++++++++++++++++++++
1 file changed, 42 insertions(+)

Toggle diff (62 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index 862dcbf12a..3a7b6e6012 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -29,6 +29,7 @@ choice.
* Tracking Bugs and Patches:: Keeping it all organized.
* Commit Access:: Pushing to the official repository.
* Updating the Guix Package:: Updating the Guix package definition.
+* Writing Documentation:: Improving documentation in GNU Guix.
* Translating Guix:: Make Guix speak your native language.
@end menu
@@ -1697,6 +1698,47 @@ This check can be disabled, @emph{at your own peril}, by setting the
this variable is set, the updated package source is also added to the
store. This is used as part of the release process of Guix.
+@cindex documentation
+@node Writing Documentation
+@section Writing Documentation
+
+Guix is documented using the Texinfo system. 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}.
+@xref{Translating Guix} for more information.
+
+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 that you can run 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
+
@cindex translation
@cindex l10n
@cindex i18n
--
2.34.0
Attachment: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc
Attachment: signature.asc
M
M
Maxim Cournoyer wrote on 7 Jul 2022 20:42
(name . Luis Felipe)(address . luis.felipe.la@protonmail.com)
87wncoydaq.fsf_-_@gmail.com
Hello,

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

Toggle quote (6 lines)
> Hi,
>
> I attach an updated patch with the changes suggested by zimoun and Ludovic.
>
> Cheers,

Pushed as e103d61485.

Thanks!

Maxim
L
J
J
jgart wrote on 8 Jul 2022 01:55
(name . Luis Felipe)(address . luis.felipe.la@protonmail.com)
20220707185537.GB1675@gac
On Thu, 07 Jul 2022 21:41:48 +0000 Luis Felipe <luis.felipe.la@protonmail.com> wrote:
Toggle quote (2 lines)
> Thank you, Maxim.

Thank you!

all best,

jgart

https://whereis.???/
J
J
jgart wrote on 29 Jun 08:52 +0200
Re: [PATCH] doc: Document the documentation process.
(address . 53287-done@debbugs.gnu.org)
875xtsnsub.fsf@dismail.de
Hi all,

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

all best,

jgart
Closed
?
Your comment

This issue is archived.

To comment on this conversation send an email to 53287@debbugs.gnu.org

To respond to this issue using the mumi CLI, first switch to it
mumi current 53287
Then, you may apply the latest patchset in this issue (with sign off)
mumi am -- -s
Or, compose a reply to this issue
mumi compose
Or, send patches to this issue
mumi send-email *.patch