[docs] [issue12602] Missing cross-references in Doc/using

Terry J. Reedy report at bugs.python.org
Sat Oct 8 00:16:13 CEST 2011


Terry J. Reedy <tjreedy at udel.edu> added the comment:

As of 2.7/3.2, the doc is named "Python Setup and Usage" at
http://docs.python.org/index.html
http://docs.python.org/using/cmdline.html (and other chapters)
and in the contents list of the Windows help version.
For new doc editors, it would be nicer if the filename (directory name, actually) had been changed to 'py_setup' or even 'py_usage'.

Looking in the first chapter, which you finally referenced, I do see an entry for '<script>', with the brackets, that can be both a target and container of links. That usage, with a generic argument name in angle brackets, may be unique in the docs. (I looked at trace, profile, pydoc, timeit, test, and doctest docs.) So don't be so surprised that others are not familiar with it. 

Now that is cleared up:
+1 on the links suggested in the original message.

-1 on a link to the tracker issue. That is not a coherent document and cannot be edited and improved. If more doc is needed, there should have been and could be a PEP, addition to the <script> entry, or a new chapter section 1.3 Zipfiles.

---
>Terry, might that other issue be #12298?

Yes. I see you have applied a fix.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12602>
_______________________________________


More information about the docs mailing list