Re: [Docutils-users] Problem with definition list

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

Greg Ward wrote:
> I'm trying to document a collection of methods like this:
...
> ``set_name(name : string)``
>   use this to change the widget name supplied to the constructor.
...
> but Docutils doesn't seem to like my notation for argument types:
> 
> Reporter: WARNING (2) Inline literal start-string without end-string at line
> 10.
> Reporter: WARNING (2) Inline literal start-string without end-string at line
> 15.

It looks like your Docutils installation is out of date.  Reporter output
doesn't look like that any more.  Get the latest snapshot here:
http://docutils.sf.net/docutils-snapshot.tgz

> If I remove the whitespace around the colons, it doesn't complain.
> 
> Oh... bugger... I seem to have run afoul of the "classifier" feature of
> definition lists.

Yes, it seems so.  The " : " structural markup (delimiting the term line
into "term" and "classifier" elements) is picked up before the "``" inline
markup.  That's a tricky case, one I hadn't anticipated.  I think this is
the only case of structural markup in the middle of text; in every other
case, the markup is either at the beginning or at the end of a text block.

> (Have I mentioned how nice it is that reST has a semi-formal spec?)

Glad you like it.  It certainly helps to be able to occasionally say "RTFM!"
and have a "fine manual" to refer to.

> This would be only slightly annoying if it weren't
> for the fact that that feature appears to have been at least vaguely
> inspired by the type syntax that I invented for Grouch.  That raises it
> from "slightly annoying" to "richly ironic", I think.

More than vaguely.  Grouch is mentioned in the spec.  Ironic indeed! :-)

> So is there a way to work around that feature?  I tried backslashing the
> colons, and they just came out backslashed in the HTML output.

Backslash-escaping the colons does indeed prevent the term/classifier split,
but then the inline literals take over and the backslashes stay in.
Dilemma.

Perhaps the entire term line should be checked for inline markup first, and
only then split on a top-level " : "?  The terms in the cases given won't be
split because the " : " would already be inside an inline literal element,
and thus not at the top level.  This will have to be thought through to see
if there are any hidden gotchas.

In the interim, how about this?

    set_name(name \: string)
        use this to change the widget...

You don't get the inline literal effect, but it's better than nothing.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/