bug#33673: "guix system --help" does not detail how to use --on-error=strategy

bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[swedebugia]

Hi

The current output is:

--on-error=STRATEGY    apply STRATEGY when an error occurs while reading
FILE

Also the manual currently lacks a cindex for on-error (I had to search
with 's' through multiple false positives to find the relevant section)

Additionally we now have so many commands in the help pages of guix
system and guix build that it would be nice to present them in a more
readable/categorized way.

Would a patches for improvement in these areas be accepted?

-- 
Cheers 
Swedebugia

-------- Original Message --------
Subject: Re: error: rmdir: Device or resource busy
Date: 2018-12-08 09:24
From: swedebugia@riseup.net
To: Fredrik Salomonsson <plattfot@gmail.com>
Cc: help-guix <help-guix@gnu.org>, Help-Guix
<help-guix-bounces+swedebugia=riseup.net@gnu.org>

Hej!

On 2018-12-08 09:05, Fredrik Salomonsson wrote:
> Hello,
> 
> tried installing GuixSD 0.16. But hitting a cryptic error.
> 
> guix system init /mnt/etc/config.scm /mnt
> --substitute-urls="http://berlin.guixsd.org http://mirror.hydra.gnu.org"
> ...
> /gnu/store/sh9x3mhl5q60yxhl861kpk6vm70l3w81-bootloader-installer
> 
> initializing operating system under '/mnt'...
> guix system: error: rmdir: Device or resource busy
> 
> This was working fine with 0.15.
> 
> Is there a way to get a better backtrace from system init? 

Yes!

From the manual: 
'--on-error=STRATEGY'
     Apply STRATEGY when an error occurs when reading FILE.  STRATEGY
     may be one of the following:

     'nothing-special'
          Report the error concisely and exit.  This is the default
          strategy.

     'backtrace'
          Likewise, but also display a backtrace.

     'debug'
          Report the error and enter Guile's debugger.  From there, you
          can run commands such as ',bt' to get a backtrace, ',locals'
          to display local variable values, and more generally inspect
          the state of the program.  *Note (guile)Debug Commands::, for
          a list of available debugging commands.

Actually the --help to "guix system" hints about this but it is not
telling how to use it, which is a bug I think. (i'm going to report it
and send a patch)

> Or does anyone
> know what the error might be?

I never saw it before.

bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[Ludovic Courtès]

Hi,

swedebugia@riseup.net skribis:

> The current output is:
>
> --on-error=STRATEGY    apply STRATEGY when an error occurs while reading
> FILE

FWIW I think it’s reasonable for ‘--help’ to be generally more concise
than the manual.  We could list the possible strategies here, but that
might clutter the output more than is desirable.

> Additionally we now have so many commands in the help pages of guix
> system and guix build that it would be nice to present them in a more
> readable/categorized way.
>
> Would a patches for improvement in these areas be accepted?

Improvements are always welcome of course.  The main criterion would be
to remain consistent with the rest of Guix and with GNU conventions that
we follow.  Maybe it’s best to discuss what you have in mind first?

Thank you,
Ludo’.

bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[Efraim Flashner]

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

On Sun, Dec 09, 2018 at 12:16:47AM +0100, Ludovic Courtès wrote:
> Hi,
> 
> swedebugia@riseup.net skribis:
> 
> > The current output is:
> >
> > --on-error=STRATEGY    apply STRATEGY when an error occurs while reading
> > FILE
> 
> FWIW I think it’s reasonable for ‘--help’ to be generally more concise
> than the manual.  We could list the possible strategies here, but that
> might clutter the output more than is desirable.
> 
> > Additionally we now have so many commands in the help pages of guix
> > system and guix build that it would be nice to present them in a more
> > readable/categorized way.
> >
> > Would a patches for improvement in these areas be accepted?
> 
> Improvements are always welcome of course.  The main criterion would be
> to remain consistent with the rest of Guix and with GNU conventions that
> we follow.  Maybe it’s best to discuss what you have in mind first?
> 
> Thank you,
> Ludo’.
> 

I'd go with (one of: nothing-special, backtrace, debug)
with the assumption that for more information the manual is more
verbose.

I also just noticed that we have 'man guix-system', which could be more
verbose on the subject without needing to fit in a concise output.

-- 
Efraim Flashner   <efraim@flashner.co.il>   אפרים פלשנר
GPG key = A28B F40C 3E55 1372 662D  14F7 41AA E7DC CA3D 8351
Confidentiality cannot be guaranteed on emails sent or received unencrypted

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

bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[swedebugia]

On 2018-12-11 08:18, Efraim Flashner wrote:
> On Sun, Dec 09, 2018 at 12:16:47AM +0100, Ludovic Courtès wrote:
>> Hi,
>>
>> swedebugia@riseup.net skribis:
>>
>> > The current output is:
>> >
>> > --on-error=STRATEGY    apply STRATEGY when an error occurs while reading
>> > FILE
>>
>> FWIW I think it’s reasonable for ‘--help’ to be generally more concise
>> than the manual.  We could list the possible strategies here, but that
>> might clutter the output more than is desirable.
>>
>> > Additionally we now have so many commands in the help pages of guix
>> > system and guix build that it would be nice to present them in a more
>> > readable/categorized way.
>> >
>> > Would a patches for improvement in these areas be accepted?
>>
>> Improvements are always welcome of course.  The main criterion would be
>> to remain consistent with the rest of Guix and with GNU conventions that
>> we follow.  Maybe it’s best to discuss what you have in mind first?
>>
>> Thank you,
>> Ludo’.
>>
> 
> I'd go with (one of: nothing-special, backtrace, debug)
> with the assumption that for more information the manual is more
> verbose.

Sounds good to me. Clutter is a problem we already have it seems so lets
not make it worse.

> 
> I also just noticed that we have 'man guix-system', which could be more
> verbose on the subject without needing to fit in a concise output.

Where do I edit this man-page?

-- 
Cheers 
Swedebugia

bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[Ludovic Courtès]

Hi!

Efraim Flashner <efraim@flashner.co.il> skribis:

> On Sun, Dec 09, 2018 at 12:16:47AM +0100, Ludovic Courtès wrote:

[...]

>> Improvements are always welcome of course.  The main criterion would be
>> to remain consistent with the rest of Guix and with GNU conventions that
>> we follow.  Maybe it’s best to discuss what you have in mind first?
>> 
>> Thank you,
>> Ludo’.
>> 
>
> I'd go with (one of: nothing-special, backtrace, debug)
> with the assumption that for more information the manual is more
> verbose.

Sounds good to me.  Would you like to send a patch?

> I also just noticed that we have 'man guix-system', which could be more
> verbose on the subject without needing to fit in a concise output.

Manual pages are generated from the ‘--help’ output, the canonical
documentation being the Info manual.

Thanks,
Ludo’.

bug#33673: PATCH: Fwd: Re: bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[swedebugia]

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

Is this patch ok?


-------- Forwarded Message --------
Subject: Re: bug#33673: "guix system --help" does not detail how to use 
--on-error=strategy
Date: Tue, 11 Dec 2018 18:10:06 +0100
From: Ludovic Courtès <ludo@gnu.org>
To: Efraim Flashner <efraim@flashner.co.il>
CC: swedebugia@riseup.net, 33673@debbugs.gnu.org

Hi!

Efraim Flashner <efraim@flashner.co.il> skribis:

> On Sun, Dec 09, 2018 at 12:16:47AM +0100, Ludovic Courtès wrote:

[...]

>> Improvements are always welcome of course.  The main criterion would be
>> to remain consistent with the rest of Guix and with GNU conventions that
>> we follow.  Maybe it’s best to discuss what you have in mind first?
>> 
>> Thank you,
>> Ludo’.
>> 
>
> I'd go with (one of: nothing-special, backtrace, debug)
> with the assumption that for more information the manual is more
> verbose.

Sounds good to me.  Would you like to send a patch?

> I also just noticed that we have 'man guix-system', which could be more
> verbose on the subject without needing to fit in a concise output.

Manual pages are generated from the ‘--help’ output, the canonical
documentation being the Info manual.

Thanks,
Ludo’.

[-- Attachment #2: 0001-system-Clarify-the-three-strategies-available.patch --]
[-- Type: text/x-patch, Size: 1747 bytes --]

From e71273a1b3b20bba8f4174ac4b98925bbc36ac0d Mon Sep 17 00:00:00 2001
From: swedebugia <swedebugia@riseup.net>
Date: Fri, 14 Dec 2018 19:41:41 +0100
Subject: [PATCH] system: Clarify the three strategies available.

* guix/scripts/system.scm (show-help): Clarify the three choices.
* doc/guix.texi (Invoking guix system): Add 3 @cindex to make on-error=strategy
  easier to find.
---
 doc/guix.texi           | 3 +++
 guix/scripts/system.scm | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 20b5013fd..4c204c619 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -22628,6 +22628,9 @@ appear in the @code{operating-system} declaration actually exist
 needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
 RAM Disk}).  Passing this option skips these tests altogether.
 
+@cindex on-error
+@cindex on-error strategy
+@cindex error strategy
 @item --on-error=@var{strategy}
 Apply @var{strategy} when an error occurs when reading @var{file}.
 @var{strategy} may be one of the following:
diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm
index 8eb32c62b..d94917100 100644
--- a/guix/scripts/system.scm
+++ b/guix/scripts/system.scm
@@ -993,7 +993,7 @@ Some ACTIONS support additional ARGS.\n"))
                          instead of reading FILE, when applicable"))
   (display (G_ "
       --on-error=STRATEGY
-                         apply STRATEGY when an error occurs while reading FILE"))
+                         apply STRATEGY (one of: nothing-special, backtrace, debug) when an error occurs while reading FILE."))
   (display (G_ "
       --file-system-type=TYPE
                          for 'disk-image', produce a root file system of TYPE
-- 
2.18.0

bug#33673: PATCH: Fwd: Re: bug#33673: "guix system --help" does not detail how to use --on-error=strategy

[Ludovic Courtès]

Hello,

swedebugia <swedebugia@riseup.net> skribis:

> From e71273a1b3b20bba8f4174ac4b98925bbc36ac0d Mon Sep 17 00:00:00 2001
> From: swedebugia <swedebugia@riseup.net>
> Date: Fri, 14 Dec 2018 19:41:41 +0100
> Subject: [PATCH] system: Clarify the three strategies available.
>
> * guix/scripts/system.scm (show-help): Clarify the three choices.
> * doc/guix.texi (Invoking guix system): Add 3 @cindex to make on-error=strategy
>   easier to find.
> ---
>  doc/guix.texi           | 3 +++
>  guix/scripts/system.scm | 2 +-
>  2 files changed, 4 insertions(+), 1 deletion(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 20b5013fd..4c204c619 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -22628,6 +22628,9 @@ appear in the @code{operating-system} declaration actually exist
>  needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
>  RAM Disk}).  Passing this option skips these tests altogether.
>  
> +@cindex on-error
> +@cindex on-error strategy
> +@cindex error strategy
>  @item --on-error=@var{strategy}
>  Apply @var{strategy} when an error occurs when reading @var{file}.
>  @var{strategy} may be one of the following:
> diff --git a/guix/scripts/system.scm b/guix/scripts/system.scm
> index 8eb32c62b..d94917100 100644
> --- a/guix/scripts/system.scm
> +++ b/guix/scripts/system.scm
> @@ -993,7 +993,7 @@ Some ACTIONS support additional ARGS.\n"))
>                           instead of reading FILE, when applicable"))
>    (display (G_ "
>        --on-error=STRATEGY
> -                         apply STRATEGY when an error occurs while reading FILE"))
> +                         apply STRATEGY (one of: nothing-special, backtrace, debug) when an error occurs while reading FILE."))

I wrapped this line and applied it.

Thank you!

Ludo’.