[Doc-SIG] examples in reStructuredText spec

[David Goodger]

Call for opinions re:

    http://structuredtext.sourceforge.net/spec/reStructuredText.txt

- Are the "syntax diagrams" useful?

- Would "before & after" examples be useful (also/instead)? For example::

      Example input::

          A Title
          =======
          Paragraph.

      Parsed::

          <document>
              <section name="a title">
                  A Title
              <paragraph>
                  Paragraph.

  Examples such as this would extend the spec's length quite a bit (they
  could be put into another file, examples.txt). However, I think they
  would help to document the DPS document tree structure. I would include
  a section explaining the indented pseudo-XML notation used to represent
  the parsed document tree.

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