homepage

General untidiness in the anchor names (and lack of same for entries like <script>)
Missing incoming:
- from "Invoking the Interpreter" in the tutorial
- direct link from runpy.run_module to -m switch
- direct link from runpy.run_path to <script>
Missing outgoing:
- direct link from <script> to runpy.run_path
Also, zipfile/dir execution was added in 2.6, not 2.5.

Should also be an outgoing link to http://bugs.python.org/issue1739468
from the <script> entry.

This is all a puzzle to me. "<script>" ??
Links from docs to tracker issue??
There is at least one other issue about bad links (from builtin functions entries).

The 'using docs' are, oddly enough, the part of the docs called 'using' :)
In particular, the part about the command line components (including the '<script>' argument):
http://docs.python.org/using/cmdline.html 

Terry, might that other issue be #12298?

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.

> 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.

I was not necessary suggesting that the filename actually be changed, just that the mapping between docs and filenames is not always obvious. I will somedays look at the dev docs doc page and see if I have any further suggestions to help.
Add 'in the Python doc context' after 'not familiar with it'. I *am* familiar with <text> in monofont ascii text and use it, for instance, in newsgroup posts. But unlike man pages, the Python docs are not so restricted and, except in this instance, use italics for parameter names. I suggest that it do so in this instance also, using *script* (in bold-faced italic) as the entry title.

Don't feel bad about not recognising the context - this stuff wasn't documented at all for a long time, and it wasn't until Georg pointed me to the usage docs that I realised adding it there would be the right place. I should have remembered that and been less cryptic when creating this issue.
It may suggest a meta-issue though - perhaps 'Documenting Python' should grow a devguide-style description of the Docs layout in source control, with a pointer from the devguide's directory layout description [1]?
[1] http://docs.python.org/devguide/setup.html#directory-structure 

That was the page I said I would look at. My suggest is that one or more of the directory entries could have either a bit more information about the directory or a "More info" link to a separate page. As a remember, files for modules were named after the module and easy to find. Those could be disposed of in one sentence. But files for the manuals were less so and could use more info.
My memory of Objects is that most files were obvious but, again, a few were/are not.

> I suggest that it do so in this instance also, using *script* (in
> bold-faced italic) as the entry title.
What do you think about :file:`{script}`? file+{} is what Sphinx uses for filenames with replaceable parts, which map to the HTML var element, which the stylesheets display as italics.

The italics parts are easier to recognize when they are within regular text (e.g. :file:`path/with/python{XY}/file`). If the whole text is in italic people might not notice the difference.

Since *script* is a file -- that is all variable -- that seems appropriate. 
Bold italic tends to be more notably different from bold italic than the normal pair. In any case, italic is the doc standard for function parameter names. It seems more sensible than introducing a unique occurrence of angle brackets. An alternative is to simply delete the angle brackets. 
If we consistently applied the "italicize non-literal symbolic parameter names" rule to command line examples, we would italicize 'command', 'module-name', 'script', and 'args' in
python [-BdEiOQsStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
just like in function signatures. I actually would like that as it would similarly diffentiate them from the literal constants meant to be entered as written. Has that ever been discussed by the doc group?

Attached path adds these links:
> Missing incoming:
> - from "Invoking the Interpreter" in the tutorial
> - direct link from runpy.run_module to -m switch
> Missing outgoing:
> - direct link from <script> to runpy.run_path
I couldn’t add this one:
> - direct link from runpy.run_path to <script>
I tried adding a standard reST link target (.. _using-on-script:) but that didn’t seem to work with the describe item. I added a link to the nearest heading instead, but maybe it is after all redundant: the seealso section of library/runpy already points to using/cmdline.

[Terry]
> It may suggest a meta-issue though - perhaps 'Documenting Python'
> should grow a devguide-style description of the Docs layout in source
> control
I would just describe the layout of the Doc subtree in the same devguide page. Care to open another bug for that?
> If we consistently applied the "italicize non-literal symbolic parameter names"
> rule to command line examples, we would italicize 'command', 'module-name',
> 'script', and 'args' in
> 
> python [-BdEiOQsStuUvVWxX3?] [-c command | -m module-name | script | - ] [args]
> 
> just like in function signatures. I actually would like that as it would
> similarly diffentiate them from the literal constants meant to be entered as
> written. Has that ever been discussed by the doc group?
Not that I recall. Currently the "python [-Bd etc.]" line is currently a code block, and as such cannot gain inline markup (:file:), but this is not insurmountable.

BTW, I’ve done nothing about #1739468 because I don’t see why you wanted to add a link.

Patch LGTM.

New changeset bd14c4e5ef00 by Berker Peksag in branch '3.4':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/bd14c4e5ef00
New changeset 3a648b3d1694 by Berker Peksag in branch 'default':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/3a648b3d1694 

New changeset 078dbecf2e2c by Berker Peksag in branch '2.7':
Issue #12602: Add missing cross-references to runpy and using/cmdline docs.
https://hg.python.org/cpython/rev/078dbecf2e2c 

Thanks for the patch, Éric.