[Doc-SIG] Docstring syntax discussion

[Berthold Höllmann]

Jack Jansen <jack@oratrix.nl> writes:

> > Hello all,
> > 
> > I think the current docstring syntax discussion fails to address a
> > very important issue. Not all users of Python are native english
> > speakers and writers (I'm of course one of these). I think localizing
> > python modules and programs is an important issue. Localizing does not
...
> """
> Alternative:
> 	Language: en
> 	Description:
> 		This function does nothing.
> Alternative:
> 	Language: nl
> 	Description:
> 		Deze functie doet niets.
> """
> 
> It is probably open to discussion whether the default for Language should be 
> unspecified/unknown (which is politically correct) or english (which is 
> probably a lot more practical, since I don't think we can teach these 
> americans to add the Language tag all the time:-).

My "proposal" has the advantage that even the on line documentation
remains usable for the user. Also is allows everyone to use her/his
own syntax for the documentation strings. I would like a syntax that
allows things like complicated formulas in my documentation. And I now
that I get problems when I should edit at leas two different versions
of my Documentation. I would prefer to keep it in one place, providing
on line help as well as nice printed books. My example was of course a
quick hack, cause I only frequently found time to think about this.
Also I have no idea how to add this functionality to functions instead
of classes.

Cheers

Berthold
-- 
bhoel@starship.python.net / http://starship.python.net/crew/bhoel/
        It is unlawful to use this email address for unsolicited ads
        (USC Title 47 Sec.227). I will assess a US$500 charge for
        reviewing and deleting each unsolicited ad.