[Doc-SIG] non-ascii docstrings
edloper at gradient.cis.upenn.edu
Sat Mar 25 05:32:57 CET 2006
David Goodger wrote:
>> In particular, the question is whether I should assume that the
>> docstring is encoded with the encoding specified by the "-*- coding
>> -*-" directive at the top of the file.
> I think that although it's the only possible assumption, it's also
> potentially a wrong assumption. IOW, don't assume anything.
That was my inclination at first, but it appears that there are a large
number of python files out there that use non-ascii docstrings. Asking
the epydoc user (who is very often not the package author) to go through
and add a 'u' in front of every docstring (but *not* any other string --
that might break the program) seems unreasonable. And I have yet to see
a single python module where the -*- coding -*- directive is *not* the
right encoding for the docstrings.
> Another reason is simple: "In the face of ambiguity, refuse the
> temptation to guess."
Practicality beats purity. :)
> Yes, it's unreasonable. But such code is buggy IMO. It's also
> unreasonable to expect Epydoc to correctly interpret garbage input.
Small consolation to the user who's just trying to learn how to use a
package that they didn't write.
More information about the Doc-SIG