[bug#43159] [PATCH 0/2] Make 'guix help' helpful

[Efraim Flashner <efraim@flashner.co.il>]

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

On Tue, Sep 01, 2020 at 10:35:20PM +0200, Ludovic Courtès wrote:
> 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?):
> 

I dislike the idea that some commands are only for developers and some
commands are "too advanced for the common user" (my words, not yours).
Before bikeshedding about where the options should be, how about:
commands for developers -> commands related to building
advanced usage -> commands related to verification
This way they're still "commands for everybody" and they're more
descriptive than just "advanced" "expert" and "debug" style headers.

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

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