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

[Maxim Cournoyer]

Hi Ludovic,

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

> 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.

I think I'd prefer keeping this one in the reference manual, as that
seems the most natural place to consult first when looking for ways to
fix an unbootable Guix System.  Alternatively, we could have some
section stub simply cross-referencing the Cookbook, but I prefer the
former for now.

> 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).

Convention it seems; although you can't use periods, commas, colons or
leading parenthesis (per info "(texinfo) Node Line Requirements").  I've
now made it 'manual-installation-networking'.

>> +@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").

It seems like @ref can be used "*within* or, more often, at the end of a
sentence", per the above manual, which I'm now using.

>> +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}.

Neat, I had forgotten about that one.

>> +@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.

It should be possible, supposing you are following this Guix Reference
manual in the TTY1 of the bootable installation image; although I'm not
sure you can copy-paste between TTYs; adjusted!

>> +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.

Cool trick, thanks!

>> +@item
>> +Start a minimal guix-daemon in the background:
>
> s/a minimal guix-daemon/@command{guix-daemon}/

Done.

>> +@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.

When using a chroot, it would fail before grub-install would get to run,
defeating the purpose.  It's perhaps workable, but I didn't investigate.

I've now pushed as 4e93ca70da.  Thanks for the review!

Maxim