[Doc-SIG] examples in reStructuredText spec

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> Call for opinions re:
>
>     http://structuredtext.sourceforge.net/spec/reStructuredText.txt
>
> - Are the "syntax diagrams" useful?

I don't think I use them particularly (and, of course, I find the first,
big, one to be rather confusing) - but I also am probably not the best
authority on the usefulness of such things (I've been accused in the
past of a, well, odd take on how language works).

> - Would "before & after" examples be useful (also/instead)?
>   Examples such as this would extend the spec's length quite
>   a bit (they could be put into another file, examples.txt).

Ah, well, as to that.

As yet, pydps has nothing in the way of selftest. By preference, I like
doctest as a means of testing stuff. But, aha, reST documents can
*embed* doctest blocks, just like docstrings can. So I was intending to
produce a "semi-literate error testing" ability to pydps.py, allowing it
to read in a .rtxt file and run doctest over it (either over the whole
thing, allowing doctest to detect the blocks of interest, or more likely
just over the doctest blocks themselves).

*Now*, if we have a reStructuredTextExamples.rtxt file (well, called
something shorter!) containing examples of text and result, I don't see
why we shouldn't leverage off the same sort of thing.

This would also allow us to discuss abstruse corners of the parser,
things to avoid or know about, whilst testing that they do indeed work
as "intended".

Howevever, if this is intended as examples for human use, it *might* be
better to have a directive defined that simply takes two parts (David,
you already know I'm bad at directive design, so please feel free to
read the *intent*, not the words!), or perhaps better two (paired)
directives - for instance::

    .. Example::
       This is some *emphasised* text.
    .. Gives::
       <paragraph>
          This is some
          <emphasis>
             emphasised
          text.

I think *this* could be a very valuable thing.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)