#59 Colon ":" breaks reST option list

[Ales Kvapil]

Takeshi Komiya told me, that Docutils are responsible for converting reST files to HTML for Sphinx. We have got a problem with this, becuase command line parameters in our Python framework contain a colon ":". But our built Sphinx documentation can not interpret/format these into an reST option list. Basically we have:

-parametera Description of parameter A
-parameter:b Description of parameter B

The first one in correctly interpreted and built into an option list by Docutils. But the second one makes the option list broken and is interpreted by Docutils/Sphinx as a plain text. We know this is not a standard Unix/Win notation (also we are multiplatform, neither Unix nor Win; or better either Unix or Win), but this is super-useful for the purpose of our Python framework. Is there a way to make this special notation be interpreted as an option list?

Takeshi Komiya also told me Docutils can be somehow extended by some sort of extension. How could we resolve our issue?

[engelbert gruber]

first "-parametera description ..." does not work really

if you check the html closely you will see it is interpretetd as "-p arametera " in the way many tools allow "-o outputfilename" to be specified as "-ooutputfilename".

longoptions start with two hyphens "--parametera "

for the colon the fix seams easy but i like to have it approved by günter or david
as colon is an important sign in reST

and maybe a different option syntax parser allowing for "-long" would be better anyway

[Günter Milde]

Ticket moved from /p/docutils/bugs/344/

[Günter Milde]

Moving to feature requests: the parser behaves as advertised:
The syntax for short and long POSIX options is based on the syntax supported by Python's getopt.py module, which implements an option parser similar to the GNU libc getopt_long() function but with some restrictions. There are many variant option systems, and reStructuredText option lists do not support all of them.

-- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

Especially, the colon has a special meaning in getopt and cannot be used inside option names.

Whether we want to support a more wide selection of syntax variants should be discussed on the list.

[Ales Kvapil]

Notice: On the reST mailing lists it was recommended to our project to change the format of command line/terminal parameters to POSIX compliant. But our project (and all its users) uses -keyword and -key:word format since 2002, therefore this would be hard breaking change, which would require to change the version number from 3.x.y to 4.x.y, and break probably thousands of cron jobs around the world calling our library (not speaking about what our users are used to)

[Günter Milde]

How could we resolve our issue?
You may want to try with a custom rst parser that modifies the regexp recognition patterns for
option lists. This should inherit from the standard rst parser and be passed to the publisher instead of it (should be doable in Sphinx configuration or as Sphinx extension but I don't know the details).

For the regular expressions, see the dictionaries "pats" and "patterns" in the docutils.parsers.rst.states.Body class.

[Günter Milde]

The suggestion did not find sufficient support amongst Docutils developers.
Closing this ticket. Thank you for your feedback and sorry we could not help.