[Doc-SIG] What's important in a docstring markup language?

[Juergen Hermann]

On Thu, 29 Mar 2001 11:28:03 -0500, Guido van Rossum wrote:

>IMO, URLs don't need any special markup.  They can just be recognized
>in the text and automatically highlighted.  Lots of tools processing
>plain text do this (including the FAQ wizard, which has a trick or two
>to make this work reliably even when there's punctuation following the
>URL).

+1 (actually, you kicked me in the right direction to improve 
MoinMoin's code in that respect ;).

I think we should go the plain text route, with _conservative_ regexes 
(i.e. a sane implementation) and not too fancy markup (Tony's list). 

The main thing to consider in a first implementation is that we do not 
paint ourselves into a corner (like using too much markup characters 
that'll make it hard to keep the "plain readable text" idea).

If people want STNG in docstrings, plug in a parser for it. On the 
problem of deciding what parser to use, I propose to add some hint on a =

per module basis (mixing several docstring styles per module would be a =

silly, unsuported idea). Either by a magic variable in the module, or a =

magic comment, or some hint in the module's docstring.


Ciao, J=FCrgen

--
J=FCrgen Hermann, Developer (jhe@webde-ag.de)
WEB.DE AG, http://webde-ag.de/