bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

When I clone and build Guix from scratch, it produces the untracked file
"doc/stamp-1" which contains the version number built into the Guix doc
and appears to be created from a call to 'git describe'.

But with subsequent git commit/make cycles the version does not
change. It doesn't change when the guix package is updated either. For
example, after pulling and building the recent commit updating the guix
package ...

commit 8b3aea9d9e022b20137cec93f668df8fa051abd9
Author: Ludovic Courtès <ludo@gnu.org>
Date:   Sun Jun 10 23:31:01 2018 +0200

    gnu: guix: Update to 77a1aac.

    * gnu/packages/package-management.scm (guix): Update to 77a1aac.

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ git describe 8b3aea9d9e022b20137cec93f668df8fa051abd9
v0.14.0-6300-g8b3aea9d9

"doc/stamp-1" and guix version remain "stuck" on June 8th ...

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ cat doc/stamp-1
@set UPDATED 8 June 2018
@set UPDATED-MONTH June 2018
@set EDITION 0.14.0.5478-1458f7
@set VERSION 0.14.0.5478-1458f7

g1@sysi31 ~/gom/.emacs.d/guix/guix [gmm]$ ./pre-inst-env guix --version
guix (GNU Guix) 0.14.0.5478-1458f7

They remain stuck after 'make clean; make', and './bootstrap;
./configure; make' The only way I found to "unstick" them is 'sudo git
clean -dfx'.

Side questions:

1) why don't you gitignore "doc/stamp-1"?
2) why don't you gitignore .po files?

TIA - George

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ludovic Courtès]

Hello George,

George Clemmer <myglc2@gmail.com> skribis:

> But with subsequent git commit/make cycles the version does not
> change. It doesn't change when the guix package is updated either. For
> example, after pulling and building the recent commit updating the guix
> package ...

Currently the version number is hardcoded in ‘configure.ac’, so the fact
that running “git pull && make” doesn’t change it is expected.  So to
me, it’s not a bug.

We could improve on that (see for instance how Guile does it with
build-aux/git-version-gen), but it still won’t be updated at each commit
because that’d be inconvenient: ‘config.h’ would regenerated, so in turn
we’d need to rebuild all of the C++ code.

‘guix pull’ does the right thing though, which I think is more important
than the build tree.

> Side questions:
>
> 1) why don't you gitignore "doc/stamp-1"?

Good idea, done!  :-)

> 2) why don't you gitignore .po files?

Because they are checked in.

Thanks for your report.

Ludo’.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Ludovic Courtès <ludo@gnu.org> writes:

> Hello George,
>
> George Clemmer <myglc2@gmail.com> skribis:
>
>> But with subsequent git commit/make cycles the version does not
>> change. It doesn't change when the guix package is updated either. For
>> example, after pulling and building the recent commit updating the guix
>> package ...
>
> Currently the version number is hardcoded in ‘configure.ac’, so the fact
> that running “git pull && make” doesn’t change it is expected.  So to
> me, it’s not a bug.
>
> We could improve on that (see for instance how Guile does it with
> build-aux/git-version-gen), but it still won’t be updated at each commit
> because that’d be inconvenient: ‘config.h’ would regenerated, so in turn
> we’d need to rebuild all of the C++ code.

Hi Ludo’,

Ok, cool. Thanks for the clarification. So... how about adding a
footnote to '(guix) Running Guix Before It Is Installed' something like
...

(3) The Guix version in the Guix build is set by './configure'. Thus,
when guix is run from the Git working tree by './pre-inst-env guix' or a
'~/.config/guix/latest’ symlink, the version reported by 'guix
--version' is not updated by subsequent 'git pull; make' steps. To
update the version (and rebuild everything), you may use 'git clean
-dfx; ./bootstrap; ./configure; make'.

Note: I also tried 'make distclean' and 'make maintainer-clean' which
didn't work.

> ‘guix pull’ does the right thing though, which I think is more important
> than the build tree.

Agreed.

>> Side questions:
>>
>> 1) why don't you gitignore "doc/stamp-1"?
>
> Good idea, done!  :-)

Thanks!

>> 2) why don't you gitignore .po files?
>
> Because they are checked in.

I guess I meant to say, why does the build change these checked-in
files? It seems like they should be ignored.

TIA - George

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ludovic Courtès]

George Clemmer <myglc2@gmail.com> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hello George,
>>
>> George Clemmer <myglc2@gmail.com> skribis:
>>
>>> But with subsequent git commit/make cycles the version does not
>>> change. It doesn't change when the guix package is updated either. For
>>> example, after pulling and building the recent commit updating the guix
>>> package ...
>>
>> Currently the version number is hardcoded in ‘configure.ac’, so the fact
>> that running “git pull && make” doesn’t change it is expected.  So to
>> me, it’s not a bug.
>>
>> We could improve on that (see for instance how Guile does it with
>> build-aux/git-version-gen), but it still won’t be updated at each commit
>> because that’d be inconvenient: ‘config.h’ would regenerated, so in turn
>> we’d need to rebuild all of the C++ code.
>
> Hi Ludo’,
>
> Ok, cool. Thanks for the clarification. So... how about adding a
> footnote to '(guix) Running Guix Before It Is Installed' something like
> ...
>
> (3) The Guix version in the Guix build is set by './configure'. Thus,
> when guix is run from the Git working tree by './pre-inst-env guix' or a
> '~/.config/guix/latest’ symlink, the version reported by 'guix
> --version' is not updated by subsequent 'git pull; make' steps. To
> update the version (and rebuild everything), you may use 'git clean
> -dfx; ./bootstrap; ./configure; make'.

I’m not comfortable documenting this because it’s nothing specific to
Guix.

Besides, note that ~/.config/guix/latest no longer exists.

>>> 2) why don't you gitignore .po files?
>>
>> Because they are checked in.
>
> I guess I meant to say, why does the build change these checked-in
> files? It seems like they should be ignored.

The build changes them only if you start anew.  In normal circumstances
(meaning you didn’t run “distclean”), they remained unchanged if I’m not
mistaken.

So yeah, it’s occasionally annoying, but I’m not sure how to fix this.

Ludo’.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Ludovic Courtès <ludo@gnu.org> writes:

> George Clemmer <myglc2@gmail.com> skribis:
>
>> Ok, cool. Thanks for the clarification. So... how about adding a
>> footnote to '(guix) Running Guix Before It Is Installed' something like
>> ...
>>
>> (3) The Guix version in the Guix build is set by './configure'. Thus,
>> when guix is run from the Git working tree by './pre-inst-env guix' or a
>> '~/.config/guix/latest’ symlink, the version reported by 'guix
>> --version' is not updated by subsequent 'git pull; make' steps. To
>> update the version (and rebuild everything), you may use 'git clean
>> -dfx; ./bootstrap; ./configure; make'.
>
> I’m not comfortable documenting this because it’s nothing specific to
> Guix.

So to summarize: This behavior is a side effect of how GNU tools
work. It is obvious to anyone who understands them. You don't want to
describe things that are obvious. I understand.

But I think many users don't have a clue about GNU build tools. They may
be puzzled by how pre-inst-env works. I think the footnote would be
helpful for them. I urge you to reconsider.

> Besides, note that ~/.config/guix/latest no longer exists.

Yes, I saw you revamped Guix pull but I haven't actually used guix pull
in over a year.  I need to check the new one out.

- George

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ludovic Courtès]

Hello,

George Clemmer <myglc2@gmail.com> skribis:

> Ludovic Courtès <ludo@gnu.org> writes:
>
>> George Clemmer <myglc2@gmail.com> skribis:
>>
>>> Ok, cool. Thanks for the clarification. So... how about adding a
>>> footnote to '(guix) Running Guix Before It Is Installed' something like
>>> ...
>>>
>>> (3) The Guix version in the Guix build is set by './configure'. Thus,
>>> when guix is run from the Git working tree by './pre-inst-env guix' or a
>>> '~/.config/guix/latest’ symlink, the version reported by 'guix
>>> --version' is not updated by subsequent 'git pull; make' steps. To
>>> update the version (and rebuild everything), you may use 'git clean
>>> -dfx; ./bootstrap; ./configure; make'.
>>
>> I’m not comfortable documenting this because it’s nothing specific to
>> Guix.
>
> So to summarize: This behavior is a side effect of how GNU tools
> work. It is obvious to anyone who understands them. You don't want to
> describe things that are obvious. I understand.
>
> But I think many users don't have a clue about GNU build tools. They may
> be puzzled by how pre-inst-env works. I think the footnote would be
> helpful for them. I urge you to reconsider.

It’s not that I find it “obvious” etc.  This specific part of the manual
targets an audience of developers, and I think it’s reasonable to expect
this audience to know where to look things up.

The other aspect, from a maintenance and readability viewpoint, is that
we could quickly add up lots of explanations that we’ll have to keep
up-to-date and that may make more important information harder to find.

I hope that makes sense, but I’m happy to hear what others think.

Ludo’.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Leo Famulari]

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

On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
> The other aspect, from a maintenance and readability viewpoint, is that
> we could quickly add up lots of explanations that we’ll have to keep
> up-to-date and that may make more important information harder to find.

Yeah, I'm worried about this too. It's tough to strike the correct
balance.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Leo Famulari <leo@famulari.name> writes:

> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
>> The other aspect, from a maintenance and readability viewpoint, is that
>> we could quickly add up lots of explanations that we’ll have to keep
>> up-to-date and that may make more important information harder to find.
>
> Yeah, I'm worried about this too. It's tough to strike the correct
> balance.

IMO Guix is great for hackers, maintainers and sysops. The doc is
appropriate for such users, well done, spare, and already voluminous.

This footnote suggestion, and others rejected in the past, are motivated
by my assumption that you will want to make Guix attractive to less
sophisticated users.

Maybe my assumption is wrong? Maybe you want only "elite" users?

Or maybe you want to defer the less sophisticated users to later in the
development cycle?

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Clément Lassieur]

Hi George,

George Clemmer <myglc2@gmail.com> writes:

> Leo Famulari <leo@famulari.name> writes:
>
>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
>>> The other aspect, from a maintenance and readability viewpoint, is that
>>> we could quickly add up lots of explanations that we’ll have to keep
>>> up-to-date and that may make more important information harder to find.
>>
>> Yeah, I'm worried about this too. It's tough to strike the correct
>> balance.
>
> IMO Guix is great for hackers, maintainers and sysops. The doc is
> appropriate for such users, well done, spare, and already voluminous.
>
> This footnote suggestion, and others rejected in the past, are motivated
> by my assumption that you will want to make Guix attractive to less
> sophisticated users.

But non-hacker users can use Guix pull!  Running Guix before it is
installed (with pre-inst-env) is described in the manual as a "Hacker
trick".

> Maybe my assumption is wrong? Maybe you want only "elite" users?

Guix pull is well documented, and should be usable for non-elite users.

> Or maybe you want to defer the less sophisticated users to later in the
> development cycle?

Clément

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Clément Lassieur]

Clément Lassieur <clement@lassieur.org> writes:

> Hi George,
>
> George Clemmer <myglc2@gmail.com> writes:
>
>> Leo Famulari <leo@famulari.name> writes:
>>
>>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
>>>> The other aspect, from a maintenance and readability viewpoint, is that
>>>> we could quickly add up lots of explanations that we’ll have to keep
>>>> up-to-date and that may make more important information harder to find.
>>>
>>> Yeah, I'm worried about this too. It's tough to strike the correct
>>> balance.
>>
>> IMO Guix is great for hackers, maintainers and sysops. The doc is
>> appropriate for such users, well done, spare, and already voluminous.
>>
>> This footnote suggestion, and others rejected in the past, are motivated
>> by my assumption that you will want to make Guix attractive to less
>> sophisticated users.
>
> But non-hacker users can use Guix pull!  Running Guix before it is
> installed (with pre-inst-env) is described in the manual as a "Hacker
> trick".
>
>> Maybe my assumption is wrong? Maybe you want only "elite" users?
>
> Guix pull is well documented, and should be usable for non-elite users.
>
>> Or maybe you want to defer the less sophisticated users to later in the
>> development cycle?
>
> Clément

Sorry if I sounded a bit rude, it wasn't my intention.  :-)

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ludovic Courtès]

Hi George,

George Clemmer <myglc2@gmail.com> skribis:

> Leo Famulari <leo@famulari.name> writes:
>
>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
>>> The other aspect, from a maintenance and readability viewpoint, is that
>>> we could quickly add up lots of explanations that we’ll have to keep
>>> up-to-date and that may make more important information harder to find.
>>
>> Yeah, I'm worried about this too. It's tough to strike the correct
>> balance.
>
> IMO Guix is great for hackers, maintainers and sysops. The doc is
> appropriate for such users, well done, spare, and already voluminous.
>
> This footnote suggestion, and others rejected in the past, are motivated
> by my assumption that you will want to make Guix attractive to less
> sophisticated users.
>
> Maybe my assumption is wrong? Maybe you want only "elite" users?

No, definitely not; I’m sorry if this is the impression this gave.

Like I wrote, my main concern is about keeping the documentation focused
and maintainable.  Sometimes we have to document things that are
technically outside of Guix because there’s no real canonical
documentation and because users would be impaired without it—I’m
thinking for instance of bits in the “Preparing for Installation”
section.

In this case, we’d be documenting something that’s both outside of Guix
and not vital for routine usage, and that’s mostly covered by the
Autoconf manual.  Hence my reluctance.

I hope that makes sense.

Ludo’.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Ludovic Courtès <ludo@gnu.org> writes:

> Hi George,
>
> George Clemmer <myglc2@gmail.com> skribis:
>
>> Leo Famulari <leo@famulari.name> writes:
>>
>>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
>>>> The other aspect, from a maintenance and readability viewpoint, is that
>>>> we could quickly add up lots of explanations that we’ll have to keep
>>>> up-to-date and that may make more important information harder to find.
>>>
>>> Yeah, I'm worried about this too. It's tough to strike the correct
>>> balance.
>>
>> IMO Guix is great for hackers, maintainers and sysops. The doc is
>> appropriate for such users, well done, spare, and already voluminous.
>>
>> This footnote suggestion, and others rejected in the past, are motivated
>> by my assumption that you will want to make Guix attractive to less
>> sophisticated users.
>>
>> Maybe my assumption is wrong? Maybe you want only "elite" users?
>
> No, definitely not; I’m sorry if this is the impression this gave.
>
> Like I wrote, my main concern is about keeping the documentation focused
> and maintainable.  Sometimes we have to document things that are
> technically outside of Guix because there’s no real canonical
> documentation and because users would be impaired without it—I’m
> thinking for instance of bits in the “Preparing for Installation”
> section.
>
> In this case, we’d be documenting something that’s both outside of Guix
> and not vital for routine usage, and that’s mostly covered by the
> Autoconf manual.  Hence my reluctance.
>
> I hope that makes sense.

Hi Ludo’,

I see the situation this way:

The current doc reflects the needs and sensibilities of the hackers,
maintainers, and sysops that have built Guix. These "elite" users have
different needs and judge what is important quite differently from end
users. This guarantees that the current doc is inadequate for end users.
So, if, as you say, you want to make Guix accessible to end users, you
need to make changes in the doc.  The questions: How? What?

May I suggest ...

a) Adopt a less defensive posture when responding to user questions,
   comments, and bug reports.

b) Be pro-active about capturing support resolutions in the doc.

This thread presents a nice example of what I am talking about. To
recap:

I said: I use 'pre-inst-env guix' this way and this is a bug.

You said: Developers expect this, so it's not a bug.

A less defensive response: Hmm, You are using 'pre-inst-env guix' in a
way we didn't anticipate. What are the benefits of using it this way? I
see how this is a bug for your use case.

We discussed a workaround. I suggested adding it to the doc.

You said: I’m not comfortable documenting this because it’s nothing
specific to Guix.

I said: I urge you to reconsider.

You said: This part of the manual targets developers... they know where
to look things up. [The more we write the more we have to maintain.]

And Clément Lassieur <clement@lassieur.org> added:

> But non-hacker users can use Guix pull!  Running Guix before it is
> installed (with pre-inst-env) is described in the manual as a "Hacker
> trick".

> Guix pull is well documented, and should be usable for non-elite users.

OK, but I'm non-elite and I have used Guix for 2+ years. I have tried
both. I prefer pre-inst-env. I expect others will too. The fact is that
pre-inst-env does not correctly report the version after 'git pull;
make'. How can you know that this won't be a problem for other users?
It only takes 4 lines to explain this and provide a workaround, e.g.,

Proposed (revised) footnote:

(3) The Guix version in the Guix build is set by './bootstrap'. Thus,
the version reported by './pre-inst-env guix --version' is not updated
by subsequent 'git pull; make' steps. To update the version (and rebuild
everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.

- George

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Nils Gillmann]

George Clemmer transcribed 3.9K bytes:
> 
> Ludovic Courtès <ludo@gnu.org> writes:
> 
> > Hi George,
> >
> > George Clemmer <myglc2@gmail.com> skribis:
> >
> >> Leo Famulari <leo@famulari.name> writes:
> >>
> >>> On Wed, Jun 13, 2018 at 08:54:49AM +0200, Ludovic Courtès wrote:
> >>>> The other aspect, from a maintenance and readability viewpoint, is that
> >>>> we could quickly add up lots of explanations that we’ll have to keep
> >>>> up-to-date and that may make more important information harder to find.
> >>>
> >>> Yeah, I'm worried about this too. It's tough to strike the correct
> >>> balance.
> >>
> >> IMO Guix is great for hackers, maintainers and sysops. The doc is
> >> appropriate for such users, well done, spare, and already voluminous.
> >>
> >> This footnote suggestion, and others rejected in the past, are motivated
> >> by my assumption that you will want to make Guix attractive to less
> >> sophisticated users.
> >>
> >> Maybe my assumption is wrong? Maybe you want only "elite" users?
> >
> > No, definitely not; I’m sorry if this is the impression this gave.
> >
> > Like I wrote, my main concern is about keeping the documentation focused
> > and maintainable.  Sometimes we have to document things that are
> > technically outside of Guix because there’s no real canonical
> > documentation and because users would be impaired without it—I’m
> > thinking for instance of bits in the “Preparing for Installation”
> > section.
> >
> > In this case, we’d be documenting something that’s both outside of Guix
> > and not vital for routine usage, and that’s mostly covered by the
> > Autoconf manual.  Hence my reluctance.
> >
> > I hope that makes sense.
> 
> Hi Ludo’,
> 
> I see the situation this way:
> 
> The current doc reflects the needs and sensibilities of the hackers,
> maintainers, and sysops that have built Guix. These "elite" users have
> different needs and judge what is important quite differently from end
> users. This guarantees that the current doc is inadequate for end users.
> So, if, as you say, you want to make Guix accessible to end users, you
> need to make changes in the doc.  The questions: How? What?

I understand where you are coming from, and I understand the trouble Ludovic
(probably) has to find the right balance of content.
Before I comment more below: I'm trying to adjust to a wide range of
people with the least possible knowledge too in the new GNUnet documentation.
Some documentations I looked at had this introductionary style for elements
when they were first used. Texinfo has this element which seems to be less
used because it renders terrible (or did not try with custom output definitions
so far). It's sort of a box element. It would be good to extend this, at least
that's my current idea, to eventually contribute to Texinfo when I have a better
view on what we want.
Long text short nonsense: you end up with lots of work and long books if you
do it right. It should be done this way. Maybe if not directly applied we
could collect the proposals somewhere in the repository? I've recently
started to strip out a whole chapter with repetive installation instructions
in GNUnet. A while back I would've argued for keeping it, that we really
need to cover and guide every case.
Some projects have written "An introduction to..." books to lead up to
the manual.
In my opinion access to knowledge should be easy and without much 'rough
edges' to get it.
Do we keep it selfcontained? Reference other books? A middle path? It's
difficult to get it right if you don't have the time to think about this
as a fulltime job.

> May I suggest ...
> 
> a) Adopt a less defensive posture when responding to user questions,
>    comments, and bug reports.
> 
> b) Be pro-active about capturing support resolutions in the doc.
> 
> This thread presents a nice example of what I am talking about. To
> recap:
> 
> I said: I use 'pre-inst-env guix' this way and this is a bug.
> 
> You said: Developers expect this, so it's not a bug.
> 
> A less defensive response: Hmm, You are using 'pre-inst-env guix' in a
> way we didn't anticipate. What are the benefits of using it this way? I
> see how this is a bug for your use case.
> 
> We discussed a workaround. I suggested adding it to the doc.
> 
> You said: I’m not comfortable documenting this because it’s nothing
> specific to Guix.
> 
> I said: I urge you to reconsider.
> 
> You said: This part of the manual targets developers... they know where
> to look things up. [The more we write the more we have to maintain.]

Do we really have to assume that everyone has the same skilset who wants
to get involved? Not about this topic, but in general? I think the assumption
that we share the same knowledge is difficult. Part of the excercise is to
reach out, actively, in person. Another part is to try and do it in text (be
it on a website or a (new) chapter in a manual).

> And Clément Lassieur <clement@lassieur.org> added:
> 
> > But non-hacker users can use Guix pull!  Running Guix before it is
> > installed (with pre-inst-env) is described in the manual as a "Hacker
> > trick".
> 
> > Guix pull is well documented, and should be usable for non-elite users.
> 
> OK, but I'm non-elite and I have used Guix for 2+ years. I have tried
> both. I prefer pre-inst-env. I expect others will too. The fact is that
> pre-inst-env does not correctly report the version after 'git pull;
> make'. How can you know that this won't be a problem for other users?
> It only takes 4 lines to explain this and provide a workaround, e.g.,
> 
> Proposed (revised) footnote:
> 
> (3) The Guix version in the Guix build is set by './bootstrap'. Thus,
> the version reported by './pre-inst-env guix --version' is not updated
> by subsequent 'git pull; make' steps. To update the version (and rebuild
> everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.
> 
> - George

Counter-proposal: What about additional man-pages? man has enough sections
to provide well written, to the point, collection of notes for such day-to-day
usage. I'm not against your proposal, just another suggestion in context of
what I've written above.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Hi Nils,

Nils Gillmann <ng0@n0.is> writes:
[...]
> Long text short nonsense: you end up with lots of work and long books if you
> do it right. It should be done this way. Maybe if not directly applied we
> could collect the proposals somewhere in the repository? I've recently
> started to strip out a whole chapter with repetive installation instructions
> in GNUnet. A while back I would've argued for keeping it, that we really
> need to cover and guide every case.
> Some projects have written "An introduction to..." books to lead up to
> the manual.
> In my opinion access to knowledge should be easy and without much 'rough
> edges' to get it.
> Do we keep it selfcontained? Reference other books? A middle path? It's
> difficult to get it right if you don't have the time to think about this
> as a fulltime job.
[...]
>
> Do we really have to assume that everyone has the same skilset who wants
> to get involved? Not about this topic, but in general? I think the assumption
> that we share the same knowledge is difficult. Part of the excercise is to
> reach out, actively, in person. Another part is to try and do it in text (be
> it on a website or a (new) chapter in a manual).
[...]
> Counter-proposal: What about additional man-pages? man has enough sections
> to provide well written, to the point, collection of notes for such day-to-day
> usage. I'm not against your proposal, just another suggestion in context of
> what I've written above.

I think the Guix strategy, AIUI, of putting 99.9% of the doc effort into
a single doc via Texinfo is very efficient. INFO and HTML reach the two
extreme user types: hackers that use INFO and people use that google.

Partitioning the problem into sub-parts is tempting.  But it increases
the risk of a sub-part drifting out of date at which point it is better
to not have had the sub-part ;-)

The Guix "mico-man-page" effectively eliminates a sub-part. Hackers can
use INFO and people who google don't use man, so I think the micro-man
approach is fine.

I think the most promising and productive way for Guix to improve the
end-user-friendliness of the doc is to use end-user "support incidents"
to drive doc additions. At the end of an incident the user question is
fresh in your mind, you have information that you know could have been
helpful to at least one user, and you capture the support effort into
something longer lasting.

- George

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ricardo Wurmus]

Hi George,

> The current doc reflects the needs and sensibilities of the hackers,
> maintainers, and sysops that have built Guix. These "elite" users have
> different needs and judge what is important quite differently from end
> users. This guarantees that the current doc is inadequate for end users.
> So, if, as you say, you want to make Guix accessible to end users, you
> need to make changes in the doc.  The questions: How? What?
[…]
> I said: I use 'pre-inst-env guix' this way and this is a bug.

“pre-inst-env” really should not be used by people other than
developers.  It is only available when building Guix from a clone of the
git repository.

We do not recommend “pre-inst-env” for any other purpose than to make
changes to the code, so I would not like to document the quirks and
limitations of “pre-inst-env” in the manual, as this is not how Guix is
supposed to be used generally.

> Proposed (revised) footnote:
>
> (3) The Guix version in the Guix build is set by './bootstrap'. Thus,
> the version reported by './pre-inst-env guix --version' is not updated
> by subsequent 'git pull; make' steps. To update the version (and rebuild
> everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.

I’m wary of adding this for similar reasons that Ludo wrote earlier.  In
my opinion this ends up cluttering the manual with notes and what I
consider to be only tangentially relevant for readers of the manual.

--
Ricardo

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[Ricardo Wurmus]

Ricardo Wurmus <rekado@elephly.net> writes:

>> Proposed (revised) footnote:
>>
>> (3) The Guix version in the Guix build is set by './bootstrap'. Thus,
>> the version reported by './pre-inst-env guix --version' is not updated
>> by subsequent 'git pull; make' steps. To update the version (and rebuild
>> everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.
>
> I’m wary of adding this for similar reasons that Ludo wrote earlier.  In
> my opinion this ends up cluttering the manual with notes and what I
> consider to be only tangentially relevant for readers of the manual.

An alternative might be to change the output of “guix --version” in the
presence of GUIX_UNINSTALLED, which is set by “pre-inst-env”.  This
could be a simple change in “show-version-and-exit” that would use
something other than “%guix-version” when GUIX_UNINSTALLED is set.

What do others think?

--
Ricardo

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[myglc2]

On 06/16/2018 at 00:24 Ricardo Wurmus writes:

> Ricardo Wurmus <rekado@elephly.net> writes:
>
>>> Proposed (revised) footnote:
>>>
>>> (3) The Guix version in the Guix build is set by './bootstrap'. Thus,
>>> the version reported by './pre-inst-env guix --version' is not updated
>>> by subsequent 'git pull; make' steps. To update the version (and rebuild
>>> everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.
>>
>> I’m wary of adding this for similar reasons that Ludo wrote earlier.  In
>> my opinion this ends up cluttering the manual with notes and what I
>> consider to be only tangentially relevant for readers of the manual.
>
> An alternative might be to change the output of “guix --version” in the
> presence of GUIX_UNINSTALLED, which is set by “pre-inst-env”.  This
> could be a simple change in “show-version-and-exit” that would use
> something other than “%guix-version” when GUIX_UNINSTALLED is set.
>
> What do others think?
>
> --
> Ricardo

I like it.

bug#31786: 'pre-inst-env guix --version' is not updated by new commits"

[George Clemmer]

Ricardo Wurmus <rekado@elephly.net> writes:

> Hi George,
>
>> The current doc reflects the needs and sensibilities of the hackers,
>> maintainers, and sysops that have built Guix. These "elite" users have
>> different needs and judge what is important quite differently from end
>> users. This guarantees that the current doc is inadequate for end users.
>> So, if, as you say, you want to make Guix accessible to end users, you
>> need to make changes in the doc.  The questions: How? What?
> […]
>> I said: I use 'pre-inst-env guix' this way and this is a bug.
>
> “pre-inst-env” really should not be used by people other than
> developers.  It is only available when building Guix from a clone of the
> git repository.
>
> We do not recommend “pre-inst-env” for any other purpose than to make
> changes to the code, so I would not like to document the quirks and
> limitations of “pre-inst-env” in the manual, as this is not how Guix is
> supposed to be used generally.
>
>> Proposed (revised) footnote:
>>
>> (3) The Guix version in the Guix build is set by './bootstrap'. Thus,
>> the version reported by './pre-inst-env guix --version' is not updated
>> by subsequent 'git pull; make' steps. To update the version (and rebuild
>> everything), use 'git clean -dfx; ./bootstrap; ./configure; make'.
>
> I’m wary of adding this for similar reasons that Ludo wrote earlier.  In
> my opinion this ends up cluttering the manual with notes and what I
> consider to be only tangentially relevant for readers of the manual.

Hi Ricardo,

Please read further down the original post. I think you will find that I
already addressed your points.

Collectively, the responses here bring to mind a Harvard Business School
case study I was taught in 1983. The gist of it: Bakers at Holsum Bread
told a salesman that they had figured out how to run his company's bread
making machine at twice the design speed. Because this was twice as fast
as the competitor's machine, they wanted to place a big order for more
machines. When the salesman told the company engineer about the order he
said, "You can't sell any more machines to Holsum because they aren't
using my machine properly!"

- George