Re: [Docutils-users] Option list not implemented according to documentation

[Pierre O. <os...@ce...>]

On 12/10/2021 13:23, Guenter Milde wrote:
> 
> Your example resembles example 7 in
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#option-lists
> 
>      --an-even-longer-option
>             The description can also start on the next line.
> 
> which also states the reasoning behind this behaviour.
> 

Hmm... I completely missed that. :)

> What is missing, is a caveat in the specification of definition lists: the
> term may not start with a hyphen. This is now added in the repository.
> 

That's a nice addition. Especially including a reference to how to 
escape around the issue.

However I would also suggest some adjustments to the parts that tripped 
me up as I re-read the option list definition multiple times:

> Option lists are two-column lists...
                    ^^^^^^^^^^
> There must be at least two spaces between the option(s)...
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^

> +----------------------------+-------------+
> | option [" " argument] "  " | description |
> +-------+--------------------+             |
                           ^^^^

Perhaps a footnote or similar emphasizing that this has an exception? 
And should the permitted trailing single space be explicitly documented?

> 
> Thank you for reporting,
> 

No problem. Trying to spare the next person the head ache. :)

Regards
-- 
Pierre Ossman           Software Development
Cendio AB               https://cendio.com
Teknikringen 8          https://twitter.com/ThinLinc
583 30 Linköping        https://facebook.com/ThinLinc
Phone: +46-13-214600

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?