classification
Title: wrong links and examples in the functional HOWTO
Type: Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: akuchling, docs@python, eli.bendersky, eric.araujo, ezio.melotti, orsenthil, pitrou, python-dev, rhettinger, terry.reedy
Priority: normal Keywords: easy

Created on 2011-11-21 04:40 by eli.bendersky, last changed 2012-01-16 06:52 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
functional-patch.txt akuchling, 2011-11-23 21:00 Patch updating links and adding a 2.x warning review
Messages (12)
msg148030 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-21 04:40
Michał Chałupczak reported in this docs@ list that the links to IBM developerworks articles are wrong.

From some additional observation, the code samples on the 3.x page use the external `functional` module, which was not ported to Python 3 at all.

I wonder whether it makes sense to use external modules in official Python documentation, since these are not guaranteed to be ported. This issue is a good example of this happening.

The HOWTO should be probably rewritten to use only the stdlib. The links to IBM developerworks should be, IMHO, removed, since they point to articles written in 2001 and have code samples that won't work on Python 3.x
msg148120 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-22 15:13
Broken links should obviously be fixed, either to their newer location if it can be found or to Web Archive links.

I think that it’s a good thing to link to some outside articles and code from the official docs; we acknowledge that the stdlib is not the whole of the Python world and we put good writings/code into the spotlight.  Here, even if the code is 2.x-only, the ideas and examples it contains can IMO still be valuable for readers, even if they can’t be directly used, so my vote is to keep them.
msg148206 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2011-11-23 21:00
Here's a patch against the 3.3 trunk.
msg148228 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-24 04:52
Andrew, thanks, but I still think it's a bigger problem that the page discusses a module which is not available on Python 3.x - this means that a user following the page can't just type in the code and make it run.

The links can be fixed and kept there, as Éric suggests, perhaps with a disclaimer, but code on the page itself should be valid - this is part of our official documentation, after all.
msg148267 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-24 15:59
Thanks for the fixed links amk.  I think they can be fixed in the repo right now.

[Eli]
> I still think it's a bigger problem that the page discusses a module which
> is not available on Python 3.x - this means that a user following the page
> can't just type in the code and make it run.
It’s only one section that’s affected, so +1 to replacing its contents with just a link and short description (“the functional module does X and Y for Python 2”).  Before doing that, would you have the time to contact its author and inquire about porting plans?

(BTW, the file is also inconsistent in its use of :: vs. implicit code blocks; I wonder if that affects doctest or the “hide prompts” button.)
msg148271 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2011-11-24 16:16
> Before doing that, would you have the time to contact its author and inquire about porting plans?

I hope to find the time. I was also thinking about an alternative - since the HOWTO probably uses just a handful of functions from that module perhaps they can just be re-implemented and placed in the HOWTO. This can remove the unhealthy dependency on an external module, as well as provide some extra examples.
msg148275 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-11-24 16:28
Good idea.  The functions used are: compose, partial (which we have in functools), flip, foldl.

I will disagree with “unhealthy”: I’m sure adding this link was a deliberate exposure of an external module, to put a well-written solution to the spotlight as a service to the users and an acknowledgment to the author.  If the cost is a little links bookkeeping for us, it is small :)
msg148464 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2011-11-27 23:55
Yes, linking to the functional module was to point people to a module that might be useful, even if it's not in the stdlib.  A numeric processing or socket handling HOWTO would also pretty much have to link to non-stdlib sources.  The purpose of documentation is to be useful to the reader, so I think if linking to something external would be reasonably useful, we should do it.

Another motivation for linking was to provide alternative explanations; if the reader finds the Functional HOWTO boring or too superficial or too complicated, maybe an alternative discussion like Mertz's "Text Processing" will fit their brain better.  (At least until those alternative sources become so outdated that they're useless...)
msg148867 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-12-05 11:21
This section has been removed from the 3.x docs in 3828f81a64e7 and 2aeef275bec8, but it's still there in 2.7.
msg150099 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-12-22 15:45
New changeset c6880edaf6f3 by Senthil Kumaran in branch '2.7':
Issue13443 - Remove the functional module examples from 2.7 (as module is
http://hg.python.org/cpython/rev/c6880edaf6f3
msg150100 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2011-12-22 15:46
Fixed this in 2.7.
msg151331 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-01-16 06:52
Sorry, my messages could be confusing.  What I meant is: While I think that Antoine’s doc changes were clear improvements, in the specific case of the functional howto there were good arguments in favor of keeping the part about the functional module.
History
Date User Action Args
2012-01-16 06:52:19eric.araujosetmessages: + msg151331
2012-01-16 06:37:04eric.araujosetmessages: - msg150399
2012-01-16 06:36:29eric.araujosetmessages: - msg150397
2011-12-30 21:40:42eric.araujosetnosy: akuchling, rhettinger, terry.reedy, orsenthil, pitrou, ezio.melotti, eric.araujo, eli.bendersky, docs@python, python-dev
messages: + msg150399
2011-12-30 21:37:13eric.araujosetmessages: + msg150397
2011-12-22 15:46:13orsenthilsetstatus: open -> closed

nosy: + orsenthil
messages: + msg150100

resolution: fixed
2011-12-22 15:45:17python-devsetnosy: + python-dev
messages: + msg150099
2011-12-05 11:21:15ezio.melottisetnosy: + pitrou
messages: + msg148867
2011-11-27 23:55:00akuchlingsetmessages: + msg148464
2011-11-26 00:26:08terry.reedysetnosy: + terry.reedy
2011-11-24 16:28:11eric.araujosetmessages: + msg148275
2011-11-24 16:16:14eli.benderskysetmessages: + msg148271
2011-11-24 15:59:46eric.araujosetmessages: + msg148267
2011-11-24 04:52:13eli.benderskysetmessages: + msg148228
2011-11-23 21:00:13akuchlingsetfiles: + functional-patch.txt

messages: + msg148206
2011-11-22 15:13:39eric.araujosetnosy: + rhettinger, eric.araujo
messages: + msg148120
2011-11-21 12:07:31ezio.melottisetkeywords: + easy
nosy: + ezio.melotti

stage: needs patch
2011-11-21 04:40:03eli.benderskycreate