[New-bugs-announce] [issue10536] Enhancements to gettext docs

[Éric Araujo]

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