[Doc-SIG] field syntax (was re: lists & blank lines)
Edward D. Loper
edloper@gradient.cis.upenn.edu
Mon, 16 Apr 2001 14:45:35 EDT
> [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