classification
Title: Missing cross-references in Doc/using
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: berker.peksag Nosy List: Kyle.Simpson, berker.peksag, docs@python, eric.araujo, ezio.melotti, ncoghlan, python-dev, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2011-07-21 11:56 by ncoghlan, last changed 2014-12-10 00:08 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
using-links.diff eric.araujo, 2011-10-14 14:26
Messages (20)
msg140812 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-07-21 11:56
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.
msg140813 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-07-21 12:10
Should also be an outgoing link to http://bugs.python.org/issue1739468
from the <script> entry.
msg145053 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-07 04:34
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).
msg145076 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-10-07 14:19
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
msg145096 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-07 16:16
Terry, might that other issue be #12298?
msg145149 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-07 22:16
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.
msg145307 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-10 15:50
> 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.
msg145312 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-10 19:13
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.
msg145318 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2011-10-11 00:45
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
msg145330 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-11 04:11
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.
msg145410 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-12 16:21
> 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.
msg145414 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-10-12 16:44
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.
msg145426 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-10-12 20:18
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?
msg145519 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-14 14:26
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.
msg145520 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-14 14:30
[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.
msg145522 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-10-14 14:52
BTW, I’ve done nothing about #1739468 because I don’t see why you wanted to add a link.
msg222417 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-07-06 20:51
Patch LGTM.
msg232403 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-12-09 23:47
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
msg232404 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-12-10 00:06
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
msg232405 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-12-10 00:08
Thanks for the patch, Éric.
History
Date User Action Args
2014-12-10 00:08:31berker.peksagsetstatus: open -> closed

type: behavior -> enhancement
assignee: eric.araujo -> berker.peksag

nosy: + berker.peksag
messages: + msg232405
resolution: fixed
stage: commit review -> resolved
2014-12-10 00:06:58python-devsetmessages: + msg232404
2014-12-09 23:47:44python-devsetnosy: + python-dev
messages: + msg232403
2014-07-06 20:51:19ezio.melottisetmessages: + msg222417
stage: needs patch -> commit review
2014-07-05 22:09:01BreamoreBoysettype: behavior
versions: + Python 3.4, Python 3.5, - Python 3.2, Python 3.3
2011-10-14 14:52:54eric.araujosetmessages: + msg145522
2011-10-14 14:30:07eric.araujosetmessages: + msg145520
2011-10-14 14:26:04eric.araujosetfiles: + using-links.diff
keywords: + patch
messages: + msg145519
2011-10-12 20:18:20terry.reedysetmessages: + msg145426
2011-10-12 16:44:37ezio.melottisetmessages: + msg145414
2011-10-12 16:21:40eric.araujosetmessages: + msg145410
2011-10-11 04:11:55terry.reedysetmessages: + msg145330
2011-10-11 00:45:35ncoghlansetmessages: + msg145318
2011-10-10 19:13:36terry.reedysetmessages: + msg145312
2011-10-10 15:50:02eric.araujosetassignee: eric.araujo
messages: + msg145307
2011-10-09 23:59:57mikehoysetnosy: - mikehoy
2011-10-07 22:16:13terry.reedysetmessages: + msg145149
2011-10-07 16:16:17eric.araujosetmessages: + msg145096
title: Missing using docs cross-references -> Missing cross-references in Doc/using
2011-10-07 14:19:59ncoghlansetmessages: + msg145076
2011-10-07 14:04:57mikehoysetnosy: + mikehoy
2011-10-07 05:51:55ezio.melottisetnosy: + ezio.melotti
2011-10-07 04:34:09terry.reedysetnosy: + terry.reedy
messages: + msg145053
2011-08-23 13:58:43Kyle.Simpsonsetnosy: + Kyle.Simpson
2011-07-22 21:27:29eric.araujosetkeywords: + easy
assignee: docs@python -> (no value)
stage: needs patch
nosy: + eric.araujo
2011-07-21 12:10:46ncoghlansetmessages: + msg140813
2011-07-21 11:57:06ncoghlansetassignee: docs@python

nosy: + docs@python
components: + Documentation
versions: + Python 2.7, Python 3.2, Python 3.3
2011-07-21 11:56:32ncoghlancreate