[I18n-sig] Translating doc strings

[Guido van Rossum]

> How would users retrieve translations of the doc strings in the first
> place? I have proposed patch 101313
> 
> http://sourceforge.net/patch/?func=detailpatch&patch_id=101313&group_id=5470
> 
> which introduces a doc() function, so that users could write
> 
>     >>> doc("".split)
>     S.split([sep [,maxsplit]]) -> Liste von Strings
>     
>     Gib eine Liste der Worte im String S zurück, mit sep als Trennstring.
>     Wenn maxsplit angegeben ist, werden höchstens maxsplit Worte
>     abgetrennt.  Wenn sep nicht angegeben ist, gelten beliebige
>     Whitespace-Strings als Trenner.

I like the interface fine.  (Some might prefer to call it help()).

> This interface has a number of advantages:
> - you don't have to type print in the front to get line breaks display
>   properly
> - you don't have to type _ four times
> - it will transparently retrieve the translation if available

In an IDE, doc() could be replaced by something that pops up the docs
in a separate window.

> For this to work, all doc strings must be in a single textual
> domain. The implementation of the doc function will retrieve the
> __doc__ attribute of the argument and look for a translation.

Hmm...  This lumps together *all* documentation for *all* modules and
packages.  What about documentation for 3rd party packages?  How will
your doc() deal with unrelated objects that somehow have the same
(probably brief) docstring but for which the translation (depending on
context) should be different?

For functions, classes, methods and instances, the module name is
easily accessible, e.g.:

    >>> import rfc822
    >>> m = rfc822.Message(open("/dev/null"))
    >>> m.__class__.__name__
    'Message'
    >>> m.__class__.__module__
    'rfc822'
    >>> 

(For submodules of packages, __module__ gives the full package name.)

--Guido van Rossum (home page: http://www.pythonlabs.com/~guido/)