Re: doc: installation: fix ~root confusion (was Re: doc: Removing much of Binary Installation)

["pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de>]

Hi Matt.  I would almost want to push your changes, but we still
disagree on some wordings.

Also,

Matt <matt@excalamus.com> writes:
> I realigned the subject.  It was previously changed to "doc: Removing
> much of Binary Installation" which is misleading.  The topic is how to
> clarify installation based on reported confusion, not about removing
> text.  The reported confusion was on the use of '~root'.  Explicit
> mention of '~root' is only necessary when the manual details how
> 'guix-install.sh' works.  Since 'guix-install.sh' is the recommended
> method of installation, such level of detail is unnecessary,
> inappropriate, and impractical.  The suggested changes address the
> issue, only incidentally, by removing text.

Yes, however the removal means that we should move the sections

* 2.2 Requirements
* 2.3 Running the Test Suite

to the Contributing manual in doc/contributing.texi.  WDYT?  You said,
it could be a separate discussion, but in my opinion it would be part of
the same patch.


> +@cindex foreign distro
> +@cindex Guix System

“@cindex Guix System” is inappropriate, because instructions on Guix
System are not here.


> +You can install the Guix package management tool on top of an existing
> +GNU/Linux or GNU/Hurd system@footnote{Currently only the Linux-libre
> +kernel is fully supported. […]

No.

First of all, using guix-install.sh as per your instructions, one
installs the Guix distribution *and* package management tool.  Either
say “You can install the Guix package management tool and distribution”
or “You can install Guix”.

Next, I believe Guix cannot currently be built on existing GNU/Hurd
systems, because guile-fibers does not work.  I do not really know
enough, but I would not mention Hurd support.  Additionally “only the
Linux-libre kernel” is incorrect, because running Guix on non-libre
Linux is fully supported.  Running Guix System there is not supported
(by us).


>> You suggested in your mail:
>>
>> Matt matt@excalamus.com> writes:
>> > Readers interested in those details may read the code for 'guix-install.sh'.
>>
>> Could you add this suggestion to your diff?
>
> I don't see that as relevant to the reader.  The ability to read the
> source is implicit in it being provided, which it is.

Yes, you are right.


> The suggested changes remove superfluous commentary on the recommended
> binary installation process which create confusion.

“remove superfluous commentary” could be part of a commit message for
your changes, if you agree.


> What do you think is lost that isn't captured by the following bulleted list?
>
> +The script guides you through the following:
> +@itemize
> +@item Download and extract the binary tarball
> +@item Set up the build daemon
> +@item Make the ‘guix’ command available to non-root users
> +@item Configure substitute servers
> +@end itemize

The list is fine.


>> Therefore, the sentence would have to be removed: “The following
>> sections describe two methods of installation, binary installation
>> and building from source.”
>
> I've removed that sentence for a different reason.  I also revised the
> sentence, "This is often quicker than installing from source, which is
> described in the next sections", to simply, "described later".
>
> The reason is that Chapter 2 doesn't currently explain building or
> installing from source.  Building and installing from source is
> currently covered much later in Section 22.1.  Whether or not the
> Installation section should cover building from source is a separate
> issue and shouldn't be part of this discussion.

This could be:

described later (@pxref{Building from Git}).


>> Matt matt@excalamus.com> writes:
>> > - Add commas in appropriate places; after "For...Ubuntu-based
>> > systems", "Likewise", and the 'or' within the list of substitutes
>>
>> I’m not a native speaker, but I believe the commas are not
>> necessary.  There particularly does not need to be an Oxford comma
>> before ‘or’.  There could be, but there is no reason to change it.
>
> Ah, the One True Brace Style of natural language :)
>
> I think there's already enough controversy in this thread.  I've changed it back :)

:D  However, please also do not change:

> -Likewise on openSUSE:
> +Likewise, on openSUSE:



>> Similarly, IMO the nuances are more appropriate in the old wording
>> “For Debian or a derivative such as Ubuntu,” rather than your change
>> “For Debian and Ubuntu-based systems”.
>
> The current wording is, "If you're running Debian or a derivative such
> as Ubuntu..."  None of the suggested changes include the wording you
> give.
>
> What are the nuances?  If they matter, we should probably make them explicit.

The nuance is that Ubuntu is a derivative of Debian.  It can be
bootstrapped with Debian’s dpkg, although I did not follow a recent
e-mail thread on how to do this from a Guix-provided dpkg.


> +@quotation Note
> +By default, binary installations of Guix build @emph{everything} from
> +source.  This makes each installation and upgrade very expensive.
> +@xref{On Trusting Binaries} for a discussion of why this is the default.
> […]
> -
> -@quotation Note
> -If you do not enable substitutes, Guix will end up building
> -@emph{everything} from source on your machine, making each installation
> -and upgrade very expensive.  @xref{On Trusting Binaries}, for a
> -discussion of reasons why one might want do disable substitutes.
>  @end quotation

Better not change the wording?  I believe enabling substitutes is not
the default.


IMHO The discussion about whether Upgrading Guix should recommend to
edit the systemd service of the Debian guix package is for a separate
second patch.

Regards,
Florian