In usage description: positional arg between options instead of after

[bpj]

In this generated usage description the positional input file argument comes second to last between the -e and -E options rather than last as I would expect, although in the code it is defined the very last. Is this a bug or have I misunderstood something?

Usage: links2list [-h] [-l <id> <label>] [--cf <cf-label>]
       [--see <see-label>] [-c {lower,l,none,n,title,t,upper,u}]
       [-a {lower,l,number,n,upper,u}] [-r <markup format>]
       [-f <sprintf format>] [-w <markup format>] [-d]
       [-e <name> <char|code>]
       <filename>.<ext>|<lib.name> [{lua,json,y[a]ml}]
       [-E <filename>.<ext>|<lib.name> [{lua,json,y[a]ml}]]

[p-ouellette]

Could you share some code to reproduce this issue?

[doxygen-spammer]

No code to reproduce needed, the source code confirms the behavior.

Normally options are before positional arguments in usage messages. However, vararg options should be after, because they can't be reliable used before a positional argument. Mutexes come into play, too, and are shown as soon as possible. Overall, output usages in the following order:

1. Mutexes that don't have positional arguments or vararg options.
2. Options that are not in any mutexes and are not vararg.
3. Positional arguments - on their own or as a part of a mutex.
4. Remaining mutexes.
5. Remaining options.

I can not follow this logic. Positional arguments can be vararg just like options. And you can not pass -- to vararg options anyways. Why not simply implement --?

I have difficulty reading the usage message if the positional arguments are not present after the options. The usage message only needs to be human readable, not reliably parsable. Therefore I expect it to show the usual order, with positional arguments last.