[I18n-sig] Re: Patch 101320: doc strings

[François Pinard]

> [Barry A. Warsaw]
> > So maybe for /docstrings/ there should be one domain, and then each module
> > can have it's own domain for its own additional translatable strings?

> [François Pinard]
> > I do not understand the advantage of doing this.  Of course, if we do
> > not need the translation of docstrings, these should not be collected
> > for translation.  But if they get collected, there is no reason to have
> > a separate domain for them.  It is just natural that they be part of the
> > domain for the collection of modules they are part of.

[Martin von Loewis]

> How would you access the doc strings?  Today, I do

> >>> import httplib
> >>> print httplib.HTTP.__doc__
> This class manages a connection to an HTTP server.

> Now, how do I get to the translation of this message?

I do not imagine all the details, but I think the spirit of the thing is that
at "import httplib" time, some function (or class instantiator) was called
at the top level of the httplib module, to produce a translating function,
which the httplib module soon assigned to the `_' variable, or something
else if the programmer did not like `_'.  The httplib module transmitted
its translation domain to the mechanism generating the translating function.

If it was systematic that `_' was assigned to, we could try to retrieve
the function stored in the `_' global variable of `httplib', and then use
it to translate any docstring from httplib.  However, it would be nicer
if the constraint of using `_' for the translating function did not exist,
and if it was rather completely left at the discretion of the programmer.
If we use `_' systematically in documentation examples we produce, it is
likely to become the popular choice, but let's avoid mandating it.

If we are not forcing `_', the doc() or help() function able to retrieve the
translated docstring would have to be a bit more clever.  I'm not familiar
enough with the Python system variables to exactly know how to do this, but
I have the feeling that it would not be hard to organise without having to
make the API any less simple than it already is.  The mechanism producing
the translating function and the help() function (let me confess I have a
preference for `help' over `doc' :-) could be designed so they collaborate,
if a straightforward implementation of help() appears difficult.

-- 
François Pinard   http://www.iro.umontreal.ca/~pinard