[Doc-SIG] Comments on the reST specification - comments

[David Goodger]

on 2001-08-07 12:09 AM, Garth T Kidd (garth@deadlybloodyserious.com) wrote:
> Status quo requires less code change. :)

That never stopped me before!

> In the IDG Books' "reStructuredText Markup for Dummies",

I'm gonna be rich! Unless somebody gets to the Dummies people before me.
Gotta stop coding, and start writing the damn book...

> I see a potential problem with directive arguments. Maybe it's just the
> overload on the operastor, but to me whatever comes after the ``::`` is
> a literal argument to the directive. If the directive has multiple
> paragraphs, my mental model says they're all parsed as a literal block
> (sans the directive marker).

How the directive block is parsed is entirely up to the directive.

> * Remove the literal block node from the directive.

I don't follow you. Explain please?

> .... which places a natural limit on just how directive arguments can get
> if the author is unfortunate enough to have a crummy text editor.

If the directive is expecting more than a word or two of "arguments", it
could easily be specified to accept arguments on the successive lines (and
even use keyword arguments)::

    .. complex-directive::
       arg1=val1
       arg2=val2

       Here's the directive block data...

Don't forget, no directives have yet been coded, so the interface has not
been established. What you see now is the generic, "unrecognized" directive
output, which uses a literal block because it's whitespace-preserving and
because the parser doesn't know what else to do. Your directive can parse
its block however it likes. See my reply (to you) containing a "caution"
directive for another possibility.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net