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

Éric Araujo report at bugs.python.org
Mon Oct 10 17:50:03 CEST 2011


Éric Araujo <merwok at netwok.org> added the comment:

> For new doc editors, it would be nicer if the filename (directory name, actually)
> had been changed to 'py_setup' or even 'py_usage'.
py_setup would conflict with pysetup, the installer part of distutils2/packaging.  py_ seems redundant to me, we are in the Python docs.

> 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. 
I however am familiar with the use of <brackets>, $SHELL-LIKE-DOLLAR, OPTPARSE-LIKE-ALLCAPS or even {str-format-like-braces} to mark up metavariables.  “Use python -m <module> or python -c "YOUR CODE HERE" or python path/to/script” is no problem; maybe it is because other documentation (man pages?) I’m familiar with use it.  (I even see them in email, like in “$deity knows etc.”)

> +1 on the links suggested in the original message.
I’ll put up a patch for review.

> -1 on a link to the tracker issue.
I’ll see if I can add a few lines with the gist of the bug report, then.

----------
assignee:  -> eric.araujo

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


More information about the docs mailing list