Mailman 3 June 2010 - docs

Python documentation : some points requiring attention
by Jacques June 7, 2010

June 7, 2010

Hi Georg, Here is a second list of issues found while navigating through the rich Python 3.1.1 official documentation. Hope this would be useful. With regards. Jacques DUCASSE FRANCE NB : in your reply to my previous email, you say you couldn't find the "default ascii encoding" in the HowTo. Here I join a screenshot of this. Georg Brandl a écrit : > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > Am 21.03.2010 00:02, schrieb Jacques: >> Hello, >> >> First, I want to thank you for the useful and clear documentation of Python. >> >> Beeing a fanatic reader of it, sometimes I encounter some mistake (or it >> seems to me it is such). If this could bring some help, you will find in >> the attached file a list of points requiring attention. >> >> All the comments concern the official standard documentation of Python >> 3.1.1. > > Hi Jacques, > > thanks for the thorough list of issues! I'm going to copy them inline here > and add answers. > [......] > >> How-to Unicode >> 1.3 Encodings >> ?For example, Python?s default encoding is the ?ascii? encoding? >> This was true in the past but, now, it defaults to UTF-8. > > I can't seem to find that sentence in the 3.1 HOWTO text. > > Thanks! > Georg

1 0

[issue8910] Write a text file explaining why Lib/test/data exists
by Éric Araujo June 7, 2010

June 7, 2010

Éric Araujo <merwok(a)netwok.org> added the comment: Attaching a proposal. I think the component is a grey area between tests and documentation, so I’d be for including this file in all four branches. ---------- keywords: +needs review, patch nosy: +docs@python, merwok Added file: http://bugs.python.org/file17581/README _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8910> _______________________________________

1 0

[issue8875] XML-RPC improvement is described twice.
by INADA Naoki June 7, 2010

June 7, 2010

New submission from INADA Naoki <songofacandy(a)gmail.com>: http://docs.python.org/dev/whatsnew/2.7.html#new-and-improved-modules "The XML-RPC client and server, provided by..." appears twice. ---------- assignee: docs@python components: Documentation messages: 106875 nosy: docs@python, naoki priority: normal severity: normal status: open title: XML-RPC improvement is described twice. versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8875> _______________________________________

3 2

[issue8519] doc: termios and ioctl reference links
by Brian Curtin June 7, 2010

June 7, 2010

Changes by Brian Curtin <curtin(a)acm.org>: ---------- title: [patch] doc: termios and ioctl reference links -> doc: termios and ioctl reference links _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8519> _______________________________________

1 0

[issue8909] mention bitmap size for bdist_wininst
by Tarek Ziadé June 6, 2010

June 6, 2010

New submission from Tarek Ziadé <ziade.tarek(a)gmail.com>: done in r81788, r81789, r81790, r81791 thanks! ---------- resolution: -> fixed stage: -> committed/rejected status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8909> _______________________________________

1 0

Sphinx indexing
by anatoly techtonik June 6, 2010

June 6, 2010

I've stumbled upon definition of `open` function in http://docs.python.org/genindex-O.html and I wonder - why none of the following entries leads to definition of `open`? open built-in function, [1] I see that linked paragraphs have explicit `builtin: open` markup, but can't find their intended usage in Sphinx documentation. To me the index should look like: open (built-in function) Files Reading and Writing Files or open (built-in function) definition [1] Files [2] Reading and Writing Files or open (built-in function) definition references [1], [2] Another issue that paragraph anchors generate links that lead to paragraph contents while in most cases it would be more helpful to read paragraph title, which is scrolled offscreen. -- anatoly t.

1 0

[issue8890] Modules have dangerous examples in documentation
by Henri Salo June 5, 2010

June 5, 2010

Henri Salo <henri(a)nerv.fi> added the comment: No it does not. http://www.owasp.org/index.php/Insecure_Temporary_File ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8890> _______________________________________

1 0

[issue8909] mention bitmap size for bdist_wininst
by anatoly techtonik June 5, 2010

June 5, 2010

Changes by anatoly techtonik <techtonik(a)gmail.com>: ---------- nosy: +docs@python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8909> _______________________________________

1 0

[issue7229] Manual entry for time.daylight can be misleading
by anatoly techtonik June 5, 2010

June 5, 2010

anatoly techtonik <techtonik(a)gmail.com> added the comment: It is too hard to track this issue without quotes from manual. Let's bring context into discussion: http://docs.python.org/library/time.html#time.altzone UTC offset of the local DST timezone if one is defined. Only use this if daylight is nonzero. http://docs.python.org/library/time.html#time.daylight Nonzero if a DST timezone is defined. http://docs.python.org/library/time.html#time.timezone UTC offset of the local (non-DST) timezone So, to answer a question "What is the current UTC offset?" you need to: if time.daylight: if time.altzone: # using only if defined use time.altzone else: use time.timezone else: use time.timezone 1. Is that really works like described above? 2. Should we at least group these timezone variables? As for offtopic UTC vs GMT - I doubt there is a way to clearly express that the offset sign of the returned values is negated in comparison with real "UTC offsets" without resorting to some king of alternative east/west scale. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

2 2

[issue7229] Manual entry for time.daylight can be misleading
by Alexander Belopolsky June 5, 2010

June 5, 2010

Alexander Belopolsky <belopolsky(a)users.sourceforge.net> added the comment: It may be a bit off-topic for this issue, but I don't like that the python manual uses UTC as if it was a geographical location. UTC is a time scale. You cannot be to the east or to the west of UTC just as you cannot be to the north of the Gregorian calendar. Even if we replace UTC with Prime or Greenwich Meridian, the manual would still be incorrect because some regions in the western hemisphere use positive offsets from UTC. For example, Madrid is at 3° 42' West, but uses Central European Time which is UTC+1. Since there are no plans to include any kind of geographical database in the standard library, I think the manual should avoid use of geographical terms. What I need to know from the manual is how to get local time from utc and daylight savings time from the standard time. >From the top of my head, I know that localtime = utctime + utcoffset, but I am not sure whether dsttime = stdtime + dst or dsttime = stdtime - dst and the manual, reworded or not, does not immediately help me. As for the original issue, do we really need time.daylight at all? ISTM that in timezones without DST, time.altzone = time.timezone, so the software that unconditionally accounts for DST will still work correctly and software that wants to optimize for no DST case can simply chsck time.altzone == time.timezone. $ TZ=UTC ./python.exe -c "import time; print(time.daylight, time.tzname, (time.timezone, time.altzone))" 0 ('UTC', 'UTC') (0, 0) In other words, time.daylight is strictly redundant. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7229> _______________________________________

1 0