[Doc-SIG] A couple quick comments

[David Goodger]

on 2001-06-16 8:21 AM, Edward D. Loper (edloper@gradient.cis.upenn.edu)
wrote:
> 1. I think we should try to concentrate on building a markup
> language for docstrings.  I think that trying to create a
> general-purpose markup language, which is simple and easy and
> wonderful etc., is going to be too hard of a project.  We'll make
> more progress if we just try to concentrate on docstrings.

I personally am aiming for the general-purpose solution. I'd encourage you
or anyone to pursue a docstring-specific variant or alternative. Whatever
gets us there faster.

Perhaps I'll change my tune once I've completed a few more hundred lines of
code.

> 3. I think we should try to direct some energy at figuring out the
> details of the DPS.

Yes please! There are lots of "XXX" bits in PEP 258.

> If we're to accept David's proposed
> approach, then markup decisions should be made pretty far down
> the road: first we create the DPS, then we construct a number of
> actual markups, so we can play with them and try them out, and
> *then* we'll have more experience with which to make decisions
> about which markup features we want.

I prefer the Extreme Programming "continuous evolution" approach to design.
I don't know what the DPS needs until I tackle each side of each API. I do
welcome the advice of others with experience.

In other words, not having a complete PEP 258 won't hinder me from writing
an input parser. I personally won't be able to fill in some of the "XXX"
bits until I've got at least a partial solution in place.

Thanks.

-- 
David Goodger    dgoodger@bigfoot.com    Open-source projects:
 - Python Docstring Processing System: http://docstring.sf.net
 - reStructuredText: http://structuredtext.sf.net
 - The Go Tools Project: http://gotools.sf.net