[Doc-SIG] Formalizing ST

[Peter Funk]

Hi,

Juergen Hermann points to MoinMoin/parser/wiki.py:
> I know this comes a little late, but have you guys considered wiki 
> markup and the python code that exists for it? Many things that 
> are/were fishy in ST are clearly defined in common wiki markups.

Last weekend I installed MoinMoin 0.8 here on a Server in our companies
intranet and played around with the markup.  Wiki markup contains
some clever ideas but IMO this is not really intuitive markup useful
for Python inline doc strings.

For example, Headlines in MoinMoin wiki markup are entered as:

= This is a very important H1 chapter headline =
== This is a slightly less important H2 section headline ==
=== This is a least of all important H3 subsection headline ===

This sucks IMO, since it emphazises the umimportant headings in favour
of the important ones, when viewing the text in an editor.

I would prefer to use indentation to markup different levels (borrow
this idea from ST) and use simple underlining for marking single
lines as headings:

This is a very important H1 chapter headline
--------------------------------------------

  This is a slightly less important H2 section headline
  -----------------------------------------------------

    This is a least of all important H3 subsection headline
    -------------------------------------------------------

IMO the ''' and '' for Mixing ''italics'' and '''bold''' are also
unreadable in Text editors.  They conflict with Pythons triple quotes
used in Docstrings BTW.  I like the *emphasize* proposed in this group
and by ST better.

However the url detection without requiring '<' and '>' delimters around
the http:// ... string is a nice feature of MoinMoin markup.  Ping has 
implemented something similar in pydoc already and this works just fine.
I have a similar feeling with the email address recognition (MoinMoin uses
the regular expression [-\w._+]+\@[\w.-]+ for that).

The use of `{{{' and `}}}' is also too heavy for the purpose.  pydoc
currently assumes that everything but URLs is preformatted literal
material and uses a fixed font to display everything.  I believe we
can loosen this a bit a consider every paragraph with mixed
indentation as literal material.  So only a paragraph with properly
indented lines will be recognized as text paragraph and possibly
reformatted.

About lists and numbered lists I'm still not sure what I would like.
I bullet item list (LaTeX itemize) seems to be enough for most cases.
A few days ago Guido gave a similar statement.

Regards, 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)