| Message ID | 20200901203520.21103-1-ludo@gnu.org |
|---|---|
| Headers | show |
| Series | Make 'guix help' helpful | expand |
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 > > > >
Hi, Efraim Flashner <efraim@flashner.co.il> skribis: > 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). Yeah, I’m ambivalent about this as well. > Before bikeshedding about where the options should be, how about: > commands for developers -> commands related to building Rather, “commands for development“, because that’s really what ‘guix environment’ is about, for instance, but saying ‘development’ rather than ‘developers’ is probably wise. > advanced usage -> commands related to verification Well that only works for ‘challenge’ (which I’d like to put in the hands of ‘normal’ users, so I’m not comfortable with the ‘advanced’ label, but OTOH, it’s clearly not one of the commands you’d begin with.) What about archive, copy, download, etc.? > This way they're still "commands for everybody" and they're more > descriptive than just "advanced" "expert" and "debug" style headers. Understood. Thanks for your feedback! Ludo’.
On Wed, Sep 02, 2020 at 11:50:17AM +0200, Ludovic Courtès wrote: > Hi, > > Efraim Flashner <efraim@flashner.co.il> skribis: > > > 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). > > Yeah, I’m ambivalent about this as well. > > > Before bikeshedding about where the options should be, how about: > > commands for developers -> commands related to building > > Rather, “commands for development“, because that’s really what ‘guix > environment’ is about, for instance, but saying ‘development’ rather > than ‘developers’ is probably wise. > > > advanced usage -> commands related to verification > > Well that only works for ‘challenge’ (which I’d like to put in the hands > of ‘normal’ users, so I’m not comfortable with the ‘advanced’ label, but > OTOH, it’s clearly not one of the commands you’d begin with.) > > What about archive, copy, download, etc.? > It seemed loosely related. If you're running 'guix pull; guix upgrade' you're not first running 'guix download https://path/to/source.tar.xz' or copying packages between machines or challenging the reproducibility of the packages. That's for after you have the packages you want in your profile or environment. > > This way they're still "commands for everybody" and they're more > > descriptive than just "advanced" "expert" and "debug" style headers. > > Understood. > > Thanks for your feedback! > > Ludo’.
Hi Ludo, On Tue, 1 Sep 2020 at 22:36, Ludovic Courtès <ludo@gnu.org> wrote: > remove removed installed packages s/removed/remove > environment spawn one-off software environments spawn one-off? > PS: We can talk about categories, but make sure to turn on the > bikeshedding limitation mode of your mail client. :-) Looking for "bikeshedder"? ;-) Category theory is always complicated. :-) It depends what do you mean by developers (or development)? To me, download, hash, lint, repl and size are also commands used on a daily basis for developing. On the other hand, container is claimed to be "experimental" in the manual so it should go in the "advanced" section. Well, instead of "advanced usage", I propose "plumbing commands" Thank you for this change. Cheers, simon
Hi, zimoun <zimon.toutoune@gmail.com> skribis: >> environment spawn one-off software environments > > spawn one-off? “One-off” is used as an adjective to mean a software environment that is used once and then thrown away. Per WordNet: --8<---------------cut here---------------start------------->8--- Overview of noun one-off The noun one-off has 1 sense (no senses from tagged texts) 1. one-off -- (a happening that occurs only once and is not repeated) --8<---------------cut here---------------end--------------->8--- Thanks for your suggestions! Ludo’.
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@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(-)