[Doc-SIG] Doc-String Syntax

[Moshe Zadka]

Yet another one in my series of fuzzy outlines before the real spec, here
is my suggestion for doc-string syntax.

There are two kinds of tags: "short" tags and "long" tags.

Short tags have the syntax exemplified by [emph this is emphasized] (the
first word is the tag, and it continues to a nested bracket. 
Rational: this way tags can be written without touching the "shift" keys
on most keyboards. 

Long tags have the syntax exemplified by

arg name=s type=string::
	string to be parsed

The special long tag 'example' will not be intepreted by the program, 
so 

example::
	['this', 'is', 'a', 'list']

will work with no problems

the special long tag 'code' will work the same way, but will be translated
to inline code:

you can also write
code::
	(lambda x: [x])(5)
to return a list containing 5.

Paragraphs are seperated by new lines.

Another long tag, which is only valid in a classe's docstring, are
'instance-attrs' (unlike 'data', which would be class attributes).

All of the current semantic markup would be moved to short tags: 
[module urllib], [class URLOpener] and [function urlopen] are all
examples.

Spec, as promised, on Friday.
--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.