diff options
Diffstat (limited to 'doc/contributing.texi')
| -rw-r--r-- | doc/contributing.texi | 63 |
1 files changed, 52 insertions, 11 deletions
diff --git a/doc/contributing.texi b/doc/contributing.texi index e1902f120f..02c7c5ae59 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 @@ -224,8 +225,7 @@ $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' @noindent @cindex REPL @cindex read-eval-print loop -@dots{} and for a REPL (@pxref{Using Guile Interactively,,, guile, Guile -Reference Manual}): +@dots{} and for a REPL (@pxref{Using Guix Interactively}): @example $ ./pre-inst-env guile @@ -278,8 +278,8 @@ prepared Guile object (@file{.go}) files. You can run @command{make} automatically as you work using @command{watchexec} from the @code{watchexec} package. For example, -to build again each time you update a package file, you can run -@samp{watchexec -w gnu/packages make -j4}. +to build again each time you update a package file, run +@samp{watchexec -w gnu/packages -- make -j4}. @node The Perfect Setup @section The Perfect Setup @@ -291,7 +291,7 @@ Manual}). First, you need more than an editor, you need wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run: @example -guix package -i emacs guile emacs-geiser emacs-geiser-guile +guix install emacs guile emacs-geiser emacs-geiser-guile @end example Geiser allows for interactive and incremental development from within @@ -664,7 +664,7 @@ hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful when using some characters for example @samp{@@} and curly braces which are the basic special characters in Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces -such as @command{guix package --show} take care of rendering it +such as @command{guix show} take care of rendering it appropriately. Synopses and descriptions are translated by volunteers @@ -1118,11 +1118,11 @@ Development is done using the Git distributed version control system. Thus, access to the repository is not strictly necessary. We welcome contributions in the form of patches as produced by @code{git format-patch} sent to the @email{guix-patches@@gnu.org} mailing list -(@pxref{submitting patches,, Submitting patches to a project, git, Git -User Manual}). Contributors are encouraged to take a moment to set some -Git repository options (@pxref{Configuring Git}) first, which can -improve the readability of patches. Seasoned Guix developers may also -want to look at the section on commit access (@pxref{Commit Access}). +(@pxref{Submitting patches to a project,,, git, Git User Manual}). +Contributors are encouraged to take a moment to set some Git repository +options (@pxref{Configuring Git}) first, which can improve the +readability of patches. Seasoned Guix developers may also want to look +at the section on commit access (@pxref{Commit Access}). This mailing list is backed by a Debbugs instance, which allows us to keep track of submissions (@pxref{Tracking Bugs and Patches}). Each @@ -1779,6 +1779,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 |