Open kneasle opened 3 years ago
A longer description could be something like --go-after-one-whole-pull , or, even longer, --go-automatically-after-only-one-whole-pull , but it's possible that neither is necessarily any clearer for people without much previous bellringing experience.
Perhaps, to address this, one would want to ask new(er) ringers what name makes (the most) sense to them, or how they would prefer command options be documented.
For example, someone with extensive programming background but no ringing history might prefer shorter commands resulting from shorter flags. Mathematicians, like anyone who is typing out each command rather than copying and pasting or running as a script or alias, might be more likely used to the shorter conventions of single-character commands followed by a single dash (hyphen, minus), so perhaps it's reasonable that the longer version of the flag name err on the more-descriptive side. For inclusion in aliases or scripts, there is a case to be made for descriptive flag names, but also for short flag names there as well, to increase readability and reduce the incidence of errors from typos.
People who like reading manuals, or man pages, rather than combing through the source code directly, might find that manner of (explicit) documentation helpful-and-sufficient, while people who prefer to primarily "guess and check" command-flag use as a first line of attempt might rely more on a --help option and on commands that remain the same over time, in a backwards-compatible manner.
Dunno if this helps. Sorry it's so verbose and rambling.
I made a FB poll for this, and the strong favourite was 'whole pull and go' - which I'm quite happy with. Anyone who cares about typing will use -u
or -H
anyway, so I don't mind making the command names a little longer.
You also bring up another point - the --help
page is currently an indigestible wall of text. We should probably put a manual somewhere else (e.g. a website) and make --help
as succinct as possible. I'd be happy to accept PRs fixing either of these from anyone who's interested in some non-coding contributions :)...
Someone pointed out that
--up-down-in
isn't very intuitive for non-handbell ringers.--up-down-off
or--up-down-go
were suggested replacements, but personally I think it's better to keep it consistent.