guix describe user experience improvement proposition

guix describe user experience improvement proposition

[Ekaitz Zarraga]

Hi all,

Yesterday I wanted to use `guix describe` and I felt quite helpless when choosing the format I wanted.

I suggest adding the possible format list in the help of the `guix describe -h` command. That way the feature discovery is easier for users that don't want to dig in the code.

It should be easy to add, something like the diff I add below (untested and horrible, the idea is to help me explain myself rather than serving as a contribution).

How do you feel about this?
Interesting for anyone? Is there any reason why it's not added already that I might be missing?

Cheers,
Ekaitz

The obnoxious diff:

diff --git a/guix/scripts/describe.scm b/guix/scripts/describe.scm
index f13f221da9..0222ed0951 100644
--- a/guix/scripts/describe.scm
+++ b/guix/scripts/describe.scm
@@ -42,11 +42,13 @@
 ;;; Command-line options.
 ;;;

+(define available-formats '("human" "channels" "json" "recutils"))
+
 (define %options
   ;; Specifications of the command-line options.
   (list (option '(#\f "format") #t #f
                 (lambda (opt name arg result)
-                  (unless (member arg '("human" "channels" "json" "recutils"))
+                  (unless (member arg available-formats)
                     (leave (G_ "~a: unsupported output format~%") arg))
                   (alist-cons 'format (string->symbol arg) result)))
         (option '(#\p "profile") #t #f
@@ -68,8 +70,8 @@
 (define (show-help)
   (display (G_ "Usage: guix describe [OPTION]...
 Display information about the channels currently in use.\n"))
-  (display (G_ "
-  -f, --format=FORMAT    display information in the given FORMAT"))
+  (display (string-append (G_ "
+  -f, --format=FORMAT    display information in the given FORMAT: ") (string-join available-formats "|")))
   (display (G_ "
   -p, --profile=PROFILE  display information about PROFILE"))
   (newline)

Re: guix describe user experience improvement proposition

[zimoun]

Dear

On Tue, 12 May 2020 at 21:07, Ekaitz Zarraga <ekaitz@elenq.tech> wrote:

> I suggest adding the possible format list in the help of the `guix describe -h` command. That way the feature discovery is easier for users that don't want to dig in the code.

Usually, the way to add such information is '--list-formats', e.g.,
see "guix graph"with '--list-types' and '-list-backends'.  I do not
know if it is an usually. ;-)


> -  (display (G_ "
> -  -f, --format=FORMAT    display information in the given FORMAT"))
> +  (display (string-append (G_ "
> +  -f, --format=FORMAT    display information in the given FORMAT: ") (string-join available-formats "|")))

The issue is the length, so at least it should on 2 lines to fix screen size.


All the best,
simon

Re: guix describe user experience improvement proposition

[Ekaitz Zarraga]

On Tuesday, May 12, 2020 9:44 PM, zimoun <zimon.toutoune@gmail.com> wrote:

> Dear
>
> On Tue, 12 May 2020 at 21:07, Ekaitz Zarraga ekaitz@elenq.tech wrote:
>
> > I suggest adding the possible format list in the help of the `guix describe -h` command. That way the feature discovery is easier for users that don't want to dig in the code.
>
> Usually, the way to add such information is '--list-formats', e.g.,
> see "guix graph"with '--list-types' and '-list-backends'. I do not
> know if it is an usually. ;-)

But do you think it's interesting?
Or is it just me?

I like the `--list-types` approach. If it's interesting I would contribute with a patch.

> > -   (display (G_ "
> > -   -f, --format=FORMAT display information in the given FORMAT"))
> >
> > -   (display (string-append (G_ "
> > -   -f, --format=FORMAT display information in the given FORMAT: ") (string-join available-formats "|")))
>
> The issue is the length, so at least it should on 2 lines to fix screen size.

Yeah I was aware of that. I was just adding the diff to try to share what I wanted, rather than like something we should add with no changes. :)

Thanks for the feedback!

Ekaitz

Re: guix describe user experience improvement proposition

[Ekaitz Zarraga]

On Tuesday, May 12, 2020 10:13 PM, Ekaitz Zarraga <ekaitz@elenq.tech> wrote:
> On Tuesday, May 12, 2020 9:44 PM, zimoun zimon.toutoune@gmail.com wrote:
> > Usually, the way to add such information is '--list-formats', e.g.,
> > see "guix graph"with '--list-types' and '-list-backends'. I do not
> > know if it is an usually. ;-)
>
> But do you think it's interesting?
> Or is it just me?
>
> I like the `--list-types` approach. If it's interesting I would contribute with a patch.

Hi,

It would be something like this, tested and working.

Opinions?

Best,
Ekaitz

diff --git a/guix/scripts/describe.scm b/guix/scripts/describe.scm
index f13f221da9..69c6d8482f 100644
--- a/guix/scripts/describe.scm
+++ b/guix/scripts/describe.scm
@@ -42,13 +42,26 @@
 ;;; Command-line options.
 ;;;

+(define %available-formats '("human" "channels" "json" "recutils"))
+
+(define (list-formats)
+  (display (G_ "The available formats are:\n"))
+  (newline)
+  (for-each (lambda (f)
+              (format #t "  - ~a~%" f))
+            %available-formats))
+
 (define %options
   ;; Specifications of the command-line options.
   (list (option '(#\f "format") #t #f
                 (lambda (opt name arg result)
-                  (unless (member arg '("human" "channels" "json" "recutils"))
+                  (unless (member arg %available-formats)
                     (leave (G_ "~a: unsupported output format~%") arg))
                   (alist-cons 'format (string->symbol arg) result)))
+        (option '("list-formats") #f #f
+                (lambda (opt name arg result)
+                  (list-formats)
+                  (exit 0)))
         (option '(#\p "profile") #t #f
                 (lambda (opt name arg result)
                   (alist-cons 'profile (canonicalize-profile arg)
@@ -70,6 +83,8 @@
 Display information about the channels currently in use.\n"))
   (display (G_ "
   -f, --format=FORMAT    display information in the given FORMAT"))
+  (display (G_ "
+      --list-formats     display available formats"))
   (display (G_ "
   -p, --profile=PROFILE  display information about PROFILE"))
   (newline)