GNU bug report logs - #43159
[PATCH 0/2] Make 'guix help' helpful

Previous Next

Full log

View this message in rfc822 format

From: help-debbugs <at> gnu.org (GNU bug Tracking System)
To: Ludovic Courtès <ludo <at> gnu.org>
Cc: tracker <at> debbugs.gnu.org
Subject: bug#43159: closed ([PATCH 0/2] Make 'guix help' helpful)
Date: Thu, 10 Sep 2020 10:36:02 +0000

[Message part 1 (text/plain, inline)]

Your message dated Thu, 10 Sep 2020 12:34:46 +0200
with message-id <874ko5hqd5.fsf <at> gnu.org>
and subject line Re: [bug#43159] [PATCHES v2] scripts: Use 'define-command' and have 'guix help' use that.
has caused the debbugs.gnu.org bug report #43159,
regarding [PATCH 0/2] Make 'guix help' helpful
to be marked as done.

(If you believe you have received this mail in error, please contact
help-debbugs <at> gnu.org.)


-- 
43159: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=43159
GNU Bug Tracking System
Contact help-debbugs <at> gnu.org with problems

[Message part 2 (message/rfc822, inline)]

From: Ludovic Courtès <ludo <at> gnu.org>
To: guix-patches <at> gnu.org
Cc: Ludovic Courtès <ludo <at> gnu.org>
Subject: [PATCH 0/2] Make 'guix help' helpful
Date: Tue,  1 Sep 2020 22:35:20 +0200

Hey Guix!

Here’s another long-overdue change that was brought to my
attention: making ‘guix help’ show a synopsis of each command.
While at it, it also groups them in categories (I more or
less followed the manual, but there’s prolly room for
improvement, like a ‘packaging’ category maybe?):

--8<---------------cut here---------------start------------->8---
$ ./pre-inst-env guix help
Usage: guix COMMAND ARGS...
Run COMMAND with ARGS.

COMMAND must be one of the sub-commands listed below:

  main commands:
    deploy        deploy operating systems on a set of machines
    describe      describe the channel revisions currently used
    gc            invoke the garbage collector
    install       install packages
    package       manage packages and profiles
    pull          pull the latest revision of Guix
    remove        removed installed packages
    search        search for packages
    show          show information about packages
    system        build and deploy full operating systems
    time-machine  run commands from a different revision
    upgrade       upgrade packages to their latest version
    weather       report on the available of pre-built package binaries

  commands for developers:
    build        build packages or derivations without installing them
    container    run code in containers created by 'guix environment -C'
    edit         view and edit package definitions
    environment  spawn one-off software environments
    import       import a package definition from an external repository
    pack         create application bundles
    refresh      update existing package definitions

  advanced usage:
    archive    manipulate, export, and import normalized archives (nars)
    challenge  challenge substitute servers, comparing their binaries
    copy       copy store items remotely over SSH
    download   download a file to the store and print its hash
    git        operate on Git repositories
    graph      view and query package dependency graphs
    hash       compute the cryptographic hash of a file
    lint       validate package definitions
    offload    set up and operate build offloading
    processes  list currently running sessions
    publish    publish build results over HTTP
    repl       read-eval-print loop (REPL) for interactive programming
    size       profile the on-disk size of packages

Report bugs to: bug-guix <at> gnu.org.
GNU Guix home page: <https://www.gnu.org/software/guix/>
General help using Guix and GNU software: <https://guix.gnu.org/help/>
--8<---------------cut here---------------end--------------->8---

Much more… helpful than what we currently have, no?  :-)

This works by introducing a new ‘define-command’ macro that each
command now uses and where it defines its synopsis.  ‘guix help’
actually reads files in search of ‘define-command’, which is cheaper
than loading each module and doing some sort of introspection.

The URL shown at the end (“General help”) is also changed, as was
rightfully suggested by zimoun a while back.

Thoughts?

Ludo’.

PS: We can talk about categories, but make sure to turn on the
    bikeshedding limitation mode of your mail client.  :-)

Ludovic Courtès (2):
  scripts: Use 'define-command' and have 'guix help' use that.
  ui: '--help' output links to <https://guix.gnu.org/help/>.

 guix/scripts.scm                  | 29 ++++++++++-
 guix/scripts/archive.scm          |  5 +-
 guix/scripts/authenticate.scm     |  8 ++-
 guix/scripts/build.scm            |  5 +-
 guix/scripts/challenge.scm        |  5 +-
 guix/scripts/container.scm        |  6 ++-
 guix/scripts/copy.scm             |  5 +-
 guix/scripts/deploy.scm           |  3 +-
 guix/scripts/describe.scm         |  3 +-
 guix/scripts/download.scm         |  5 +-
 guix/scripts/edit.scm             |  7 ++-
 guix/scripts/environment.scm      |  5 +-
 guix/scripts/gc.scm               |  4 +-
 guix/scripts/git.scm              |  6 ++-
 guix/scripts/graph.scm            |  5 +-
 guix/scripts/hash.scm             |  5 +-
 guix/scripts/import.scm           |  8 ++-
 guix/scripts/install.scm          |  6 ++-
 guix/scripts/lint.scm             |  5 +-
 guix/scripts/offload.scm          |  6 ++-
 guix/scripts/pack.scm             |  5 +-
 guix/scripts/package.scm          |  4 +-
 guix/scripts/perform-download.scm | 18 ++++---
 guix/scripts/processes.scm        |  4 +-
 guix/scripts/publish.scm          |  5 +-
 guix/scripts/pull.scm             |  4 +-
 guix/scripts/refresh.scm          |  7 ++-
 guix/scripts/remove.scm           |  6 ++-
 guix/scripts/repl.scm             |  5 +-
 guix/scripts/search.scm           |  6 ++-
 guix/scripts/show.scm             |  4 +-
 guix/scripts/size.scm             |  7 ++-
 guix/scripts/substitute.scm       |  7 ++-
 guix/scripts/system.scm           |  4 +-
 guix/scripts/time-machine.scm     |  4 +-
 guix/scripts/upgrade.scm          |  6 ++-
 guix/scripts/weather.scm          |  4 +-
 guix/ui.scm                       | 82 +++++++++++++++++++++++++++----
 38 files changed, 249 insertions(+), 64 deletions(-)

-- 
2.28.0

[Message part 3 (message/rfc822, inline)]

From: Ludovic Courtès <ludo <at> gnu.org>
To: Maxim Cournoyer <maxim.cournoyer <at> gmail.com>
Cc: 43159-done <at> debbugs.gnu.org, Efraim Flashner <efraim <at> flashner.co.il>,
 zimoun <zimon.toutoune <at> gmail.com>
Subject: Re: [bug#43159] [PATCHES v2] scripts: Use 'define-command' and have
 'guix help' use that.
Date: Thu, 10 Sep 2020 12:34:46 +0200

Ludovic Courtès <ludo <at> gnu.org> skribis:

> Here’s a v2 of the patches, where I tried to take your feedback into
> account.  Changes:
>
>   • Categories that appear in uses of ‘define-command’ are now validated
>     at macro-expansion time.
>
>   • (guix scripts) contains an alist of the known categories and
>     ‘show-help’ traverses it.
>
>   • Changed the label for development commands to “commands for
>     development”, and changed “advanced” to “plumbing”.
>
>   • Added a “packaging” category.
>
>   • Fixed the typos you reported.

I pushed this v2 as 3794ce93be8216d8378df7b808ce7f53b1e05a53.

Let’s iterate from here if people have ideas about better categorization
or things like that.

Thanks,
Ludo’.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.