Hi Ricardo, On 12/11/24 13:14, Ricardo Wurmus wrote: > Hi Guix, > > I found the help output not to be very helpful whenever there are > sub-commands. The output contains options that are not relevant to the > sub-command. The options also don't appear to be ordered. > > Here is an example. I want to know more about "guix system > docker-image", so I run "guix system docker-image --help". This is the > output I get: > > --8<---------------cut here---------------start------------->8--- > Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE] > Build the operating system declared in FILE according to ACTION. > Some ACTIONS support additional ARGS. > > The valid values for ACTION are: > > search search for existing service types > edit edit the definition of an existing service type > reconfigure switch to a new operating system configuration > roll-back switch to the previous operating system configuration > describe describe the current system > list-generations list the system generations > switch-generation switch to an existing operating system configuration > delete-generations delete old system generations > build build the operating system without installing anything > container build a container that shares the host's store > vm build a virtual machine image that shares the host's store > image build a Guix System image > docker-image build a Docker image > init initialize a root file system to run GNU > extension-graph emit the service extension graph in Dot format > shepherd-graph emit the graph of shepherd services in Dot format > > -L, --load-path=DIR prepend DIR to the package module search path > -K, --keep-failed keep build tree of failed builds > -k, --keep-going keep going when some of the derivations fail > -n, --dry-run do not build the derivations > --fallback fall back to building when the substituter fails > --no-substitutes build instead of resorting to pre-built substitutes > --substitute-urls=URLS > fetch substitute from URLS if they are authorized > --no-grafts do not graft packages > --no-offload do not attempt to offload builds > --max-silent-time=SECONDS > mark the build as failed after SECONDS of silence > --timeout=SECONDS mark the build as failed after SECONDS of activity > --rounds=N build N times in a row to detect non-determinism > -c, --cores=N allow the use of up to N CPU cores for the build > -M, --max-jobs=N allow at most N build jobs > --debug=LEVEL produce debugging output at LEVEL > -d, --derivation return the derivation of the given system > -e, --expression=EXPR consider the operating-system EXPR evaluates to > instead of reading FILE, when applicable > --allow-downgrades for 'reconfigure', allow downgrades to earlier > channel revisions > --on-error=STRATEGY > apply STRATEGY (one of nothing-special, backtrace, > or debug) when an error occurs while reading FILE > --list-image-types list available image types > -t, --image-type=TYPE for 'image', produce an image of TYPE > --image-size=SIZE for 'image', produce an image of SIZE > --no-bootloader for 'init', do not install a bootloader > --volatile for 'image', make the root file system volatile > --persistent for 'vm', make the root file system persistent > --label=LABEL for 'image', label disk image with LABEL > --save-provenance save provenance information > --share=SPEC for 'vm' and 'container', share host file system with > read/write access according to SPEC > --expose=SPEC for 'vm' and 'container', expose host file system > directory as read-only according to SPEC > -N, --network for 'container', allow containers to access the network > -r, --root=FILE for 'vm', 'image', 'container' and 'build', > make FILE a symlink to the result, and > register it as a garbage collector root > --full-boot for 'vm', make a full boot sequence > --no-graphic for 'vm', use the tty that we are started in for IO > --skip-checks skip file system and initrd module safety checks > -v, --verbosity=LEVEL use the given verbosity LEVEL > > --graph-backend=BACKEND > use BACKEND for 'extension-graph' and 'shepherd-graph' > > -I, --list-installed[=REGEXP] > for 'describe' and 'list-generations', list installed > packages matching REGEXP > > --list-targets list available targets > --target=TRIPLET cross-build for TRIPLET--e.g., "aarch64-linux-gnu" > > --list-systems list available systems > -s, --system=SYSTEM attempt to build for SYSTEM--e.g., "i686-linux" > > --help-docker-format list options specific to the docker image type. > > -h, --help display this help and exit > -V, --version display version information and exit > > Report bugs to: bug-guix@gnu.org. > GNU Guix home page: > General help using Guix and GNU software: > --8<---------------cut here---------------end--------------->8--- > > Note that this is the same output as for "guix system --help". > > I don't think it's great to see all these "for 'vm'" qualifiers on the > right-hand side. > > Here is what I propose: > > - In the case of commands that offer sub-commands, remove *all* the > options from the help output of the main command (e.g. "guix system > --help"), and only showing the list of available sub-commands. > > - For "guix [command] [sub-command] --help" show only options to this > sub-command. > > - optionally, group all generic options (e.g. --system, --help, > --version, etc) under a single heading. > > What do you think? That's the functionality I would expect, so +1