[docs] [issue10536] Enhancements to gettext docs
Éric Araujo
report at bugs.python.org
Fri Nov 26 01:22:06 CET 2010
New submission from Éric Araujo <merwok at netwok.org>:
A patch made for #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:
1) Markup: Use modern class/method directives combo (yay DRY). Mark up variable parts in :file: constructs (e.g. :file:`{domain}.mo` will cause the HTML output to use var to indicate replaceable text). Also change some ``gettext`` to :program:`gettext` for consistency.
2) Fix a typo in lngettext doc (originally included in patch by Franz Glasner for #2504).
3) I had started to remove information about private attributes (_info, _charset), advertising public getter methods instead. Then I read the description of NullTranslations and realized the information was needed for subclasses. I’ve reverted my removals, but I still think the private attributes should be listed in a specific section for people writing subclasses and not in the rest of the text. If you’re okay, I’ll make a second patch.
4) Assorted wording changes, missing periods and hyphens, and other very small touch-ups: Turned a broken bare link into a working link with nice text; used the with statement in an example (we all love the with statement!); used two spaces after periods throughout (hello Fred Drake).
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:
a) The current docs is currently POSIX-specific.
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.
----------
assignee: eric.araujo
components: Documentation
files: gettext-docs-1.diff
keywords: needs review, patch
messages: 122420
nosy: barry, docs at python, eric.araujo
priority: normal
severity: normal
stage: patch review
status: open
title: Enhancements to gettext docs
versions: Python 2.7, Python 3.1, Python 3.2
Added file: http://bugs.python.org/file19819/gettext-docs-1.diff
_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10536>
_______________________________________
More information about the docs
mailing list