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: > General help using Guix and GNU software: > --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 . > > 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 אפרים פלשנר GPG key = A28B F40C 3E55 1372 662D 14F7 41AA E7DC CA3D 8351 Confidentiality cannot be guaranteed on emails sent or received unencrypted