Hello,

I'm not sure if I've posted to the mailing list before.
If not (or even if so), greetings everyone.

While we're on the subject of improvements to opthelp, I have a few
ideas to propose.

On 2022-02-04 07:53, Kaz Kylheku wrote:
> I'm probably going to just split it up into multiple
> functions/methods:
>
> opthelp: just the help
>
> opthelp-conventions: print the notes about the argument conventions
>
> opthelp-types: print the type legend.

I think this is an excellent idea.

> While the notes is verbose and unnecessary to someone who generally
> knows how to use command line options, the type legend could be of
> help to the user; I don't like it being disabled together.

I have actually been sidestepping the long opthelp by providing two
command-line options in my programs:

- ‘--usage’ for a short description, where I trim-right the opthelp
  starting from #/\nNotes:\n/.
  (Incidentally, this is how I found the stream bug, *twice* ― I was
  going to report the bug, forgot about it, then got bitten by it again
  and finally decided to fix it.)

- ‘--help’ for a long description, i.e., including the conventions and
  type legend (which are most definitely useful).

---

Now for my first idea: I wonder if there should be a way to pair the
type information with a more descriptive argument name, e.g., displaying
“-v LEVEL” or “-v VERBOSITY” instead of “-v DEC”.
This could be achieved in a backwards-compatible way by allowing the
type slot to also be a list, the cadr of which would be the name of the
argument.
For instance (to reuse part of the manual's example):

  (define-option-struct prog-opts nil
    (v verbose (:dec "LEVEL")
     "Verbosity LEVEL. Higher values produce more chatter.")
    ...)

Then I see a few possibilities for how to relate the argument name to
the type legend:

- After the description of each type, list (on one wrapped line) the
  names of the arguments that are of that type.

- Allow the caddr of the listified type slot to be the description to be
  added to the type legend.
  For example:

    (define-option-struct prog-opts nil
      (v verbose (:dec "LEVEL" "Decimal integer indicating verbosity level")
       "Verbosity LEVEL. Higher values produce more chatter.")
      ...)

  In this case, assuming --verbose is the only :dec option, DEC would be
  omitted from the type legend.
  Unless we want to allow the user (developer) to leverage DEC's
  existing description, for example:

    (define-option-struct prog-opts nil
      (v verbose (:dec "LEVEL" "DEC value indicating verbosity level")
       "Verbosity LEVEL. Higher values produce more chatter.")
      ...)

- Allow the developer to add more types to the type legend by way of a
  function, e.g., (register-opthelp-type) or something.

---

My second idea would be to reformat the display of each option in order
to gain a bit of horizontal space for the option description (and also
to keep the short and long options close together, so they're easy to
see at a glance).
Instead of

  --verbose=DEC         (-v DEC)   Verbosity LEVEL. Higher values
                                   produce more chatter.

we could have

  -v, --verbose DEC       Verbosity LEVEL. Higher values produce more
                          chatter.

and then in the conventions explain what this syntax means: that short
options do not accept an equals for the argument but long options accept
a space or an equals.
(But keep sorting according to the long option's name.)
If no short option exists, just align the long option to the left (or not).

(This style is essentially that of Python's pip package manager, among
likely many others.)

This shorter style pairs well with custom type names, which can become
long; we save space by writing them out only once.
(Actually, (list :dec) is already quite long.)

I can submit patches for all of the foregoing, if we deem the ideas to
be worthwhile.

Best regards,
Paul