[Doc-SIG] directives and fields

[Goodger, David]

[Edward D. Loper]
> > > The only other difference would be that, under my scheme, 
> the contents
> > > of a directive have to be properly formatted formatted text; where
> > > under your scheme it seems like they can be anything.
> > 
> > Not "anything", but directive-dependent. 
> 
> Yes.  But from the parser's point of view, it can be anything, because
> it doesn't know what extensions you'll be using.  Some later stage
> (after the parser) will put restrictions on it..

Not true. I'd like to clear up this concept of directives. It's completely
different from your proposed field concept, though not necessarily
incompatible.

Directives are a parser-control mechanism and can be used as an extension
mechanism. The reStructuredText directive proposal is similar to extension
modules in Python. Inevitably, someone will want to add a feature or some
behaviour to the reStructuredText parser which cannot be easily added
through character-construct syntax, because:

1. There's no natural or obvious candidate characters or constructs
   for syntax.
2. We've run out of characters to use as syntax.
3. The new feature or behaviour is too narrowly application- or 
   domain-dependent.
4. The new feature or behaviour cannot be added to the standard 
   due to lack of consensus (basically the same as case 3).

With one construct (regexp '^\.\. ', which comes from Setext) we have
comments, internal hyperlink targets, external URL hyperlinks, footnotes,
and directives. Directives were proposed as a mechanism for adding explicit
syntax that the parser can recognize, triggering parser extension code.

Say we add an 'SQL' extension to the parser, which performs a database query
and inserts the results. The extension would consist of an entry in the
directives dispatch table and support code to handle the query itself. This
code would be run by the parser as it is parsing, not afterward. The
semantics of the extension construct are up to the extension, but they could
easily include the processing of properly formatted text. For example, we
could add a set of admonition extensions::

    .. warning::

        Don't *ever* press the `Self-Destruct` button.
        If you do, you'll be sorry.

The 'warning' extension would tell the parser to process its text block as
usual, and simply wrap it in a new DOM object (hypothetically). The
*emphasis* and `literals` would be processed as usual.

Your field concept could be implemented using the '@' syntax as proposed, or
using the extension mechanism. If it's important enough, *and* the syntax is
natural enough, using the JavaDoc '@' syntax is no problem. The '@' syntax
doesn't strike me as natural though.

The cornerstone of the Setext/StructuredText-like approach is that the raw
text should be as readable as possible, even to the uninitiated. To quote
Jim Fulton's StructuredTextWiki,

    If you don't buy into this idea, you're probably wasting your time.

I think that '@' and especially 'C<>' stray from this ideal. I don't think
they belong in a Setext/StructuredText-like markup language. (Note: I'm not
saying you're wasting your time, Edward; far from it, these discussions have
been very helpful in many ways.)

/DG