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

[Goodger, David]

[Edward Loper]
>     3. The field list must be the last thing in a docstring

Why? What about PEPs?

> I require the contents of each directive
> to be indented.

Why? And what do you mean by "directive" here? (Note that my proposed
directive syntax was for arbitrary language extension. The keyword-tagged
values directive was just an example.)

> 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).

I'm confused. So what? And why would we want this?
 
> 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. In other words, for the keywords
example, given the directive::

    .. keywords::

The next lines are expected to be of the form "keyword: value". (Beyond
that, I didn't specify; it was only an example of what could be done.)

> 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.

Sorry, my bad. I meant character-based syntax (in this case "@"-based), as
opposed to explicit directive-based.

> This is a feature that I'm very interested in making sure that the
> markup language includes.

Keyword-tagged values have been discussed in the past on Doc-SIG. If they're
that important to you, I'd suggest you go through the archives, list up all
proposed alternatives, analyze & summarize. Otherwise, history repeats.

> I see this feature as being more 
> important than the ability to use lists or colorizing..)

I don't. Everyone has their own agenda, their own priorities. Beware that
yours don't become a stumbling block for others' acceptance. :)

One problem with getting a Setext/StructuredText derivative to satisfy
everyone's needs is that the more characters we use as markup, the more
complex it becomes. Another is that the available characters are limited.
Are keyword-tagged values important enough to warrant the use of another
character for their syntax? Edward's answer is obviously "yes". Mine was
"no" (also because "@" isn't obvious/intuitive), and so I proposed a general
explicit solution to future extension.

/DG