Re: [Docutils-users] many-character option list

[David G. <go...@py...>]

On Tue, Feb 27, 2018 at 11:53 AM, Gary Mamon <ga...@ia...> wrote:
> * How can I make a many-character non-POSIX (i.e. single dash signs) option
> list, i.e.
>
> -data file # data filename
>
> OR
>
> -data file -> data filename

You cannot, per the reStructuredText Markup Specification:
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

The 4 types of option markup allowed are:

* Short POSIX
* Long POSIX
* Old GNU-style "plus"
* DOS/VMS "slash"

> where the first data is highlighted as a literal, the “file” is highlighted
> as emphasis (italics), and the tabulation between “file” and “#” or “->” is
> a real tab so that subsequent lines are vertically aligned?

Note: tabs are not used. Tables or other markup are used.

> Using standard option lists doesn’t work:
> 1) multiple-character options have their first letter in literal and the
> next ones in emphasis, which is weird.

Not weird once you understand what's going on. A line like:

    -option    description

is simply interpreted as the short POSIX option "-o" followed by the
argument "ption" and a description.

Trying to mix single-dash long options with short options is ambiguous
at best, and not supported by reStructuredText.

> 2) some lines with arguments fail to process correctly.

See the spec for correct syntax. Non-POSIX styles are not supported though.

> * As an alternative, I could enclose all lines in a literal block. But then,
> how can I place emphasis on some of the words within the literal block?

You could use a parsed literal block:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

> * A 3rd possibility is do the mark-up word by word. But then, how can I
> insert tabs to enforce vertical alignment?

Again, there are no tabs. You could use a table.

David Goodger
<http://python.net/~goodger>