[bug#53287] [PATCH] doc: Document the documentation process.

[bug#53287] [PATCH] doc: Document the documentation process.

[jgart via Guix-patches via]

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(+)

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

[bug#53287] [PATCH v2] doc: Document the documentation process.

[jgart via Guix-patches via]

* 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

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

[bug#53287] [PATCH v3] doc: Document the documentation process.

[jgart via Guix-patches via]

* 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(+)

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

[bug#53287] [PATCH v3] doc: Document the documentation process.

[zimoun]

Hi,

On Sat, 15 Jan 2022 at 14:45, jgart via Guix-patches via <guix-patches@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

[bug#53287] [PATCH] doc: Document the documentation process.

[Ludovic Courtès]

Hi!

jgart <jgart@dismail.de> skribis:

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

> --- 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’.

[bug#53287] (no subject)

[jgart via Guix-patches via]

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

[bug#53287] [PATCH] doc: Document the documentation process.

[Luis Felipe via Guix-patches via]

[-- Attachment #1.1: Type: text/plain, Size: 128 bytes --]

Hi,

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

Cheers,

---
Luis Felipe López Acevedo

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-Document-the-documentation-process.patch --]
[-- Type: text/x-patch; filename="0001-doc-Document-the-documentation-process.patch"; name="0001-doc-Document-the-documentation-process.patch", Size: 3213 bytes --]

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(+)

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 #1.3: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1815 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]

[bug#53287] [PATCH] doc: Document the documentation process.

[Maxim Cournoyer]

Hello,

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

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

Pushed as e103d61485.

Thanks!

Maxim

[bug#53287] [PATCH] doc: Document the documentation process.

[Luis Felipe via Guix-patches via]

[-- Attachment #1.1: Type: text/plain, Size: 17 bytes --]

Thank you, Maxim.

[-- Attachment #1.2: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1815 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]

[bug#53287] [PATCH] doc: Document the documentation process.

[jgart via Guix-patches via]

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

Thank you!

all best,

jgart

https://whereis.みんな/

bug#53287: [PATCH] doc: Document the documentation process.

[jgart via Guix-patches via]

Hi all,

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

all best,

jgart