#84 Recognize syntax for optional and repeating arguments in option lists

[Alkis Georgopoulos]

The option-lists specs state that "the syntax for short and long POSIX options is based on the syntax supported by Python's getopt.py module".

This doesn't allow for optional or repeating arguments. A couple of examples from the man man page:

--warnings[=warnings]  This is an argument with an optional value

-m system[,...]  This is an argument with a repeating value

My feature request is for the square brackets [] to become allowed in the option lists spec and implementation in a similar way as the less than / great than symbols <>.

This will allow us to use docutils even when some binaries in our project do need optional or repeating arguments.
(I'm currently evaluating if it would be appropriate to migrate the https://ltsp.org and https://epoptes.org documentation and man pages, from markdown to restructuredtext)

[Günter Milde]

Thank you for the suggestion. I agree that this would be a helpful addition.
A suggestion/patch how to document this feature in the reStructuredText specification is welcome.

We have to think about backwards incompatibility, as currently the source text

--warnings[=warnings]
       Enable warnings from groff.  This may be  used  to  perform
       sanity checks on the source text of manual pages.

is recognised as a definition list item. (The the last example in
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists) was added after a user reported tripping over this ambiguity.)
This means we would need an andvance warning and proper documentation, if the request should be implemented.

[Alkis Georgopoulos]

Thank you very much Günter! Unfortunately in the meantime and after evaluating both restructuredtext/sphinx and markdown/mkdocs, I decided that mkdocs is a better match for my projects and I already started migrating my sites to mkdocs-material (e.g. https://ltsp.org).
So feel free to close this issue, as I don't think I'll be able to allocate enough free time to propose a patch for it. Of course if anyone needs it, they're most welcome to offer one!

[Günter Milde]

Updating the option-list recognition rules to match the output of Pythons standard "argparse" module should be considered (but is not the most urgent problem right now).