Documentation

Documentation

[Vincent Legoll]

Hello,

when & how is the documentation here :
https://www.gnu.org/software/guix/manual/guix.html
updated ?

I ask, because doing some git grep in a recent git checkout
showed me something in doc/guix.texi that I couldn't find in
that online manual...

Then I searched how to build the doc, and found in README:

See the manual for the installation instructions, either by running

  info -f doc/guix.info "(guix) Installation"

but...

info: doc/guix.info: No such file or directory

So how do I make that doc so that I can read the "installation
instructions" which will tell me how to make the doc...

Looks adequately recursive to me... ;-)

Maybe a very simple INSTALL file with the basic explained
would help newbies...

Or did I miss something ?

-- 
Vincent Legoll

Re: Documentation

[Leo Famulari]

On Fri, Sep 02, 2016 at 05:45:02PM +0200, Vincent Legoll wrote:
> when & how is the documentation here :
> https://www.gnu.org/software/guix/manual/guix.html
> updated ?

I'm not sure, but I think it's updated whenever we make a new release.

> Then I searched how to build the doc, and found in README:
> 
> See the manual for the installation instructions, either by running
> 
>   info -f doc/guix.info "(guix) Installation"
> 
> but...
> 
> info: doc/guix.info: No such file or directory

On GuixSD, `info guix` should work. On other systems...

> So how do I make that doc so that I can read the "installation
> instructions" which will tell me how to make the doc...

... from a checkout of our Git repo, you can do:

`guix environment guix -- make doc/guix.info`

Similarly, you can do `make doc/guix.html`.

If the Git checkout is new, you will need to run the ./configure script
first. And if so, you almost always want to do it like this:

`./configure --localstatedir=/var`.

https://www.gnu.org/software/guix/manual/html_node/Building-from-Git.html#Building-from-Git

Re: Documentation

[Vincent Legoll]

Thanks for the answers, still no joy for me...

On Fri, Sep 2, 2016 at 6:08 PM, Leo Famulari <leo@famulari.name> wrote:
> On Fri, Sep 02, 2016 at 05:45:02PM +0200, Vincent Legoll wrote:
>> when & how is the documentation here :
>> https://www.gnu.org/software/guix/manual/guix.html
>> updated ?
>
> I'm not sure, but I think it's updated whenever we make a new release.
>
>> Then I searched how to build the doc, and found in README:
>>
>> See the manual for the installation instructions, either by running
>>
>>   info -f doc/guix.info "(guix) Installation"
>>
>> but...
>>
>> info: doc/guix.info: No such file or directory
>
> On GuixSD, `info guix` should work. On other systems...

That works, but I cannot find what I'm searching for: libressl, that
I can see with (in a current git checkout) :

$ git grep libressl
[...]
doc/guix.texi:(define libressl-instead-of-openssl
doc/guix.texi:  (package-input-rewriting `((,openssl . ,libressl))))
doc/guix.texi:(define git-with-libressl
doc/guix.texi:  (libressl-instead-of-openssl git))
doc/guix.texi:with @var{libressl}.  Then we use it to define a
@dfn{variant} of the
doc/guix.texi:@var{git} package that uses @var{libressl} instead of
@var{openssl}.

What am I missing ?
Or maybe I'm very bad at info, always found its interface weird...

>> So how do I make that doc so that I can read the "installation
>> instructions" which will tell me how to make the doc...
>
> ... from a checkout of our Git repo, you can do:
>
> `guix environment guix -- make doc/guix.info`

I don't have guix installed on this system, see below:

> Similarly, you can do `make doc/guix.html`.

$ make doc/guix.html
make: *** No rule to make target `doc/guix.html'.  Stop.

The configure script is not working here (ubuntu 14.04) bare git
checkout, see below...

> If the Git checkout is new, you will need to run the ./configure script
> first. And if so, you almost always want to do it like this:
>
> `./configure --localstatedir=/var`.

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.

nothing to commit, working directory clean
$ ./configure --localstatedir=/var
configure: error: cannot find install-sh, install.sh, or shtool in
build-aux "."/build-aux

-- 
Vincent Legoll

Re: Documentation

[Leo Famulari]

On Fri, Sep 02, 2016 at 06:45:37PM +0200, Vincent Legoll wrote:
> > On GuixSD, `info guix` should work. On other systems...
> 
> That works, but I cannot find what I'm searching for: libressl, that
> I can see with (in a current git checkout) :
> 
> $ git grep libressl
> [...]
> doc/guix.texi:(define libressl-instead-of-openssl
> doc/guix.texi:  (package-input-rewriting `((,openssl . ,libressl))))
> doc/guix.texi:(define git-with-libressl
> doc/guix.texi:  (libressl-instead-of-openssl git))
> doc/guix.texi:with @var{libressl}.  Then we use it to define a
> @dfn{variant} of the
> doc/guix.texi:@var{git} package that uses @var{libressl} instead of
> @var{openssl}.
> 
> What am I missing ?
> Or maybe I'm very bad at info, always found its interface weird...

I'm not sure, I actually don't use `info` very much either. Maybe your
GuixSD installation has not been updated since the relevant text was
added to the manual?

> >> So how do I make that doc so that I can read the "installation
> >> instructions" which will tell me how to make the doc...
> >
> > ... from a checkout of our Git repo, you can do:
> >
> > `guix environment guix -- make doc/guix.info`

> nothing to commit, working directory clean
> $ ./configure --localstatedir=/var
> configure: error: cannot find install-sh, install.sh, or shtool in
> build-aux "."/build-aux

Sorry, I forgot the first step, `./bootstrap`, which is mentioned here:

https://www.gnu.org/software/guix/manual/html_node/Building-from-Git.html#Building-from-Git

Re: Documentation

[Vincent Legoll]

>> Or maybe I'm very bad at info, always found its interface weird...
>
> I'm not sure, I actually don't use `info` very much either. Maybe your
> GuixSD installation has not been updated since the relevant text was
> added to the manual?

I regularly do guix pull && guix system reconfigure, like earlier today...

Isn't that enough ?

Which package contains this documentation ?

>> $ ./configure --localstatedir=/var
>> configure: error: cannot find install-sh, install.sh, or shtool in
>> build-aux "."/build-aux
>
> Sorry, I forgot the first step, `./bootstrap`, which is mentioned here:

OK, after ./bootstrap, now ./configure --localstatedir=/var works, but not:

$ make doc/guix.html

make[1]: Entering directory `/home/vlegoll/repo/upstream/gnu/guix'
make[1]: Leaving directory `/home/vlegoll/repo/upstream/gnu/guix'
Updating ./doc/version.texi
  MAKEINFO doc/guix.html
doc/guix.texi:6621: @include: could not find os-config-bare-bones.texi
doc/guix.texi:6726: @include: could not find os-config-desktop.texi
doc/guix.texi:6733: @include: could not find os-config-lightweight-desktop.texi
make: *** [doc/guix.html] Error 1

-- 
Vincent Legoll

Re: Documentation

[Leo Famulari]

On Fri, Sep 02, 2016 at 07:46:51PM +0200, Vincent Legoll wrote:
> OK, after ./bootstrap, now ./configure --localstatedir=/var works, but not:
> 
> $ make doc/guix.html
> 
> make[1]: Entering directory `/home/vlegoll/repo/upstream/gnu/guix'
> make[1]: Leaving directory `/home/vlegoll/repo/upstream/gnu/guix'
> Updating ./doc/version.texi
>   MAKEINFO doc/guix.html
> doc/guix.texi:6621: @include: could not find os-config-bare-bones.texi
> doc/guix.texi:6726: @include: could not find os-config-desktop.texi
> doc/guix.texi:6733: @include: could not find os-config-lightweight-desktop.texi

I guess that you have to build Guix in order to get those files:

`make`

Re: Documentation

[Ludovic Courtès]

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

>>> Or maybe I'm very bad at info, always found its interface weird...
>>
>> I'm not sure, I actually don't use `info` very much either. Maybe your
>> GuixSD installation has not been updated since the relevant text was
>> added to the manual?
>
> I regularly do guix pull && guix system reconfigure, like earlier today...
>
> Isn't that enough ?
>
> Which package contains this documentation ?

It contains the documentation of the currently-packaged Guix snapshot:

--8<---------------cut here---------------start------------->8---
$ guix package -A guix
guix	0.11.0	out	gnu/packages/package-management.scm:71:2
guix	0.11.0-1.4420	out	gnu/packages/package-management.scm:216:4
--8<---------------cut here---------------end--------------->8---

We update the snapshot once every few weeks.

Eventually ‘guix pull’ will be able to update guix.info; it doesn’t do
that currently, which is a problem as you noticed.

>>> $ ./configure --localstatedir=/var
>>> configure: error: cannot find install-sh, install.sh, or shtool in
>>> build-aux "."/build-aux
>>
>> Sorry, I forgot the first step, `./bootstrap`, which is mentioned here:
>
> OK, after ./bootstrap, now ./configure --localstatedir=/var works, but not:
>
> $ make doc/guix.html

Try “make && make html”.

However, I think you should try ‘info’ again.  The interface is not any
weirder than that of a browser after all, see “info info”.  :-)

Ludo’.

Re: Documentation

[myglc2]

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

> Hello,
>
> when & how is the documentation here :
> https://www.gnu.org/software/guix/manual/guix.html
> updated ?
>
> I ask, because doing some git grep in a recent git checkout
> showed me something in doc/guix.texi that I couldn't find in
> that online manual...

Hi Vincent, the INFO that "comes with" 'guix pull' is from an earlier
git commit. The www html version may be even earlier, not sure.

Anyway, to read INFO from the latest 'git pull' you can do ...

git clone http://git.savannah.gnu.org/cgit/guix.git/
cd guix
guix environment guix
./bootstrap
./configure --localstatedir=/var
make

To read the INFO in emacs ...

emacs
'C-u F1 i'
"<YOURPATHTOGUIX>/guix/doc/guix.1"

Or, to always read the git version, I add this to my emacs init file ...

(with-eval-after-load 'info
  (info-initialize)
  (add-to-list 'Info-directory-list
	       " <YOURPATHTOGUIX>/guix/doc"))

HTH, George