Proposal: an unchanging URL for Python documentation

[Steve]

posted on: comp.lang.python
emailed to: do**@python.org

I have a suggestion/request that will, I think, improve the Python
documentation.

Currently, the Python documentation in HTML format is stored at URLs
that change with each new release of Python. That is, for example, the
documentation for the os module is at
http://python.org/doc/2.3/lib/module-os.html for release 2.3 of Python,
at http://python.org/doc/2.4/lib/module-os.html for release 2.4 and so
on.

I propose that an additional a URL be set up for the Python HTML
documentation. This URL will always contain the current version of the
documentation. Suppose we call it "current". Then (while 2.4 is still
the current version) the documentation for the os module would also be
available at
http://python.org/doc/current/lib/module-os.html.

There are three advantages to this proposal.

(1) It is cheap and easy to do.

(2) If a person regularly refers to the documentation for the os
module, he can bookmark
http://python.org/doc/current/lib/module-os.html and always be sure of
getting the most current version.

(3) This would give Pythonistas -- basically as a freebie --
annotatable documentation. You may be familiar with Wikalong (
http://www.wikalong.org/ ). Wikalong basically allows you to annotate
any URL. If we had a "current" URL for Python documentation, people
could add Wikalong notes to the current documentation without worrying
that the annotations would not survive the release of the next version
of Python. Being able to use Wikalong would provide the Python
community with the opportunity to experiment with annotatable documents
(not to mention, ride the leading edge of the Wikalong wave). And
those who dislike annotated documentation can easily ignore it or turn
it off the Wikalong sidebar (assuming that they have Wikalong installed
in the first place).

-- Steve Ferg

[Skip Montanaro]

steve> I propose that an additional a URL be set up for the Python HTML
steve> documentation. This URL will always contain the current version
steve> of the documentation. Suppose we call it "current". Then (while
steve> 2.4 is still the current version) the documentation for the os
steve> module would also be available at
steve> http://python.org/doc/current/lib/module-os.html.

Time machine at work? The above URL works for me now.

steve> (3) This would give Pythonistas -- basically as a freebie --
steve> annotatable documentation. You may be familiar with Wikalong (
steve> http://www.wikalong.org/ ). Wikalong basically allows you to
steve> annotate any URL.

But appears to be firefox-specific.

Skip

[Tim Peters]

[Steve]

I have a suggestion/request that will, I think, improve the Python
documentation.

Currently, the Python documentation in HTML format is stored at URLs
that change with each new release of Python. That is, for example, the
documentation for the os module is at
http://python.org/doc/2.3/lib/module-os.html for release 2.3 of Python,
at http://python.org/doc/2.4/lib/module-os.html for release 2.4 and so
on.
Have you tried <http://docs.python.org>?
I propose that an additional a URL be set up for the Python HTML
documentation. This URL will always contain the current version of the
documentation. Suppose we call it "current". Then (while 2.4 is still
the current version) the documentation for the os module would also be
available at
http://python.org/doc/current/lib/module-os.html.
Try

http://docs.python.org/lib/module-os.html
There are three advantages to this proposal.

(1) It is cheap and easy to do.

(2) If a person regularly refers to the documentation for the os
module, he can bookmark
http://python.org/doc/current/lib/module-os.html and always be sure of
getting the most current version.

(3) This would give Pythonistas -- basically as a freebie --
annotatable documentation. You may be familiar with Wikalong (
http://www.wikalong.org/ ). Wikalong basically allows you to annotate
any URL. If we had a "current" URL for Python documentation, people
could add Wikalong notes to the current documentation without worrying
that the annotations would not survive the release of the next version
of Python. Being able to use Wikalong would provide the Python
community with the opportunity to experiment with annotatable documents
(not to mention, ride the leading edge of the Wikalong wave). And
those who dislike annotated documentation can easily ignore it or turn
it off the Wikalong sidebar (assuming that they have Wikalong installed
in the first place).

Con: It's already there, and TOOWTDI <wink>.

[Michael Spencer]

Skip Montanaro wrote:

steve> I propose that an additional a URL be set up for the Python HTML
steve> documentation. This URL will always contain the current version
steve> of the documentation. Suppose we call it "current". Then (while
steve> 2.4 is still the current version) the documentation for the os
steve> module would also be available at
steve> http://python.org/doc/current/lib/module-os.html.

Time machine at work? The above URL works for me now.
....
But appears to be firefox-specific.

Skip

Works for me with both Firefox and IE6 under WinXP

Michael

[Skip Montanaro]

Skip> But appears to be firefox-specific.

Michael> Works for me with both Firefox and IE6 under WinXP

The wikalong.org thing is firefox-specific. You trimmed too much from my
reply.

Skip

[Fredrik Lundh]

"Steve" <st***@ferg.org> wrote:

I propose that an additional a URL be set up for the Python HTML
documentation. This URL will always contain the current version of the
documentation. Suppose we call it "current". Then (while 2.4 is still
the current version) the documentation for the os module would also be
available at
http://python.org/doc/current/lib/module-os.html.

did you check that link before you posted it?

</F>

[Erik Max Francis]

Fredrik Lundh wrote:

did you check that link before you posted it?

Works here. Your browser is probably concluding the trailing . is part
of the URL, rather than sentence punctuation :-).

--
Erik Max Francis && ma*@alcyone.com && http://www.alcyone.com/max/
San Jose, CA, USA && 37 20 N 121 53 W && AIM erikmaxfrancis
Dear World: I am leaving because I am bored.
-- George Sanders (in his suicide note)

[Robert Kern]

Erik Max Francis wrote:

Fredrik Lundh wrote:

did you check that link before you posted it?

Works here. Your browser is probably concluding the trailing . is part
of the URL, rather than sentence punctuation :-).

No, Fredrik knows that it works. The OP seemed to be under the
impression that it didn't (and was posting to propose that it should
exist and behave as it actually does).

--
Robert Kern
rk***@ucsd.edu

"In the fields of hell where the grass grows high
Are the graves of dreams allowed to die."
-- Richard Harter

[Steve]

I stand corrected. Not only does what I wanted already exist, it seems
to exist in TWO places. For the module index, for instance, there is

http://docs.python.org/modindex.html

and there also is

http://python.org/doc/current/modindex.html

Anybody know why there are two different URLs?

Which one should be considered the "official" current documentation
URL? (REASON: A person wanting to Wikalong annotate the "official"
current documentation URL would want to know which one to annotate.)

[Aahz]

In article <11**********************@z14g2000cwz.googlegroups .com>,
Steve <st***@ferg.org> wrote:

http://docs.python.org/modindex.html

and there also is

http://python.org/doc/current/modindex.html

Anybody know why there are two different URLs?

Which one should be considered the "official" current documentation
URL? (REASON: A person wanting to Wikalong annotate the "official"
current documentation URL would want to know which one to annotate.)

I'd consider the official URL to be

http://www.python.org/doc/current/modindex.html

The primary reason for creating docs.python.org was to make Google
searches easier. I believe the eventual intent is to make that the
official URL, but there were some glitches in setting it up and I'm not
sure whether they've been completely ironed out.
--
Aahz (aa**@pythoncraft.com) <*> http://www.pythoncraft.com/

"The joy of coding Python should be in seeing short, concise, readable
classes that express a lot of action in a small amount of clear code --
not in reams of trivial code that bores the reader to death." --GvR

[Simon Brunning]

On 4/19/05, Skip Montanaro <sk**@pobox.com> wrote:

... the documentation for the os
steve> module would also be available at
steve> http://python.org/doc/current/lib/module-os.html.

Time machine at work? The above URL works for me now.

Yup, but it's not all unchanging. Take, for example,
<http://www.python.org/doc/current/tut/node16.html>. I have wanted to
steer people towards that page a number of times, and that node number
keeps changing.

--
Cheers,
Simon B,
si***@brunningonline.net,
http://www.brunningonline.net/simon/blog/

[olsongt]

Simon Brunning wrote:

Yup, but it's not all unchanging. Take, for example,
<http://www.python.org/doc/current/tut/node16.html>. I have wanted to
steer people towards that page a number of times, and that node number keeps changing.

Here's the code I've been using to translate the latex2html links
(including embedded anchors) to something that has some context. I can
lookup links via something that is understandable like
('os','path','exists'). A truly adventurous person could probably use
this to write a redirector.

http://pyxr.sourceforge.net/PyXR/c/p...rawler.py.html