For new doc editors, it would be nicer if the filename (directory name, actually) had been changed to 'py_setup' or even 'py_usage'.

Éric Araujo <merwok@netwok.org> added the comment: 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@bugs.python.org> <http://bugs.python.org/issue12602> _______________________________________