[issue10536] Enhancements to gettext docs

[Julien Palard]

Change by Julien Palard :


--
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[miss-islington]

miss-islington  added the comment:


New changeset 98b360e27b0be4646ed24c5a7ac07112ca020982 by Miss Islington (bot) 
in branch '3.7':
[3.7] bpo-10536: Enhancements to gettext docs (GH-10324) (GH-13224)
https://github.com/python/cpython/commit/98b360e27b0be4646ed24c5a7ac07112ca020982


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[miss-islington]

Change by miss-islington :


--
pull_requests: +13134
stage:  -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Serhiy Storchaka]

Change by Serhiy Storchaka :


--
stage: resolved -> 
status: closed -> open
versions: +Python 3.6, Python 3.7 -Python 3.4, Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

I think it is worth to enhance documentation for other versions too. See also 
my comments on GitHub.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Julien Palard]

Change by Julien Palard :


--
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Julien Palard]

Julien Palard  added the comment:


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


--
nosy: +mdk

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Stéphane Wirtel]

Change by Stéphane Wirtel :


--
versions: +Python 3.8

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Stéphane Wirtel]

Stéphane Wirtel  added the comment:

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 
Date:   Fri Nov 26 11:07:04 2010 +

Merged revisions 86791 via svnmerge from
svn+ssh://python...@svn.python.org/python/branches/py3k


  r86791 | stefan.krah | 2010-11-26 11:54:09 +0100 (Fri, 26 Nov 2010) | 1 
line

  Indentation cleanup.

--
Added file: https://bugs.python.org/file47904/bpo-10536.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Stéphane Wirtel]

Change by Stéphane Wirtel :


--
pull_requests: +9627

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Stéphane Wirtel]

Stéphane Wirtel  added the comment:

Serhyi and Eric, for which version of Python, only 2.7? or master, 3.6 & 3.7?

--
nosy: +matrixise

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Éric Araujo]

Éric Araujo  added the comment:

I will try to find some time in the next month!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

É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.

--
nosy: +serhiy.storchaka

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Terry J. Reedy]

Changes by Terry J. Reedy :


--
versions: +Python 3.4, Python 3.5 -Python 3.1, Python 3.2

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Andy Maier]

Andy Maier added the comment:

É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

--
nosy: +andymaier

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Roundup Robot]

Roundup Robot  added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Roundup Robot]

Roundup Robot  added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue10536] Enhancements to gettext docs

[Éric Araujo]

New submission from Éric Araujo :

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/042/ (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, d...@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 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com