[Doc-SIG] field syntax (was re: lists & blank lines)

[Edward D. Loper]

> [Edward Loper]
> >     @param x: ...
> 
> I'm not a big fan of the JavaDoc @ syntax, but I don't know of a better
> inline syntax for keyword-tagged values. (I did propose a [directive-based
> syntax]_; search for "keyword".)

As I've said before, I'm not terribly attatched to the JavaDoc syntax.
But it seems to me to make sense to handle field lists as follows:

    1. Each field begins with a "bullet", like "@returns" or "returns:"
       or ".. Keywords::" or whatever we agree on.  These should be
       recognizable using a regexp that doesn't depend on the actual
       words (i.e., *not* "@returns|@param|...", but "@\w+\b").
    2. Fields act just like list items.
    3. The field list must be the last thing in a docstring, and it
       must be separated by a blank line (unless it's the only thing
       in the docstring).  If you want, we could require that it be
       indented -- then, its syntax would be essentially identical to
       list syntax.

As I understand it, your "directive-based syntax" would mainly fit
this model.. Except that I require the contents of each directive
to be indented.  Note that you are not required to start a paragraph
on the line that a list bullet is on.. You can write list items 
like this if you want::
    1. 
       Paragraph one for list item (1).

       Paragraph two for list item (1).

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.

As a side note, you called this "inline syntax," but I think of "inline" 
as being things that occur within a paragraph.. This is "structural 
syntax" in my mind.

The reason I'd support JavaDoc rather than something like ".." is
because it's no less readable, and it's already a somewhat established
conventions (there are a fair number of javadoc-clones out there for
other languages).  On the other hand, we might not want people to
get confused, and think that our markup language is the same as
javadoc's...  :)  Also, "@\w+" occurs very rarely under natural 
circumstances (although perhaps the same can be said of ".. \w+::".

> I propose that until a clearly superior
> syntax is discovered/revealed, we leave these out of the discussion
> (unnecessary complication).

This is a feature that I'm very interested in making sure that the
markup language includes.  As such, I'd like to keep it on the table,
even if it's off to the side. :)  (I see this feature as being more 
important than the ability to use lists or colorizing..)

-Edward