[Doc-SIG] Where to go from here

[Peter Funk]

Hi Edward,

>     - continue trying to come up with a concrete, formal spec

That would be very nice.

>     - drop the idea of maintaining compatibility with STNG, for

Yes.  *Some* ideas from ST are good.  Let's drop all the others.
Especially heading recognition in ST sucks.

> Dropping STNG compatibility will allow us to consider a number
> of options that I hadn't brought up before..  For example, I think
> we might want to replace '--' with '---' as the description list
> indicator, since people *do* use '--' in text (I know I do, and
> apparently Guido does too).  And I think we should drop 'o' as
> a bullet character.  etc..

I think, a description list can be dropped alltogether.  
At least for the time being a bullet list will be enough.  
enumerated lists: ...hmmm...  I think we can also live without 
them for a try.

I think we should aim for *very* minimalistic set of features
and people may than add other things lateron:
  * emphasizing of *single* words.
  * section headings (marked up through underlining with a line of
    hyphens or '=' and preceeded by a blank line). 
  * bullet item lists (which may be nested through indentation).
  * References to URLs, to Mailaddresses and to Python objects.
  * pre formatted paragraphs for code examples, tables and such:
    (every paragraph with mixed indentation or which starts with
    the patterns '>>>' or '+--' should be left allone.  Only properly 
    aligned normal text paragraphs should allowed for reformatting.

Than let's try to implement this minimal set and plug this into Ping's
pydoc and see what comes out, if running this on existing sources.
Of course this will never be able to replace an external documentation
written with a powerful markup system like LaTeX.  But it would
make Pings marvelous pydoc an even more worthwile tool for all this
useful version 0.x.y stuff written in Python, which comes without
documentation for the prime time.

Just my 2 pfennig, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)