Mailman 3 November 2010 - docs

[issue10389] Document rules for use of case in section titles
by Éric Araujo Nov. 11, 2010

Nov. 11, 2010

Éric Araujo <merwok(a)netwok.org> added the comment: +1 about the patch, if you add an example: “sentence case” may not be obvious for everyone. If it’s “modulename — Module description”, I agree. Also, s/white space/whitespace/. ---------- nosy: +docs@python, eric.araujo _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10389> _______________________________________

1 0

Use of title-case in section titles
by Alexander Belopolsky Nov. 11, 2010

Nov. 11, 2010

Apple style guide recommends that section titles be written in title-case (a set of confusing rules where most words are capitalized). However, with few exceptions, per module sections have titles with only the first word in capitals: 6. String Services 6.1. string — Common string operations 6.2. re — Regular expression operations .. 6.7. unicodedata — Unicode Database 6.8. stringprep — Internet String Preparation Third level subsections are mostly capitalizing the first word as well. I personally prefer to use sentence case in section titles. Note that "string — Common string operations" is neither sentence nor title case: it title-case it would be "string — Common String Operations" and in sentence-case, it would be ""string — common string operations" because the first word of the sentence is "string", not "common". Since most of the existing documentation does not follow Apple style guide in this respect, I think we should document an appropriate recommendation in Python documentation style guide and use it more consistently.

2 1

Compiler package deprecated/removed
by Tom Adams Nov. 10, 2010

Nov. 10, 2010

Sorry, I'm being very rude by sending messages to a mailing list but not subscribing. But in lieu of a bug tracker this will have to do. Usually the docs are pretty good, and point you in the right direction when a package gets deprecated, but this is an exception: http://docs.python.org/library/compiler.html "Deprecated since version 2.6: The compiler package has been removed in Python 3.0." I was expecting the message to continue on to say what package(s) replace the functionality of the compiler package. Thankfully Google/StackOverflow had the answer: http://stackoverflow.com/questions/909092/why-is-the-compiler-package-disco… Thanks, Tom

1 0

Single quotes are rendered as U2019 in PDF
by Alexander Belopolsky Nov. 10, 2010

Nov. 10, 2010

In PDF output (see for example 3.1.2 Strings section in tutorial.pdf), single-quote characters in code samples are rendered as unicode U2019, RIGHT SINGLE QUOTATION MARK. This conflicts with copy and paste from PDF to python prompt.

1 0

[issue7061] Improve turtle module documentation
by Alexander Belopolsky Nov. 10, 2010

Nov. 10, 2010

Alexander Belopolsky <belopolsky(a)users.sourceforge.net> added the comment: On Sun, Oct 31, 2010 at 8:00 PM, Éric Araujo <report(a)bugs.python.org> wrote: .. > “Python” is lower-cased only when referring to the executable (as a > file) itself. When talking about the language, the implementation or > the VM in an abstract way (not a file), It think it’s always “Python”. For the record, this is covered in the Python documentation style guide: """ Python The name of our favorite programming language is always capitalized. """ http://docs.python.org/dev/documenting/style.html ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue7061> _______________________________________

1 0

[issue10379] locale.format() input regression
by Łukasz Langa Nov. 10, 2010

Nov. 10, 2010

Łukasz Langa <lukasz(a)langa.pl> added the comment: Please use the deprecation process when possible. That would mean creating an alias for the function you want to remove somewhat like this (taken from configparser): def readfp(self, fp, filename=None): """Deprecated, use read_file instead.""" warnings.warn( "This method will be removed in future versions. " "Use 'parser.read_file()' instead.", PendingDeprecationWarning, stacklevel=2 ) self.read_file(fp, source=filename) ---------- nosy: +lukasz.langa _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10379> _______________________________________

1 0

pywin32 is now on sourceforge -- not python.net
by Vernon Cole Nov. 10, 2010

Nov. 10, 2010

The link for the pywin32 project in http://docs.python.org/py3k/using/windows.html#pywin32 points to http://python.net/crew/mhammond/win32/ which has been obsolete for some five years now. The correct link should be http://sourceforge.net/projects/pywin32/ -- Vernon Cole -- also known as kf7xm on sourceforge (and one of the developers for pywin32)

1 0

[issue10379] locale.format() input regression
by R. David Murray Nov. 10, 2010

Nov. 10, 2010

R. David Murray <rdmurray(a)bitdance.com> added the comment: Yeah, obviously that language can be improved. 'exactly' was meant to imply 'nothing but', but clearly it doesn't. If we want to restore more stringent backward compatibility and allow trailing text, it would be possible to make format an alias for format_string. I'm not sure this is a good idea, but it is the most sensible way to restore backward compatibility while still fixing the original bug that I can think of. Or...perhaps there is little need of both 'format' and 'format_string' as public APIs, and we could deprecate (without removing) one of them. On the other hand, I believe the original bug affects the Ubuntu code that triggered this report...in other words, absent this fix chances are there would eventually have been a bug report against that code that would have necessitated that it change to use format_string anyway in order to get the correct locale-specific number formatting. ---------- nosy: +lemburg _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10379> _______________________________________

1 0

Documentation typo
by Gautam Kotian (Googie) Nov. 10, 2010

Nov. 10, 2010

section 5.4 (Sets) The 3rd line in the demonstration section (output of the "print(basket)" command) has an error. 'banana' has been mis-spelled as 'bananna' - Googie

2 1

[issue10378] Typo in results of help(divmod)
by Richard Fuhr Nov. 10, 2010

Nov. 10, 2010

New submission from Richard Fuhr <richard.fuhr(a)gmail.com>: When running Python 2.7 if you invoke help(divmod) the first line of the resulting help displays Help on built-in function divmod in module __builtin__: but I believe that the name of the module is __builtins__ so the line should say Help on built-in function divmod in module __builtinsq__: ---------- assignee: docs@python components: Documentation messages: 120900 nosy: docs@python, rdfuhr priority: normal severity: normal status: open title: Typo in results of help(divmod) type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10378> _______________________________________

3 4