[bug#55613] [PATCH] doc: Document how to repair Guix System from a chroot.

[Ludovic Courtès]

Hi!

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> * doc/guix.texi (System Troubleshooting Tips): New chapter.

That’s a much welcome addition.

Since it’s more informal than the manual, how adding it to the cookbook?
I imagine we could have other troubleshooting subsections.

Some minor typographical comments…

> +@anchor{Manual Installation - Networking}

Usually anchor names are lowercase and without spaces (I’m not sure if
it’s a hard requirement or a convention).

> +@cindex troubleshooting, guix system

“Guix System”

> +Boot the image, and proceed with the graphical text-based installer
> +until your network is configured.  Alternatively, you could configure
> +the network manually by following the @pxref{Manual Installation -
> +Networking} section.  If you get the error @samp{RTNETLINK answers:

@pxref is for use in a parenthesized expression; it cannot be used in
the middle of a sentence; in fact, no cross-reference markup can be used
in the middle of a sentence, but I recommend checking the manual
(info "(texinfo) Cross References").

> +Switch to a virtual console (tty) if you haven't already by pressing
> +simultaneously the @samp{Control + Alt + F4} keys.  Mount your file

Rather @kbd{ctrl-alt-F4}.

> +@example sh
> +# mount /dev/sda2 /mnt
> +@end example
> +
> +@item
> +Mount special block devices and Linux-specific directories:
> +
> +@example sh
> +# mount --bind /proc /mnt/proc
> +# mount --bind /sys /mnt/sys
> +# mount --bind /dev /mnt/dev
> +@end example

I’d remove the “#” prompt from examples, for easier copy/pasting
(assuming that’s an option in those circumstances :-)) and for
consistency.

> +Source your user profile to setup the environment, where
> +@samp{$YOUR_USER} is adjusted to the user name used for the Guix System
> +you are attempting to repair.
> +
> +@example sh
> +sh-5.1# source /home/$YOUR_USER/.guix-profile/etc/profile

You can use a “meta-syntactic variable” for the user name: write
@var{user}, both in the text and example.

> +@item
> +Start a minimal guix-daemon in the background:

s/a minimal guix-daemon/@command{guix-daemon}/

> +@example sh
> +sh-5.1# guix-daemon --build-users-group=guixbuild --disable-chroot &

What’s the rationale for ‘--disable-chroot’?  It’s safer to avoid it.

Thanks,
Ludo’.