Mailman 3 June 2012 - docs

[issue10536] Enhancements to gettext docs
by Éric Araujo May 9, 2019

May 9, 2019

New submission from Éric Araujo <merwok(a)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@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(a)bugs.python.org> <http://bugs.python.org/issue10536> _______________________________________

8 17

[issue12188] PEP 7, C style: add ++ policy and explanation
by Terry J. Reedy May 9, 2019

May 9, 2019

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: In response to a discussion of a patch removing 'useless' post-increments, (which issue has apparently come up before) Guido posted "> Sorry to butt in here, but I agree with Eric that it was better > before. There is a common idiom, *pointer++ =<something>, and > whenever you see that you know that you are appending something to an > output buffer. Perhaps the most important idea here is that this > maintains the *invariant* "pointer points just after the last thing in > the buffer". Always maintaining the invariant is better than trying to > micro-optimize things so as to avoid updating dead values. The > compiler is better at that." A condensed version of the above added to PEP 7 would help new developers see the usage as local idiom rather than style bug. ---------- assignee: docs@python components: Documentation messages: 136991 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: PEP 7, C style: add ++ policy and explanation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12188> _______________________________________

7 11

[issue11001] Various obvious errors in cookies documentation
by Luke Plant May 7, 2019

May 7, 2019

New submission from Luke Plant <L.Plant.98(a)cantab.net>: Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached. The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake. Thanks. ---------- assignee: docs@python components: Documentation files: http_cookies_doc_corrections.diff keywords: patch messages: 126962 nosy: docs@python, spookylukey priority: normal severity: normal status: open title: Various obvious errors in cookies documentation versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11001> _______________________________________

8 12

[issue10789] Lock.acquire documentation is misleading
by Jyrki Pulliainen April 26, 2019

April 26, 2019

New submission from Jyrki Pulliainen <jyrki(a)dywypi.org>: In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments. The signature in documentation should be formatted as in thread.lock.acquire. ---------- assignee: docs@python components: Documentation messages: 124861 nosy: Jyrki.Pulliainen, docs@python priority: normal severity: normal status: open title: Lock.acquire documentation is misleading versions: Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10789> _______________________________________

6 9

[issue10048] urllib.request documentation confusing
by Antoine Pitrou April 26, 2019

April 26, 2019

New submission from Antoine Pitrou <pitrou(a)free.fr>: The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use. Ideally, the use of the old primitives should also be discouraged. ---------- assignee: docs@python components: Documentation messages: 118179 nosy: docs@python, orsenthil, pitrou priority: normal severity: normal stage: needs patch status: open title: urllib.request documentation confusing versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10048> _______________________________________

4 5

[issue12957] mmap.resize changes memory address of mmap'd region
by Michael Schurter April 26, 2019

April 26, 2019

New submission from Michael Schurter <m(a)schmichael.com>: Since mmap.resize uses MREMAP_MAYMOVE on Linux, it would be nice to warn users that pointers into their memory mapped regions will be invalid after resizes. Linux's manpage offers the following explanation: "If the mapping is relocated, then absolute pointers into the old mapping location become invalid (offsets relative to the starting address of the mapping should be employed)." Since the only way I know of to use pointers into mmaps from pure Python is to use ctypes.<type>.from_buffer(<mmap>), perhaps clarification would be better in the ctypes docs. ---------- assignee: docs@python components: Documentation files: killctypes.py messages: 143845 nosy: docs@python, schmichael priority: normal severity: normal status: open title: mmap.resize changes memory address of mmap'd region type: feature request versions: Python 2.7 Added file: http://bugs.python.org/file23126/killctypes.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12957> _______________________________________

4 4

[issue14945] Setup & Usage documentation for selected stdlib modules
by Nick Coghlan April 26, 2019

April 26, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: Some stdlib modules have officially documented and supported behaviour when executed via -m. These should be referenced from the Setup & Usage documentation at http://docs.python.org/dev/using/index.html Current candidates: python -m unittest python -m timeit ---------- assignee: docs@python components: Documentation messages: 161832 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for selected stdlib modules type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14945> _______________________________________

6 11

[issue13282] the table of contents in epub file is too long
by wrobell April 11, 2019

April 11, 2019

New submission from wrobell <wrobell(a)pld-linux.org>: the table of contents in python documentation epub file is very very long. it takes several long minutes to jump from first page to a part containing language reference toc. imho it would be great if first page of epub file contained pointers to tutorial, lang ref, mod ref without detailed table of contents as it is at docs.python.org. ---------- assignee: docs@python components: Documentation messages: 146548 nosy: docs@python, wrobell priority: normal severity: normal status: open title: the table of contents in epub file is too long versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13282> _______________________________________

4 4

[issue13850] Summary tables for argparse add_argument options
by Nick Coghlan March 24, 2019

March 24, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements: 1. Summary table with a one line description of each parameter 2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const') 3. Summary table with a one line description of each alternative for the "nargs" parameter ---------- assignee: docs@python components: Documentation messages: 151880 nosy: bethard, docs@python, ncoghlan priority: normal severity: normal status: open title: Summary tables for argparse add_argument options versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13850> _______________________________________

12 27

[issue14944] Setup & Usage documentation for pydoc
by Nick Coghlan March 20, 2019

March 20, 2019

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: pydoc is installed as a script by Python. It should be documented under http://docs.python.org/dev/using/index.html. ---------- assignee: docs@python components: Documentation messages: 161831 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Setup & Usage documentation for pydoc type: enhancement versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14944> _______________________________________

7 13