[Doc-SIG] Where to go from here

[Guido van Rossum]

> > 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.  

Yes!  They are darn ugly in HTML anyway.

> At least for the time being a bullet list will be enough.  

Agreed.

> enumerated lists: ...hmmm...  I think we can also live without 
> them for a try.

In any case, ST++ shouldn't go and rewrite the item numbers.  The
requirement that the input is also readable without processing means
that the author ought to put the proper numbers in there by hand
anyway, so all ST++ needs to do is recognize them and give the
paragraph the proper indent/spacing.

> 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.

Please do look at the conventions in MoinMoin an another example!

> 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

Surely you mean 0.02 Euro. :-)

--Guido van Rossum (home page: http://www.python.org/~guido/)