How best to handle the docs for a renamed module?
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name. But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name? -Brett
On a sunny day, Brett Cannon <brett@python.org> wrote:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
I'd say use the new names, so people can get used to them sooner -- otherwise all you do is postpone the confusion until they're going to use 3.0. People who've only head of Queue will be fine as long as searching for Queue in the index and TOC will find them a pointer to queue (and that one has a "versionadded 2.6 -- renamed from Queue" note). -- --Guido van Rossum (home page: http://www.python.org/~guido/)
On Sun, May 11, 2008 at 8:17 PM, Guido van Rossum <guido@python.org> wrote:
On a sunny day, Brett Cannon <brett@python.org> wrote:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
I'd say use the new names, so people can get used to them sooner -- otherwise all you do is postpone the confusion until they're going to use 3.0. People who've only head of Queue will be fine as long as searching for Queue in the index and TOC will find them a pointer to queue (and that one has a "versionadded 2.6 -- renamed from Queue" note).
OK, documented as such. -Brett
Brett Cannon schrieb:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
I've now updated docs for the Queue, SocketServer and copy_reg modules in the trunk. * File names (only important for copy_reg) and references use the new name. * There are two "module" directives in the file; one for the old, one for the new name. The synopsis of the old name is "Old name of the XXX module." * There is a note after the module directives that tells The :mod:`XXX` module has been renamed to :mod:`YYY` in Python 3.0. It is importable under both names in Python 2.6 and the rest of the 2.x series. Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out.
On 2008-05-12 04:34, Brett Cannon wrote:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
How hard would it be to add a redirects from the old pages to the new ones ? mod_rewrite does wonders - well, provided you find the right patterns... -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, May 16 2008)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
:::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,MacOSX for free ! :::: eGenix.com Software, Skills and Services GmbH Pastor-Loeh-Str.48 D-40764 Langenfeld, Germany. CEO Dipl.-Math. Marc-Andre Lemburg Registered at Amtsgericht Duesseldorf: HRB 46611
* M.-A. Lemburg wrote:
On 2008-05-12 04:34, Brett Cannon wrote:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
How hard would it be to add a redirects from the old pages to the new ones ?
mod_rewrite does wonders - well, provided you find the right patterns...
The "pattern" can be a simple text file maintained in subversion:: oldurl newurl ... And then you can utilize RewriteMap to get that into the apache. nd
On Fri, May 16, 2008 at 5:43 AM, M.-A. Lemburg <mal@egenix.com> wrote:
On 2008-05-12 04:34, Brett Cannon wrote:
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
But what to do about all the references. Should we leave them pointing at Queue to lessen confusion for people who read about some module on some other site that isn't using the new name, or update everything in 2.6 to use the new name?
How hard would it be to add a redirects from the old pages to the new ones ?
mod_rewrite does wonders - well, provided you find the right patterns...
Well, the problem is that only solves the online docs issue, not offline viewing. And now that the docs can be built easily, I at least find myself referring to the docs mostly offline rather than through docs.python.org. -Brett
[Brett[
For the sake of argument, let's consider the Queue module. It is now named queue. For 2.6 I plan on having both Queue and queue listed in the index, with Queue deprecated with instructions to use the new name.
FWIW, I don't consider this to be a value added backport. Renaming doesn't benefit a 2.6 user. All it does is add confusion and it may break code where users or third-party libraries are already using the new name. I say leave the new names in 3.0 and let the 2-to-3 tool do its job. Why confuse the 2.6 landscape with double naming clutter. Raymond
Raymond Hettinger wrote:
I say leave the new names in 3.0 and let the 2-to-3 tool do its job. Why confuse the 2.6 landscape with double naming clutter.
To increase the common subset of code which can run on both 2.6 and 3.0 *without* invoking 2to3? PEP-8'ifying these names also makes them easier for at least me to remember (since I don't have to worry about whether or not the module name includes unexpected underscores or strange capitalisation) Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia --------------------------------------------------------------- http://www.boredomandlaziness.org
On Fri, May 16, 2008 at 5:49 PM, Nick Coghlan <ncoghlan@gmail.com> wrote:
Raymond Hettinger wrote:
I say leave the new names in 3.0 and let the 2-to-3 tool do its job. Why confuse the 2.6 landscape with double naming clutter.
To increase the common subset of code which can run on both 2.6 and 3.0 *without* invoking 2to3?
Right. 2.6 is trying to be as much of a reasonable subset of Python 3.0 as possible. This includes module names.
PEP-8'ifying these names also makes them easier for at least me to remember (since I don't have to worry about whether or not the module name includes unexpected underscores or strange capitalisation)
That too. =) -Brett
participants (8)
-
Alexandre Vassalotti -
André Malo -
Brett Cannon -
Georg Brandl -
Guido van Rossum -
M.-A. Lemburg -
Nick Coghlan -
Raymond Hettinger