2 (possible) problems in documentation

2 (possible) problems in documentation

[Alex Vong]

Hi,

I hit several problems when I followed the documentation. Please see
if it is a real issue or just my misunderstandings.

1. In <https://www.gnu.org/software/guix/manual/guix.html#X11-Fonts>,
it saids "Essential font packages include gs-fonts, font-dejavu, and
font-gnu-freefont.". But I think "font-gnu-freefont" has been renamed
to "font-gnu-freefont-ttf", so this has to be changed.

2. In <https://www.gnu.org/software/guix/manual/guix.html#Running-Guix-Before-It-Is-Installed>,
it said "To that end, all the command-line tools can be used even if
you have not run make install.". However, in the case of "guix pull",
it is not true. Even if "guix pull" does run properly, it will not
update the source tree you have downloaded, so you end up with running
the original compiled version of Guix. Obviously, I was a victim :)

Does these sound like problems to you?

Cheers,
Alex

Re: 2 (possible) problems in documentation

[Alex Kost]

Alex Vong (2015-10-31 14:27 +0300) wrote:

> Hi,
>
> I hit several problems when I followed the documentation. Please see
> if it is a real issue or just my misunderstandings.
>
> 1. In <https://www.gnu.org/software/guix/manual/guix.html#X11-Fonts>,
> it saids "Essential font packages include gs-fonts, font-dejavu, and
> font-gnu-freefont.". But I think "font-gnu-freefont" has been renamed
> to "font-gnu-freefont-ttf", so this has to be changed.

I think this on-line manual is for the current version (0.8.3).  The
typo you mention was fixed in the git repo:
<http://git.savannah.gnu.org/cgit/guix.git/commit/?id=8fe5b1d1d1d188cbc6eb1b644fdc0d9fff255d4e>

> 2. In
> <https://www.gnu.org/software/guix/manual/guix.html#Running-Guix-Before-It-Is-Installed>,
> it said "To that end, all the command-line tools can be used even if
> you have not run make install.". However, in the case of "guix pull",
> it is not true. Even if "guix pull" does run properly, it will not
> update the source tree you have downloaded, so you end up with running
> the original compiled version of Guix. Obviously, I was a victim :)

Sorry, I don't understand what you mean here.  "guix pull" can't update
the source tree you downloaded.  It fetches the latest guix source,
compiles it, put it to the store and link "~/.config/guix/latest" to it.
Then the Guix code from this directory when you run "guix ..." commands.

If you use the described "pre-inst-env" method, the code from the git
directory is used instead, and running "guix pull" doesn't effect
".../pre-inst-env guix" commands in any way.  Here instead of "guix
pull" you use "git pull" and "make".

-- 
Alex

Re: 2 (possible) problems in documentation

[Alex Vong]

On 01/11/2015, Alex Kost <alezost@gmail.com> wrote:
> Alex Vong (2015-10-31 14:27 +0300) wrote:
>
>> Hi,
>>
>> I hit several problems when I followed the documentation. Please see
>> if it is a real issue or just my misunderstandings.
>>
>> 1. In <https://www.gnu.org/software/guix/manual/guix.html#X11-Fonts>,
>> it saids "Essential font packages include gs-fonts, font-dejavu, and
>> font-gnu-freefont.". But I think "font-gnu-freefont" has been renamed
>> to "font-gnu-freefont-ttf", so this has to be changed.
>
> I think this on-line manual is for the current version (0.8.3).  The
> typo you mention was fixed in the git repo:
> <http://git.savannah.gnu.org/cgit/guix.git/commit/?id=8fe5b1d1d1d188cbc6eb1b644fdc0d9fff255d4e>
>
Thanks! I wasn't aware that the web version not being up to date.

>> 2. In
>> <https://www.gnu.org/software/guix/manual/guix.html#Running-Guix-Before-It-Is-Installed>,
>> it said "To that end, all the command-line tools can be used even if
>> you have not run make install.". However, in the case of "guix pull",
>> it is not true. Even if "guix pull" does run properly, it will not
>> update the source tree you have downloaded, so you end up with running
>> the original compiled version of Guix. Obviously, I was a victim :)
>
> Sorry, I don't understand what you mean here.  "guix pull" can't update
> the source tree you downloaded.  It fetches the latest guix source,
> compiles it, put it to the store and link "~/.config/guix/latest" to it.
> Then the Guix code from this directory when you run "guix ..." commands.
>
> If you use the described "pre-inst-env" method, the code from the git
> directory is used instead, and running "guix pull" doesn't effect
> ".../pre-inst-env guix" commands in any way.  Here instead of "guix
> pull" you use "git pull" and "make".
>
What I mean is "guix pull" only works after Guix is installed, so what
the documentation says, "To that end, all the command-line tools can
be used even if you have not run make install", is inaccurate. Should
we note this in the documentation?

> --
> Alex
>

Cheers,
Alex

Re: 2 (possible) problems in documentation

[Alex Kost]

Alex Vong (2015-11-01 06:22 +0300) wrote:

> On 01/11/2015, Alex Kost <alezost@gmail.com> wrote:
>> Alex Vong (2015-10-31 14:27 +0300) wrote:
[...]
>>> 2. In
>>> <https://www.gnu.org/software/guix/manual/guix.html#Running-Guix-Before-It-Is-Installed>,
>>> it said "To that end, all the command-line tools can be used even if
>>> you have not run make install.". However, in the case of "guix pull",
>>> it is not true. Even if "guix pull" does run properly, it will not
>>> update the source tree you have downloaded, so you end up with running
>>> the original compiled version of Guix. Obviously, I was a victim :)
>>
>> Sorry, I don't understand what you mean here.  "guix pull" can't update
>> the source tree you downloaded.  It fetches the latest guix source,
>> compiles it, put it to the store and link "~/.config/guix/latest" to it.
>> Then the Guix code from this directory when you run "guix ..." commands.
>>
>> If you use the described "pre-inst-env" method, the code from the git
>> directory is used instead, and running "guix pull" doesn't effect
>> ".../pre-inst-env guix" commands in any way.  Here instead of "guix
>> pull" you use "git pull" and "make".
>>
> What I mean is "guix pull" only works after Guix is installed, so what
> the documentation says, "To that end, all the command-line tools can
> be used even if you have not run make install", is inaccurate. Should
> we note this in the documentation?

IMO it is accurate, because "./pre-inst-env guix pull" also works; it
just doesn't work the way you thought.  But if you find the
documentation confusing you are welcome to improve it :-)

-- 
Alex

Re: 2 (possible) problems in documentation

[Mathieu Lirzin]

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

Hi,

Alex Vong <alexvong1995@gmail.com> writes:

> On 01/11/2015, Alex Kost <alezost@gmail.com> wrote:
>> I think this on-line manual is for the current version (0.8.3).  The
>> typo you mention was fixed in the git repo:
>> <http://git.savannah.gnu.org/cgit/guix.git/commit/?id=8fe5b1d1d1d188cbc6eb1b644fdc0d9fff255d4e>
>>
> Thanks! I wasn't aware that the web version not being up to date.

The online manual is up to date with the current release but not with
the master branch.  Maybe we could provide a link to it like Guile:

  https://www.gnu.org/software/guile/docs/docs.html

> What I mean is "guix pull" only works after Guix is installed, so what
> the documentation says, "To that end, all the command-line tools can
> be used even if you have not run make install", is inaccurate. Should
> we note this in the documentation?

I think you mean that ‘pre-inst-env guix pull’ does not work if you have
not run ‘make install’ before?  What do you think of the following
patch?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-doc-Add-an-exception-in-Running-Guix-Before-It-Is-In.patch --]
[-- Type: text/x-diff, Size: 1285 bytes --]

From ee2f4467d84ad9516b14c7bd14f821e4bec443cc Mon Sep 17 00:00:00 2001
From: Mathieu Lirzin <mthl@gnu.org>
Date: Sun, 1 Nov 2015 16:27:07 +0100
Subject: [PATCH] doc: Add an exception in "Running Guix Before It Is
 Installed".

* doc/contributing.texi (Running Guix Before It Is Installed): Add an
  exception footnote for `guix pull'.

Suggested-by: Alex Vong <alexvong1995@gmail.com>
---
 doc/contributing.texi | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f855daf..d033b1f 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -72,8 +72,9 @@ test the changes made in your local source tree checkout without
 actually installing them.  So that you can distinguish between your
 ``end-user'' hat and your ``motley'' costume.
 
-To that end, all the command-line tools can be used even if you have not
-run @code{make install}.  To do that, prefix each command with
+To that end, all the command-line tools@footnote{@code{guix pull} is an
+exception (@pxref{Invoking guix pull}).} can be used even if you have
+not run @code{make install}.  To do that, prefix each command with
 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
 top build tree of Guix), as in:
 
-- 
2.6.1


[-- Attachment #3: Type: text/plain, Size: 28 bytes --]


Thanks,

--
Mathieu Lirzin

Re: 2 (possible) problems in documentation

[Mathieu Lirzin]

Hi again,

Mathieu Lirzin <mthl@gnu.org> writes:

> What do you think of the following patch?
>
>From ee2f4467d84ad9516b14c7bd14f821e4bec443cc Mon Sep 17 00:00:00 2001
> From: Mathieu Lirzin <mthl@gnu.org>
> Date: Sun, 1 Nov 2015 16:27:07 +0100
> Subject: [PATCH] doc: Add an exception in "Running Guix Before It Is
>  Installed".
>
> * doc/contributing.texi (Running Guix Before It Is Installed): Add an
>   exception footnote for `guix pull'.
>
> Suggested-by: Alex Vong <alexvong1995@gmail.com>

Please ignore this patch, my mind was confused. :)

--
Mathieu Lrzin

Re: 2 (possible) problems in documentation

[Alex Vong]

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

Hi,

I have written a patch based on the old patch. Does it look good to
you? By the way, does anyone know how to build the guix website from
source? I want to add some labels so that librejs don't complain the
javascripts being non-free on this page
<https://www.gnu.org/software/guix/packages/>. I have cloned the
guix-artwork repo but I don't know how to set-up or build the websites
(I have zero experience on building websites.).

Cheers,
Alex

On 01/11/2015, Mathieu Lirzin <mthl@gnu.org> wrote:
> Hi again,
>
> Mathieu Lirzin <mthl@gnu.org> writes:
>
>> What do you think of the following patch?
>>
>>From ee2f4467d84ad9516b14c7bd14f821e4bec443cc Mon Sep 17 00:00:00 2001
>> From: Mathieu Lirzin <mthl@gnu.org>
>> Date: Sun, 1 Nov 2015 16:27:07 +0100
>> Subject: [PATCH] doc: Add an exception in "Running Guix Before It Is
>>  Installed".
>>
>> * doc/contributing.texi (Running Guix Before It Is Installed): Add an
>>   exception footnote for `guix pull'.
>>
>> Suggested-by: Alex Vong <alexvong1995@gmail.com>
>
> Please ignore this patch, my mind was confused. :)
>
> --
> Mathieu Lrzin
>
>

[-- Attachment #2: 0001-doc-To-clarify-.-pre-inst-env-guix-pull-won-t-upgrad.patch --]
[-- Type: text/x-patch, Size: 1188 bytes --]

From e562ebc9a9e3859ecc0c1c2e8be6f39a44b5be7d Mon Sep 17 00:00:00 2001
From: Alex Vong <alexvong1995@gmail.com>
Date: Mon, 2 Nov 2015 23:34:16 +0800
Subject: [PATCH] doc: To clarify `./pre-inst-env guix pull` won't upgrade
 local source tree.

* doc/contributing.texi (Running Guix Before It Is Installed): To clarify
`./pre-inst-env guix pull` won't upgrade local source tree
and add a footnote to explain why (thanks to Alex Kost).
---
 doc/contributing.texi | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index f855daf..6423d85 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -82,6 +82,12 @@ $ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
 $ ./pre-inst-env guix build hello
 @end example
 
+However, note that @command{./pre-inst-env guix pull} will not upgrade your
+local source tree@footnote{@code{guix pull} fetches the latest guix source,
+compiles it, put it to the store and link "~/.config/guix/latest" to it.}.
+You should run @command{git pull} instead
+if you want to upgrade your local source tree.
+
 @noindent
 Similarly, for a Guile session using the Guix modules:
 
-- 
2.1.4

Re: 2 (possible) problems in documentation

[Ludovic Courtès]

Alex Vong <alexvong1995@gmail.com> skribis:

> From e562ebc9a9e3859ecc0c1c2e8be6f39a44b5be7d Mon Sep 17 00:00:00 2001
> From: Alex Vong <alexvong1995@gmail.com>
> Date: Mon, 2 Nov 2015 23:34:16 +0800
> Subject: [PATCH] doc: To clarify `./pre-inst-env guix pull` won't upgrade
>  local source tree.
>
> * doc/contributing.texi (Running Guix Before It Is Installed): To clarify
> `./pre-inst-env guix pull` won't upgrade local source tree
> and add a footnote to explain why (thanks to Alex Kost).

I pushed a slightly modified version of this patch.  Thanks!

Ludo’.

JavaScript on web site

[Ludovic Courtès]

Alex Vong <alexvong1995@gmail.com> skribis:

> By the way, does anyone know how to build the guix website from
> source? I want to add some labels so that librejs don't complain the
> javascripts being non-free on this page
> <https://www.gnu.org/software/guix/packages/>. I have cloned the
> guix-artwork repo but I don't know how to set-up or build the websites
> (I have zero experience on building websites.).

What does LibreJS say?  The packages.js file in the guix-artwork repo
has a license tag at the top, but maybe it is malformed?

Thanks for looking into it,
Ludo’.

Re: JavaScript on web site

[Mathieu Lirzin]

Hi,

> Alex Vong <alexvong1995@gmail.com> skribis:
>
>> By the way, does anyone know how to build the guix website from
>> source?

There are some instructions in website/README but I must confess they
are not very explicit.  Assuming that DIR is the root of your personal
guix-artwork repository, in a REPL you can do:

  (chdir "DIR/website")
  (add-to-load-path (getcwd))
  (use-modules (www) (www utils))
  (parameterize ((current-url-root (getcwd))
                 (gnu.org-root "https://www.gnu.org"))
    (export-web-site))

Then you will have the generated html files in “DIR/website”.

Simplifying the build process is on my TODO list.  :)

--
Mathieu Lirzin