On Thu, Nov 24, 2011 at 09:04, Keshav Kini <kes...@gm...> wrote:
> This is possibly a silly question, but I am reading the information
> about option lists in the reStructuredText specification document and
> wondering how to denote optional arguments of command line options in
> the usual way, i.e. "--warnings [<warninglevel>]" or
> "--warnings[=<warninglevel>]". Are we supposed to do "--warnings
> <[warninglevel]>"? In my experience the [] seem to usually come
> outside the <>, though I admit my experience is rather short. And this
> workaround (?) doesn't seem to be possible to apply to
> "--warnings[=<warninglevel>]". What's the correct thing to do here?
Docutils subscribes to the model used by the optparse module/package
in the Python standard library, whose documentation states:
Typically, a given option either takes an argument or it
doesn’t. Lots of people want an “optional option arguments”
feature, meaning that some options will take an argument if they
see it, and won’t if they don’t. This is somewhat controversial,
because it makes parsing ambiguous: if -a takes an optional
argument and -b is another option entirely, how do we interpret
-ab? Because of this ambiguity, optparse does not support this
feature.
-- http://docs.python.org/library/optparse.html#terminology
So Docutils syntax doesn't support this feature either. If the app
you're documenting does support "optional option arguments", the
method of documenting this is up to you. I'd just spell it out in the
description: "the argument to this option is optional".
--
David Goodger <http://python.net/~goodger>
|
