New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Enhancements to gettext docs #54745
Comments
A patch made for bpo-2504 revealed a bug in gettext.rst, and I’ve found a number of other things to change in the file. This is the first patch of a series of two or three. Barry, as the original author of the module and doc, I’d like your opinion on points 3, a, and b particularly. Patch is also uploaded to Rietveld for greater convenience: http://codereview.appspot.com/3333042/ (upload.py rocks) Summary:
Final note: lines have not been rewrapped, for diff clarity. When I commit part or all of this patch, I’ll make another commit to rewrap. Not addressed: b) The docs take great care to explain that Unicode strings will be returned in different places, but this should not be so accented in 3.x docs IMO. I would just put a note somewhere near the top that all strings are str and remove the redundant sentences. Following that line of thought, I could group all l*gettext variants at the end of the list of methods, explaining that regular usage should just be happy with str objects and that l*gettext are available if people really want bytes. c) The file uses “built-in namespace” and “builtins namespace”, sometimes in neighbor paragraphs. :mod:`builtins` is not used, even in explanations of the install function/method. I don’t know if I should change that. d) Some capitalization patterns look strange to me: I have seen “I18N” and “L10N” in upper case nowhere else. Similarly, lower-case “id” looks stranger than “ID”. The latter is used for example in official GNU gettext docs. Am I going into foolish consistency territory or not? Thanks in advance for reviews and opinions. |
New changeset e48e6e9bdef6 by Éric Araujo in branch '3.2': |
New changeset 1e48a2b484a3 by Éric Araujo in branch '2.7': |
Éric, Barry's review I think is also still needed :-) My 2 cents on your questions to Barry: On 3): I like your proposal. On a): Can you be more specific on where it is POSIX specific, and what the issue is with that? On b): After understanding that your comment is about the v3 version, I agree with the comment in general. However, the set of functions changes between 2.7 and 3.x tip (for example, ugettext() from v2 is no longer in v3 because gettext() now returns Unicode strings), and if people try to understand what changed, I think it would be helpful to be more explicit, particularly because the v2 text is also explicit. So I would leave the "Unicode string" verbiage unchanged. But I don't have a strong opinion on this and can go either way. Andy |
Éric, do you mind to create a PR? But please avoid unnecessary formatting changes like adding a second space between sequences. While I prefer such style, these changes doesn't affect the result output and distract attention from significant changes. |
I will try to find some time in the next month! |
Serhyi and Eric, for which version of Python, only 2.7? or master, 3.6 & 3.7? |
Serhiy & Éric, I have ported the patch to a PR for master (3.8). I have removed the double spaces and some useless diffs. You will find my diff file I have used for the PR. the git revision was 5d744a8 Author: Stefan Krah <stefan@bytereef.org>
|
I think it is worth to enhance documentation for other versions too. See also my comments on GitHub. |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: