Simplify contributing instructions

DoneSubmitted by pelzflorian (Florian Pelz).
Details
2 participants
  • Ludovic Courtès
  • pelzflorian (Florian Pelz)
Owner
unassigned
Severity
normal
P
P
pelzflorian (Florian Pelz) wrote on 13 Jul 2019 08:41
(address . guix-patches@gnu.org)
20190713064140.froxjbrj4pzzsfh2@pelzflorian.localdomain
I believe we want to be able to refer users who have bugs to the Guix
manual sections on Contributing. In
the contributing instructions in the Guix manual were not understood
properly. I hope the attached patch could alleviate this a little.

Regards,
Florian
From 3d6f944daa314e3bf064ef262a5c79ada1c70e6e Mon Sep 17 00:00:00 2001
From: Florian Pelz <pelzflorian@pelzflorian.de>
Date: Sat, 13 Jul 2019 08:29:26 +0200
Subject: [PATCH] doc: Reorder and clarify contributing instructions.

* doc/contributing.texi (Building from Git, Running Guix Before It Is
Installed): Make instructions using Guix come first and clarify which code is
an instruction and which is merely an example.
---
doc/contributing.texi | 36 +++++++++++++++++++-----------------
1 file changed, 19 insertions(+), 17 deletions(-)

Toggle diff (70 lines)
diff --git a/doc/contributing.texi b/doc/contributing.texi
index e00634eed4..f5eff842b9 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -38,19 +38,6 @@ version from the Git repository:
 git clone https://git.savannah.gnu.org/git/guix.git
 @end example
 
-When building Guix from a checkout,
-the following packages are required in addition to those mentioned in
-the installation instructions (@pxref{Requirements}).
-
-@itemize
-@item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
-@item @url{http://gnu.org/software/automake/, GNU Automake};
-@item @url{http://gnu.org/software/gettext/, GNU Gettext};
-@item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
-@item @url{http://www.graphviz.org/, Graphviz};
-@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
-@end itemize
-
 The easiest way to set up a development environment for Guix is, of
 course, by using Guix!  The following command starts a new shell where
 all the dependencies and appropriate environment variables are set up to
@@ -61,7 +48,22 @@ guix environment guix --pure
 @end example
 
 @xref{Invoking guix environment}, for more information on that command.
-Extra dependencies can be added with @option{--ad-hoc}:
+
+If you are unable to use Guix when building Guix from a checkout, the
+following are the required packages in addition to those mentioned in the
+installation instructions (@pxref{Requirements}).
+
+@itemize
+@item @url{http://gnu.org/software/autoconf/, GNU Autoconf};
+@item @url{http://gnu.org/software/automake/, GNU Automake};
+@item @url{http://gnu.org/software/gettext/, GNU Gettext};
+@item @url{http://gnu.org/software/texinfo/, GNU Texinfo};
+@item @url{http://www.graphviz.org/, Graphviz};
+@item @url{http://www.gnu.org/software/help2man/, GNU Help2man (optional)}.
+@end itemize
+
+On Guix, extra dependencies can be added by instead running @command{guix
+environment} with @option{--ad-hoc}:
 
 @example
 guix environment guix --pure --ad-hoc help2man git strace
@@ -113,8 +115,8 @@ run @code{make install}.  To do that, you first need to have an environment
 with all the dependencies available (@pxref{Building from Git}), and then
 simply prefix each command with
 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
-top build tree of Guix; it is generated by @command{./configure}),
-as in@footnote{The @option{-E} flag to
+top build tree of Guix; it is generated by @command{./configure}).
+An example@footnote{The @option{-E} flag to
 @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set
 such that @command{guix-daemon} and the tools it uses can find the Guile
 modules they need.}:
@@ -125,7 +127,7 @@ $ ./pre-inst-env guix build hello
 @end example
 
 @noindent
-Similarly, for a Guile session using the Guix modules:
+Similarly, an example for a Guile session using the Guix modules:
 
 @example
 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
-- 
2.22.0
L
L
Ludovic Courtès wrote on 17 Jul 2019 15:00
(name . pelzflorian (Florian Pelz))(address . pelzflorian@pelzflorian.de)(address . 36635-done@debbugs.gnu.org)
877e8gddey.fsf@gnu.org
Hello,

"pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

Toggle quote (9 lines)
>>From 3d6f944daa314e3bf064ef262a5c79ada1c70e6e Mon Sep 17 00:00:00 2001
> From: Florian Pelz <pelzflorian@pelzflorian.de>
> Date: Sat, 13 Jul 2019 08:29:26 +0200
> Subject: [PATCH] doc: Reorder and clarify contributing instructions.
>
> * doc/contributing.texi (Building from Git, Running Guix Before It Is
> Installed): Make instructions using Guix come first and clarify which code is
> an instruction and which is merely an example.

Applied, thanks!

Ludo’.
Closed
?
Your comment

This issue is archived.

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