| Message ID | 20220115194521.2158-1-jgart@dismail.de |
|---|---|
| State | New |
| Headers | show |
| Series | [bug#53287,v3] doc: Document the documentation process. | expand |
| Context | Check | Description |
|---|---|---|
| cbaines/comparison | success | View comparision |
| cbaines/git branch | success | View Git branch |
| cbaines/applying patch | success | View Laminar job |
| cbaines/issue | success | View issue |
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
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’.
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 +