FAQ

FAQ

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 309 bytes --]

> Yes, but the Automake you installed by hand (in /usr/local I suppose?)
> doesn’t look for .m4 files under /usr/share.  Thus you need to:

>   export ACLOCAL PATH=/usr/share/aclocal

I've seen similar questions several times.  Maybe we should create a FAQ
section in 'HACKING'.  What do you think?

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: FAQ

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> Yes, but the Automake you installed by hand (in /usr/local I suppose?)
>> doesn’t look for .m4 files under /usr/share.  Thus you need to:
>
>>   export ACLOCAL PATH=/usr/share/aclocal
>
> I've seen similar questions several times.  Maybe we should create a FAQ
> section in 'HACKING'.  What do you think?

It’s a good idea, probably as the first section in ‘HACKING’.  Would you
like to propose a patch?

Thanks,
Ludo’.

Re: FAQ

[Nikita Karetnikov]

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

> It’s a good idea, probably as the first section in ‘HACKING’.  Would you
> like to propose a patch?

Attached.  Did I forget to mention anything?


[-- Attachment #1.2: 0001-doc-Add-FAQ-to-HACKING.patch --]
[-- Type: text/x-diff, Size: 1667 bytes --]

From 17a11ca78a4f71174edf57ec01f55934b1761363 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Tue, 9 Jul 2013 18:47:17 +0000
Subject: [PATCH] doc: Add FAQ to 'HACKING'.

---
 HACKING |   20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/HACKING b/HACKING
index dd59a68..89ea124 100644
--- a/HACKING
+++ b/HACKING
@@ -3,12 +3,32 @@
 #+TITLE: Hacking GNU Guix and Its Incredible Distro
 
 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
+Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.
 
 
+* FAQ
+
+** ./configure: line 6755: `PKG_CHECK_MODULES(GUILE, guile-2.0 >= 2.0.5)'
+
+This message means that Autoconf didn't pick up the definition of the
+'PKG_CHECK_MODULES' M4 macro.  'pkg.m4' is provided by the 'pkg-config'
+package.  If you install 'pkg-config', Autoconf should automatically find it.
+
+However, if you installed Automake in '/usr/local', it wouldn't look for '.m4'
+files in '/usr/share'.  You have to invoke the following command in that case:
+
+  $ export ACLOCAL_PATH=/usr/share/aclocal
+
+** make: *** No rule to make target `nix/libstore/schema.sql', needed by
+`nix/libstore/schema.sql.hh'.
+
+You must run './bootstrap', which just invokes 'git submodule update', before
+'./configure && make && make check'.
+
 * Running Guix before it is installed
 
 Command-line tools can be used even if you have not run "make install".
-- 
1.7.9.5


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: FAQ

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> It’s a good idea, probably as the first section in ‘HACKING’.  Would you
>> like to propose a patch?
>
> Attached.  Did I forget to mention anything?

Looks good, but I would call it “Building from Git”, for instance, with
this particular error as a caveat.

> +You must run './bootstrap', which just invokes 'git submodule update', before

Remove “just”.

I would also link to the “Installation” section of the manual, and to
“Installing Guix from Guix” in README.

WDYT?

Ludo’.

Re: FAQ

[Nikita Karetnikov]

[-- Attachment #1: Type: text/plain, Size: 384 bytes --]

> Looks good, but I would call it “Building from Git”, for instance, with
> this particular error as a caveat.

OK.

> Remove “just”.

OK.

> I would also link to the “Installation” section of the manual, and to
> “Installing Guix from Guix” in README.

> WDYT?

Can I use 'README' instead of 'HACKING', then?  All installation
instructions are there.

[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: FAQ

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> Looks good, but I would call it “Building from Git”, for instance, with
>> this particular error as a caveat.
>
> OK.
>
>> Remove “just”.
>
> OK.
>
>> I would also link to the “Installation” section of the manual, and to
>> “Installing Guix from Guix” in README.
>
>> WDYT?
>
> Can I use 'README' instead of 'HACKING', then?  All installation
> instructions are there.

I’d say no, because that could lead “normal users” to think they need
Automake & co. to install Guix.

Ludo’.

Re: FAQ

[Nikita Karetnikov]

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

> I’d say no, because that could lead “normal users” to think they need
> Automake & co. to install Guix.

OK, can I push this one?


[-- Attachment #1.2: 0001-doc-Add-Building-from-Git-to-HACKING.patch --]
[-- Type: text/x-diff, Size: 2252 bytes --]

From cb6750a9869fc162d98eeb38ccb78e0846553f64 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Wed, 10 Jul 2013 06:13:59 +0000
Subject: [PATCH] doc: Add "Building from Git" to 'HACKING'.

---
 HACKING |   30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/HACKING b/HACKING
index 9d8960c..8f6e835 100644
--- a/HACKING
+++ b/HACKING
@@ -3,12 +3,42 @@
 #+TITLE: Hacking GNU Guix and Its Incredible Distro
 
 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
+Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.
 
 
+* Building from Git
+
+The following errors might appear if you are building from Git.  Also,
+take a look at the [[https://gnu.org/software/guix/manual/guix.html#Installation]["Installation"]] section of the manual and the
+[[http://git.savannah.gnu.org/cgit/guix.git/tree/README]["Installing Guix from Guix"]] section in 'README'.
+
+** ./configure: line 6755: `PKG_CHECK_MODULES(GUILE, guile-2.0 >= 2.0.5)'
+
+This message means that Autoconf didn't pick up the definition of the
+'PKG_CHECK_MODULES' M4 macro.  'pkg.m4' is provided by the 'pkg-config'
+package.  If you install 'pkg-config', Autoconf should automatically find it.
+
+However, if you installed Automake in '/usr/local', it wouldn't look for '.m4'
+files in '/usr/share'.  You have to invoke the following command in that case:
+
+  $ export ACLOCAL_PATH=/usr/share/aclocal
+
+** make: *** No rule to make target `nix/libstore/schema.sql', needed by
+`nix/libstore/schema.sql.hh'.
+
+You must run './bootstrap', which invokes 'git submodule update', before
+'./configure && make && make check'.
+
+** /bin/bash: dot: command not found
+make[2]: *** [doc/images/bootstrap-graph.png] Error 127
+
+You must install Graphviz.  (It is not listed as a requirement because the
+resulting images will be shipped with a tarball.)
+
 * Running Guix before it is installed
 
 Command-line tools can be used even if you have not run "make install".
-- 
1.7.9.5


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: FAQ

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

> +* Building from Git
> +
> +The following errors might appear if you are building from Git.  Also,
> +take a look at the [[https://gnu.org/software/guix/manual/guix.html#Installation]["Installation"]] section of the manual and the
> +[[http://git.savannah.gnu.org/cgit/guix.git/tree/README]["Installing Guix from Guix"]] section in 'README'.

Sorry if I wasn’t clear.  What I meant is: instead of presenting it as a
trial-and-error approach, I would rather present it as a sequence of
instructions to build from Git.

Something like:

  First, make sure Autoconf (>= 2.69), Automake, pkg-config, etc. are
  installed.  If you get an error like this:

    ./configure: line 6755: `PKG_CHECK_MODULES(GUILE, guile-2.0 >= 2.0.5)'

  then it probably means that pkg-config’s pkg.m4 file was not found by
  Automake.  Make sure pkg.m4 is available, and possibly add its
  directory to the ACLOCAL_PATH environment variable (info "(automake)
  Macro Search Path").

  Second, run ./bootstrap.  Among other things, this will run ‘git
  submodule update’.  If you get an error like this:

    ...

Also, when referring to a GNU manual, please show the info command (as I
did above) rather than giving a hyperlink.  This will ensure that users
read the right version of the manual.

For the link to README, just use [[./README][README]] (info "(org)
Hyperlinks").


It may look like I’m being picky, and indeed that’s what I am ;-), but I
think it’s important to agree on how to present information.

Thanks for your help!

Ludo’.

Re: FAQ

[Nikita Karetnikov]

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

> Sorry if I wasn’t clear.  What I meant is: instead of presenting it as a
> trial-and-error approach, I would rather present it as a sequence of
> instructions to build from Git.

OK, what do you think about this patch?

> For the link to README, just use [[./README][README]] (info "(org)
> Hyperlinks").

I decided not to refer to 'README' because it's mentioned in the
"Installation" section of the manual.

> It may look like I’m being picky, and indeed that’s what I am ;-), but I
> think it’s important to agree on how to present information.

No, you are absolutely right.  Do you have any other comments?


[-- Attachment #1.2: 0001-doc-Add-Building-from-Git-to-HACKING.patch --]
[-- Type: text/x-diff, Size: 2364 bytes --]

From 64f56139dc2b3d92cf9b580414df609fdd951bf0 Mon Sep 17 00:00:00 2001
From: Nikita Karetnikov <nikita@karetnikov.org>
Date: Fri, 12 Jul 2013 20:31:28 +0000
Subject: [PATCH] doc: Add "Building from Git" to 'HACKING'.

---
 HACKING |   35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/HACKING b/HACKING
index 9d8960c..c711521 100644
--- a/HACKING
+++ b/HACKING
@@ -3,12 +3,47 @@
 #+TITLE: Hacking GNU Guix and Its Incredible Distro
 
 Copyright © 2012, 2013 Ludovic Courtès <ludo@gnu.org>
+Copyright © 2013 Nikita Karetnikov <nikita@karetnikov.org>
 
   Copying and distribution of this file, with or without modification,
   are permitted in any medium without royalty provided the copyright
   notice and this notice are preserved.
 
 
+* Building from Git
+
+First, make sure that 'autoconf' (>= 2.69), 'automake', and 'pkg-config' are
+installed.  Run './bootstrap' that, among other things, invokes 'git submodule
+update', or you might get the following error
+
+  make: *** No rule to make target `nix/libstore/schema.sql', needed by
+  `nix/libstore/schema.sql.hh'
+
+Then, as always, run './configure'.  If you get an error like this one
+
+  ./configure: line 6755: `PKG_CHECK_MODULES(GUILE, guile-2.0 >= 2.0.5)'
+
+it probably means that 'autoconf' couldn't find 'pkg.m4', which is provided by
+'pkg-config'.  Make sure that 'pkg.m4' is available.  For instance, if you
+installed 'automake' in '/usr/local', it wouldn't look for '.m4' files in
+'/usr/share'.  So you have to invoke the following command in that case
+
+  $ export ACLOCAL_PATH=/usr/share/aclocal
+
+See "info '(automake) Macro Search Path'" for more information.
+
+After that you should proceed with 'make'.  You might also get this error
+
+  /bin/bash: dot: command not found
+  make[2]: *** [doc/images/bootstrap-graph.png] Error 127
+
+This one is easy to handle; just install 'graphviz'.  It is not listed as a
+requirement because the resulting images should come with a tarball.
+
+Finally, you have to invoke 'make check' to run tests.  If anything fails,
+take a look at "info '(guix) Installation'" or send a message to
+<bug-guix@gnu.org>.
+
 * Running Guix before it is installed
 
 Command-line tools can be used even if you have not run "make install".
-- 
1.7.9.5


[-- Attachment #2: Type: application/pgp-signature, Size: 835 bytes --]

Re: FAQ

[Ludovic Courtès]

Nikita Karetnikov <nikita@karetnikov.org> skribis:

>> Sorry if I wasn’t clear.  What I meant is: instead of presenting it as a
>> trial-and-error approach, I would rather present it as a sequence of
>> instructions to build from Git.
>
> OK, what do you think about this patch?

Looks good to me!

One last thing:

> +* Building from Git
> +
> +First, make sure that 'autoconf' (>= 2.69), 'automake', and 'pkg-config' are

When speaking of the packages, not the commands, use the right spelling,
without quotes: Autoconf, Automake, pkg-config, Graphviz.

(When you do need quotation marks, you can use Unicode quotation marks.)

Please commit with these changes.

Thanks,
Ludo’.

FAQ

[Vincent Legoll]

Hello,

Is there a FAQ page we can contribute to ?

Something less formal than the official doc, perhaps a wiki...

-- 
Vincent Legoll

Re: FAQ

[Andreas Enge]

On Sat, Jul 16, 2016 at 03:41:43PM +0200, Vincent Legoll wrote:
> Is there a FAQ page we can contribute to ?

This is an FAQ :-)

The standard answer is that we prefer patches to the documentation instead
of spreading out the information.

Maybe we should create an FAQ with exactly this question and an answer
similar to mine?

Andreas

Re: FAQ

[Vincent Legoll]

OK, I'll try to create a FAQ section in the official doc then...

-- 
Vincent Legoll

Re: FAQ

[myglc2]

Vincent Legoll <vincent.legoll@gmail.com> writes:

> OK, I'll try to create a FAQ section in the official doc then...

Great idea!

Re: FAQ

[Andreas Enge]

On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
> Vincent Legoll <vincent.legoll@gmail.com> writes:
> > OK, I'll try to create a FAQ section in the official doc then...
> Great idea!

Hm, lest I be misunderstood: The aim is that reading the manual should
be sufficient. If there is a frequently asked question, it should not
be added to an FAQ section, but the section of the documentation where
the question should be answered should be updated.

My reply was half meant as a joke. And half seriously: As a little joke
we could add an FAQ with only one question: "Where is the FAQ?" and the
answer "There is none, if you find the documentation is lacking, please
submit a patch to improve this manual." or the like.

Andreas

Re: FAQ

[Alex Sassmannshausen]

Hello,

Andreas Enge writes:

> On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
>> Vincent Legoll <vincent.legoll@gmail.com> writes:
>> > OK, I'll try to create a FAQ section in the official doc then...
>> Great idea!
>
> Hm, lest I be misunderstood: The aim is that reading the manual should
> be sufficient. If there is a frequently asked question, it should not
> be added to an FAQ section, but the section of the documentation where
> the question should be answered should be updated.
>
> My reply was half meant as a joke. And half seriously: As a little joke
> we could add an FAQ with only one question: "Where is the FAQ?" and the
> answer "There is none, if you find the documentation is lacking, please
> submit a patch to improve this manual." or the like.

hmm… I sympathise strongly with the notion of contralising documentation
as much as possible.  It strikes me that an FAQ is meant to do something
else from a manual though: whereas a (reference) manual is meant to be
as comprehensive and detailed as possible, an FAQ can provide
high-level, short responses to common questions.

Because Guix is relatively unique in its approach to package management,
it may well be worth trying to address some high level questions in an
FAQ, which in turn might link to the relevant sections of the manual for
more detail.

I don't know if this is the right way to go, but I'd be interested in
seeing a (patch) proposal for such a type of FAQ as an appendix to the
manual if this was what was indeed intended.

WDYT?

Alex

Re: FAQ

[Vincent Legoll]

I did it:
https://lists.gnu.org/archive/html/guix-devel/2016-07/msg00488.html

That's where I'm coming from with this idea of not-so-formalized, *easy*
to edit FAQ...

Something where we can tell newcomers to go wild, and ask their questions,
they don't know scheme, nor texinfo, nor should we assume anything from
them. then as questions / answers mature, they can be moved into the
relevant doc section.

That's my 2 cts

-- 
Vincent Legoll

Re: FAQ

[Amirouche Boubekki]

On 2016-07-16 20:15, Alex Sassmannshausen wrote:
> Hello,
> 
> Andreas Enge writes:
> 
>> On Sat, Jul 16, 2016 at 01:02:33PM -0400, myglc2 wrote:
>>> Vincent Legoll <vincent.legoll@gmail.com> writes:
>>> > OK, I'll try to create a FAQ section in the official doc then...
>>> Great idea!
>> 
>> Hm, lest I be misunderstood: The aim is that reading the manual should
>> be sufficient. If there is a frequently asked question, it should not
>> be added to an FAQ section, but the section of the documentation where
>> the question should be answered should be updated.
>> 
>> My reply was half meant as a joke. And half seriously: As a little 
>> joke
>> we could add an FAQ with only one question: "Where is the FAQ?" and 
>> the
>> answer "There is none, if you find the documentation is lacking, 
>> please
>> submit a patch to improve this manual." or the like.
> 
> hmm… I sympathise strongly with the notion of contralising 
> documentation
> as much as possible.  It strikes me that an FAQ is meant to do 
> something
> else from a manual though: whereas a (reference) manual is meant to be
> as comprehensive and detailed as possible, an FAQ can provide
> high-level, short responses to common questions.
> 
> Because Guix is relatively unique in its approach to package 
> management,
> it may well be worth trying to address some high level questions in an
> FAQ, which in turn might link to the relevant sections of the manual 
> for
> more detail.
> 
> I don't know if this is the right way to go, but I'd be interested in
> seeing a (patch) proposal for such a type of FAQ as an appendix to the
> manual if this was what was indeed intended.
> 
> WDYT?

+1

Focusing on the texinfo manual is not a good idea. If there is still no 
way
to make libreplanet wiki the official wiki of guix, I hope the a FAQ 
patch
can make it through