Feature Request: Help formatting features

[gdevenyi]

Right now, options are dumped into a help block in the order they're defined, with no ability to format/group them.

A nice simple addition would be to allow a way to place a spacer label in the help output, classically to split up between "basic options" and "advanced options"

[matejak]

Please don't hesitate to come up with an example how would you imagine a nicely-formatted help message.

[gdevenyi]

Sure of course, here's the idea, hacked up version of a help from a script I already use argbash with

iterativeN3 imhomogenaeity correction
Usage: ./iterativeN3.sh [-h|--help] [--(no-)standalone] [--distance <arg>] [--levels <arg>] [--cycles <arg>] [--iters <arg>] [--lambda <arg>] [--fwhm <arg>] [--stop <arg>] [--isostep <arg>] [--lsq6-resample-type <arg>] [--prior-config <arg>] [-c|--(no-)clobber] [-v|--(no-)verbose] [-d|--(no-)debug] <input> <output>
        <input>: Input MINC file
        <output>: Output MINC File
        -h, --help: Prints help
        --standalone, --no-standalone: Save intermediate outputs during processing (off by default)

Iteration parameters:
        --distance: Initial distance for correction (default: '400')
        --levels: Levels of correction with distance halving (default: '4')
        --cycles: Cycles of correction at each level (default: '3')
        --iters: Iterations of correction for each cycle (default: '25')

N3 parameters:
        --lambda: Spline regularization value (default: '2e-6')
        --fwhm: Intensity histogram smoothing fwhm (default: '0.1')
        --stop: Stopping criterion for N3 (default: '1e-5')
        --isostep: Isotropic resampling resolution in mm for N3 (default: '4')

Advanced parameters:
        --lsq6-resample-type: (Standalone) Type of resampling lsq6(rigid) output files undergo, can be "coordinates" or a number for the isotropic resolution in mni_icbm152_t1_tal_nlin_sym_09c space (default: 'coordinates')
        --prior-config: Config file to use for models and priors (default: 'mni_icbm152_nlin_sym_09c.cfg')
        -c, --clobber, --no-clobber: Overwrite files that already exist (off by default)
        -v, --verbose, --no-verbose: Run commands verbosely (on by default)
        -d, --debug, --no-debug: Show all internal comands and logic for debug (off by default)

With a ARGBASH header something like:

#!/bin/bash
#
# ARG_HELP([iterativeN3 imhomogenaeity correction])
# ARG_OPTIONAL_BOOLEAN([standalone],[],[Save intermediate outputs during processing])
# ARG_SECTION_SEPARATOR([Iteration parameters])
# ARG_OPTIONAL_SINGLE([distance],[],[Initial distance for correction],[400])
# ARG_OPTIONAL_SINGLE([levels],[],[Levels of correction with distance halving],[4])
# ARG_OPTIONAL_SINGLE([cycles],[],[Cycles of correction at each level],[3])
# ARG_OPTIONAL_SINGLE([iters],[],[Iterations of correction for each cycle],[25])
# ARG_SECTION_SEPARATOR([N3 parameters])
# ARG_OPTIONAL_SINGLE([lambda],[],[Spline regularization value],[2e-6])
# ARG_OPTIONAL_SINGLE([fwhm],[],[Intensity histogram smoothing fwhm],[0.1])
# ARG_OPTIONAL_SINGLE([stop],[],[Stopping criterion for N3],[1e-5])
# ARG_OPTIONAL_SINGLE([isostep],[],[Isotropic resampling resolution in mm for N3],[4])
# ARG_SECTION_SEPARATOR([Advanced parameters])
# ARG_OPTIONAL_SINGLE([lsq6-resample-type],[],[(Standalone) Type of resampling lsq6(rigid) output files undergo, can be "coordinates" or a number for the isotropic resolution in mni_icbm152_t1_tal_nlin_sym_09c space],[coordinates])
# ARG_OPTIONAL_SINGLE([prior-config],[],[Config file to use for models and priors],[mni_icbm152_nlin_sym_09c.cfg])
# ARG_OPTIONAL_BOOLEAN([clobber],[c],[Overwrite files that already exist])
# ARG_OPTIONAL_BOOLEAN([verbose],[v],[Run commands verbosely],[on])
# ARG_OPTIONAL_BOOLEAN([debug],[d],[Show all internal comands and logic for debug],[])
# ARG_POSITIONAL_SINGLE([input],[Input MINC file])
# ARG_POSITIONAL_SINGLE([output],[Output MINC File])
# ARGBASH_GO()

Thus I'm requesting something like ARG_SECTION_SEPARATOR where I can provide a bit of formatting.

Inspired by python's argparse formatting: https://stackoverflow.com/questions/54670642/how-to-group-arguments-into-sections-for-a-programs-help-message

Very happy if it sticks close to it.