classification
Title: Enhancements to gettext docs
Type: Stage:
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 2.7
process
Status: open Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: andymaier, barry, docs@python, eric.araujo, matrixise, mdk, python-dev, serhiy.storchaka
Priority: normal Keywords: needs review, patch

Created on 2010-11-26 00:22 by eric.araujo, last changed 2018-11-07 12:57 by serhiy.storchaka.

Files
File name Uploaded Description Edit
gettext-docs-1.diff eric.araujo, 2010-11-26 00:22 review
bpo-10536.diff matrixise, 2018-11-04 21:02
Pull Requests
URL Status Linked Edit
PR 10324 merged matrixise, 2018-11-04 20:59
Messages (10)
msg122420 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-26 00:22
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.
msg145218 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-10-09 06:59
New changeset e48e6e9bdef6 by Éric Araujo in branch '3.2':
Fix a typo and a broken link (part of #10536).
http://hg.python.org/cpython/rev/e48e6e9bdef6
msg145226 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-10-09 07:00
New changeset 1e48a2b484a3 by Éric Araujo in branch '2.7':
Fix a typo and a broken link (part of #10536).
http://hg.python.org/cpython/rev/1e48a2b484a3
msg222166 - (view) Author: Andy Maier (andymaier) * Date: 2014-07-03 09:51
Éric,
I have reviewed the patch, and have one minor comment on it (see review page). Otherwise, I think it is good to go into v3 (The version list for this issue also shows 2.7, and the 2.7 version of this file is quite different from the v3 tip version, so a backport is still needed).

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
msg328642 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-10-27 05:31
É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.
msg329251 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2018-11-04 19:47
I will try to find some time in the next month!
msg329252 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-11-04 19:54
Serhyi and Eric, for which version of Python, only 2.7? or master, 3.6 & 3.7?
msg329258 - (view) Author: Stéphane Wirtel (matrixise) * (Python triager) Date: 2018-11-04 21:02
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 5d744a8855bb4d411e5f32cfd365f0581e30ef48

Author: Stefan Krah <stefan@bytereef.org>
Date:   Fri Nov 26 11:07:04 2010 +0000

    Merged revisions 86791 via svnmerge from
    svn+ssh://pythondev@svn.python.org/python/branches/py3k
    
    ........
      r86791 | stefan.krah | 2010-11-26 11:54:09 +0100 (Fri, 26 Nov 2010) | 1 line
    
      Indentation cleanup.
msg329270 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-11-04 22:24
New changeset 55f3317e984cc35bd18ba0326ed98766a2750ffd by Julien Palard (Stéphane Wirtel) in branch 'master':
bpo-10536: Enhancements to gettext docs (GH-10324)
https://github.com/python/cpython/commit/55f3317e984cc35bd18ba0326ed98766a2750ffd
msg329279 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2018-11-05 06:11
I think it is worth to enhance documentation for other versions too. See also my comments on GitHub.
History
Date User Action Args
2018-11-07 12:57:40serhiy.storchakasetstatus: closed -> open
stage: resolved ->
versions: + Python 3.6, Python 3.7, - Python 3.4, Python 3.5
2018-11-05 06:11:42serhiy.storchakasetmessages: + msg329279
2018-11-04 22:27:10mdksetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-11-04 22:24:44mdksetnosy: + mdk
messages: + msg329270
2018-11-04 21:02:14matrixisesetversions: + Python 3.8
2018-11-04 21:02:02matrixisesetfiles: + bpo-10536.diff

messages: + msg329258
2018-11-04 20:59:02matrixisesetpull_requests: + pull_request9627
2018-11-04 19:54:20matrixisesetnosy: + matrixise
messages: + msg329252
2018-11-04 19:47:23eric.araujosetmessages: + msg329251
2018-10-27 05:31:15serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg328642
2014-08-30 04:21:17terry.reedysetversions: + Python 3.4, Python 3.5, - Python 3.1, Python 3.2
2014-07-03 09:51:54andymaiersetnosy: + andymaier
messages: + msg222166
2011-10-09 07:00:14python-devsetmessages: + msg145226
2011-10-09 06:59:48python-devsetnosy: + python-dev
messages: + msg145218
2010-11-26 00:22:03eric.araujocreate