Mailman 3 December 2010 - docs

[issue9056] Adding additional level of bookmarks and section numbers in python pdf documents.
by pengyu.ut Feb. 18, 2020

Feb. 18, 2020

New submission from pengyu.ut <pengyu.ut(a)gmail.com>: Current pdf version of python documents don't have bookmarks for sussubsection. For example, there is no bookmark for the following section in python_2.6.5_reference.pdf. Also the bookmarks don't have section numbers in them. I suggest to include the section numbers. Could these features be added in future release of python document. 3.4.1 Basic customization ---------- assignee: docs@python components: Documentation messages: … [View More]

7 9

[issue9305] Don't use east/west of UTC in date/time documentation
by Alexander Belopolsky Feb. 14, 2020

Feb. 14, 2020

New submission from Alexander Belopolsky <belopolsky(a)users.sourceforge.net>: I am opening this to supersede issue7229. See discussion following msg107148. In many places offsets representing the difference between local time and UTC are described as minutes or seconds east or west of UTC. This is not correct because UTC is not a place and minutes and seconds don't measure distance in this context. Replacing UTC with the Prime Meridian will not fix that because some regions in the … [View More]

15 30

[issue9938] Documentation for argparse interactive use
by Jay T Sept. 12, 2019

Sept. 12, 2019

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method … [View More]

16 28

[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 … [View More]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> _______________________________________ [View Less]

8 17

[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 … [View More]

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, … [View More]

4 5

[issue9842] Document ... used in recursive repr of containers
by Éric Araujo Nov. 20, 2018

Nov. 20, 2018

New submission from Éric Araujo <merwok(a)netwok.org>: Built-in containers like dict use an ellipsis to represent a recursive item. In the symbols index, “...” only links to the secondary prompt; I think it should also link to a paragraph explaining the display of recursive containers. ---------- assignee: docs@python components: Documentation keywords: easy messages: 116256 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Document … [View More]

8 17

[issue8722] Documentation for __getattr__
by Paul Davis Feb. 5, 2018

Feb. 5, 2018

New submission from Paul Davis <paul.joseph.davis(a)gmail.com>: The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated. The attached script demonstrates the issue on OS X 10.6, Python 2.6.1 I'm thinking something along the lines of: If the attribute … [View More]

8 23

[issue10438] list an example for calling static methods from WITHIN classes
by Ian July 12, 2017

July 12, 2017

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP … [View More]

7 19

[issue10415] readline.insert_text documentation incomplete
by Justin Lebar Oct. 1, 2016

Oct. 1, 2016

New submission from Justin Lebar <justin.lebar(a)gmail.com>: The readline documentation currently says: > readline.insert_text(string) > Insert text into the command line. But as far as I can tell, readline.insert_text() does something only when called from startup_hook or pre_input_hook. Here's an example of someone using the module in a way that works: http://swapoff.org/svn/cly/tags/0.7/cly/interactive.py ---------- assignee: docs@python components: Documentation … [View More]

6 7