[Doc-SIG] Docstring syntax discussion

[Berthold Höllmann]

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
only include the programs messages, but also the functions help
messages. This is a problem, that can't be addressed using the current
docstring syntax. 

An idea how to address this problem is shown in the foollowing script:

===File ~/miscpy/doctest.py=================================
class __docc__:
    def __init__(self):
        import locale
        loc = locale.setlocale(locale.LC_MESSAGES,'')
        if loc == "de_DE":
            self.text = """Dies ist ein TEST.

Benutzt globale Variablen.

%(__version__)s
%(__name__)s
""" % globals()
        elif loc == "fr_FR":
            self.text = """(I don't know any french.)

Uses global variables.

%(__version__)s

%(__name__)s
""" % globals()
        else:
            self.text = """This is a TEST.
Uses global variables.
Version: %(__version__)s
Name: %(__name__)s
""" % globals()
    def __str__(self):
        return self.text

__version__ = "0.0"
__name__ = "Berthold Höllmann"
__doc__ = __docc__()
============================================================

This could be used as following:

>>> import doctest
>>> print doctest.__doc__
Dies ist ein TEST.
Benutzt globale Variablen.
0.0
Berthold Höllmann
>>>

(I'm using german locale). This could allow to keep the documentation
in one's favourite markup language and just provide the appropriate
method for different output styles as '__str__' for text output,
'xml', 'sgml', 'TeX' or others.

Just my 2c.

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.