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

[François Pinard]

[Martin von Loewis]

> > 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.

> Ok, so if _ is bound, all is well.

Not necessarily.  `_' could be bound to a lot of things, not necessarily
a translating function.

> That brings us back to square one: Should we split the Python library
> into different textual domains?

I miss the logic of sliding over the snake, down to square one.  I perceive
the issues as rather orthogonal.  How are they connected?

> If yes, then how?  *If* we decide to split that, it would be very easy
> to extract doc strings of different modules into different catalogs.

Everything should be easy.  It is just not "convenient" to handle a
multiplicity of domains, without very serious reasons to do so.  Best is
to use one textual (or translation) domain per distribution of a system
or package.

> Even in that case, I guess there would be some code left that did not
> have its own textual domain.  So there would still be the need for some
> kind of "fallback" domain for the doc strings.

Why should we use separate domains for doc strings?

> The proposed operation of the help function would then be that:
> - if the module of the object (function, class, etc) can be
>   established, and has _ bound, then translate the doc string
>   in the catalog associated with _.

My feeling is that we should not rely on `_'.  The variable used to hold
the translating function should be left at the discretion of the user.

> - else, try to translate the doc string in the domain for Python
>   doc strings ("pydoc"?).

Why not just use the textual domain of a module, to translate the doc
strings it contains?  It may well happen that if the module comes with
the Python distribution, it will have "python" for its textual domain.
But it might come from anywhere, and we cannot predict the textual domain
of a randomly imported module.  However, all modules holding translated
strings should also get, right on initial import, a translating function
out of their textual domain, and the mechanics producing that translating
function might save a correspondence between the module and the textual
domain for that module (unless we find something more straightfoward).
It should be possible to communicate with the mechanics to get a copy
of the translating function for that module, and use that function to
translate doc strings held within that module.

> However, you also brought the point that the doc strings should use
> the same catalog as any other strings of the Python core,

I just checked the `To:' of your message to make sure, and indeed, you
are writing to me :-).  No, I'm pretty sure I never said that, or else,
if I did, I surely was extremely tired! :-) Simplicity asks that doc
strings share the textual domain of all other strings for the same module.
Is there a need to do otherwise?

                                                Keep happy!

P.S. - I slightly begin to fear that we will not have a full, clear
consensus by the 4th of September... :-)

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