[Doc-SIG] docstring grammar

[uche.ogbuji@fourthought.com]

> David Ascher wrote:
> >   Paragraphs are separated by one or more blank lines.
> 
> As you say later on, I think this does cause some over-use of whitespace...

Agreed.  Let's kill them.

> >   Characters between # signs and the end of the line are stripped by
> >   the docstring parser.
> 
> This is a Bad Thing - I have quite often needed to discuss things in doc
> strings which include use of the "#" character - not least if I'm parsing a
> little language that uses "#" as its comment character! So losing stuff thus
> would be difficult. Either (a) why do we need comments in doc strings, or
> (b) provide a way to escape the "#" character.

I forgot to mention this in my original reply.  I also think that this is a 
bad idea.  I don't think we need meta-comments for the doc-strings.  I don't 
like the idea even if we find a way to escape '#'.

> but the above gets oververbose. I suppose one could instead use a list
> syntax:
> 
> 	Contributors::
> 		- John Doe
> 		- Ronald Reagan
> 		- Francois Mitterand

Yes, and this goes with what David had in his proposal about bullets.

> since I don't see the ambiguity in allowing the omission of the vertical
> whitespace here, *if* one allows that some care would be needed with
> hyphenation! (i.e., one can't allow one's hyphens to start a line, which is
> awkward but probably not too bad). Another possibility might be to allow
> "Python list" syntax - I started off disliking this, but over the last few
> minutes it has grown on me:
> 
> 	Contributors::
> 		[ John Doe,
> 		  Ronald Reagan,
> 		  Francois Mitterand ]
> 
> (again, highjacking Python's syntax).

Again as long as we don't go having meta-compilation in the first version of 
the system.

> No, on thinking about it, I would vote for either:
> 
> 	1) use of white space as David proposes
> 	   (pro: utter simplicity,
> 	    con: doesn't quite look as nice as I'd like)
> 	2) allow Python list syntax
> 	   (pro: emphasises this is for short lists,
> 	    con: a bit odd)
> 	3) detect bullet characters at the "start of line"
> 	   (pro: still fairly simple,
> 	    con: one has to take care about, e.g., dashes in text)
> 	   Ah - I just realised that negative numbers at the start of a line
> 	   probably kill that one...

This one is also a bit ugly, but how about a hybrid:

List
	[
	* item 1
	* item 2
		[
		* sub-item 1
		* sub-item 2
		]
	* item 3
	]


-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org