This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Tutorial links to file object methods are broken.
Type: behavior Stage:
Components: Documentation Versions: Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, jonroach@icloud.com, r.david.murray
Priority: normal Keywords:

Created on 2017-01-06 09:58 by jonroach@icloud.com, last changed 2022-04-11 14:58 by admin.

Messages (3)
msg284806 - (view) Author: Jonathan Roach (jonroach@icloud.com) Date: 2017-01-06 09:58
The file documentation (as seen in python.org) went missing in 3.3. In 2.7.13 it can be found in 'The Python Standard Library' as section '5.9 File Objects', between '5.8 Mapping Types' and '5.10 memory view type'. In 3.3 and onwards this section is no longer present, and, as far as I can tell, is not present elsewhere in the documentation.
[related: in 'The Python Tutorial' section '7.2.1 Methods of File Objects' the inline references to the file object methods are shown as references, but without a target]
msg284825 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2017-01-06 15:33
The tutorial links are definitely bugs, and the section may need some tweaking.  The 'file object' documentation is replaced by the io module, which completely defines the file object API.  There is a link from the 'file object' glossary entry to the IO module indicating this.

Only 3.6 and 3.7 docs get documentation updates at this point, so I've removed the others from versions (we use versions to say where things will get fixed).  (Well, 3.5 docs can still get updates at the moment, but that won't last long, final is soon.)
msg284848 - (view) Author: Jonathan Roach (jonroach@icloud.com) Date: 2017-01-06 20:47
OK, I understand that the older versions aren't going to be revised - that makes sense.

I think part of the reason I submitted this is the reader's path from the open() documentation to the most relevant part of the io documentation (the interface) is long and narrow: open()->file object(in the Glossary)->io(see note)..and then scroll several pages down.
Note: the link to io from the 'file object' glossary entry is visually tiny, and in last paragraph - effectively making it almost invisible. This also seems to be the only place in the chain of links from open() which gets you to the io documentation.
When trying to find the interface documentation I tried the visually bigger, earlier links and ended up like I was being given the run-around through the various glossary entries.
As a documentation user I'd ideally like a direct link (which is a bit visually bigger than 'io') from open() to the relevant, interface section of the io documentation. However, upstanding you have a better feel for the tone of the documentation, I can see you might take a different route.
History
Date User Action Args
2022-04-11 14:58:41adminsetgithub: 73361
2017-01-06 20:47:31jonroach@icloud.comsetmessages: + msg284848
2017-01-06 15:33:15r.david.murraysetnosy: + r.david.murray
title: Documentation for File objects missing -> Tutorial links to file object methods are broken.
messages: + msg284825

versions: - Python 3.3, Python 3.4, Python 3.5
2017-01-06 09:58:43jonroach@icloud.comcreate