classification
Title: Mark up "subprocess" as module in its doc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: belopolsky, eric.araujo, ezio.melotti, georg.brandl, python-dev, terry.reedy
Priority: normal Keywords: patch

Created on 2010-11-11 02:52 by belopolsky, last changed 2012-11-08 08:18 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
subprocess-doc.diff belopolsky, 2010-11-11 02:52 review
Messages (9)
msg120937 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-11 02:52
I was going to commit this patch, but decided to ask for a second opinion.  I think module names in section titles should be marked up with :mod:.
msg120956 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-11 15:19
Marking up each and every instance of a module name is not mandatory IMO.  What’s important is that each document title starts with the :mod: construct, so that the HTML titles and index (at /library) be consistently useful.  See for example ast (which also suffers from non-standard markup in its docstring, but that’s another issue).  In addition, there are hierarchy problems in the index.
msg121057 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-12 19:09
1. Does the markup make any visual difference?
2. Does the markup affect the index?
3. What do other module docs do?

I notice that 'Tkinter' appears in several section headings. Is it marked? (Is the upper case a holdover that should be lowercased?)

'Turtle' also appears in several section headers. That could be interpreted as a reference to the class rather than the module.
msg121061 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2010-11-12 19:27
On Fri, Nov 12, 2010 at 2:09 PM, Terry J. Reedy <report@bugs.python.org> wrote:
..
> 1. Does the markup make any visual difference?

It does on my browser.  (I wouldn't have noticed it otherwise.) See
http://docs.python.org/dev/contents.html

> 2. Does the markup affect the index?

I don't think so because module names are already in the index.

This is either holdover or title-case.  In either case it should be
fixed.  Note that in some section titles it is lower case and marked
up properly.

> 'Turtle' also appears in several section headers. That could be interpreted
> as a reference to the class rather than the module.

In "Turtle graphics" it is neither -- just part of the name of the
graphics framework.  When it is a name of the class, as in " Overview
of available Turtle and Screen methods," is should be marked up with
:class: IMO.  In "Tell Turtle’s state", I think "turtle" should be
lower-cased.
msg121066 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-12 19:48
Eric: any :mod: role never affects the index.  Only the module directive does.

Otherwise, I concur that it's not mandatory to mark up every occurrence of the module name, but it's nice in section headings.
msg121069 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-12 20:22
>http://docs.python.org/dev/contents.html
The only thing I see there is the bold-facing of *PEP 3101*.
Is that what you are referring to?

In any case, with Georg's concurrence go ahead with this and any other modules you care about.
msg121093 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-12 23:50
I think that using e.g. :mod:`subprocess` in the subprocess page is redundant because there's no need to add a link to the page you are already reading. I'm also not sure that it looks too nice in the headers (iirc the font is different), but I haven't tried to apply the patch and see how it looks.
msg175140 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-11-08 08:12
New changeset 58564aeec8e4 by Ezio Melotti in branch '2.7':
#10385: use the mod role in subprocess docs.
http://hg.python.org/cpython/rev/58564aeec8e4

New changeset 8e8d391eb3eb by Ezio Melotti in branch '3.2':
#10385: use the mod role in subprocess docs.
http://hg.python.org/cpython/rev/8e8d391eb3eb

New changeset f45d1afb952b by Ezio Melotti in branch '3.3':
#10385: merge with 3.2.
http://hg.python.org/cpython/rev/f45d1afb952b

New changeset 5d7e7e7e2e82 by Ezio Melotti in branch 'default':
#10385: merge with 3.3.
http://hg.python.org/cpython/rev/5d7e7e7e2e82
msg175141 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-08 08:18
It looked OK and the :mod: role was already used throughout the page, so I applied the patch.
History
Date User Action Args
2012-11-08 08:18:31ezio.melottisetstatus: open -> closed

assignee: belopolsky -> ezio.melotti
versions: + Python 2.7, Python 3.3, Python 3.4
messages: + msg175141
type: enhancement
resolution: fixed
stage: commit review -> resolved
2012-11-08 08:12:15python-devsetnosy: + python-dev
messages: + msg175140
2010-11-12 23:50:25ezio.melottisetnosy: + ezio.melotti
messages: + msg121093
2010-11-12 20:22:05terry.reedysetmessages: + msg121069
2010-11-12 19:48:15georg.brandlsetmessages: + msg121066
2010-11-12 19:27:34belopolskysetmessages: + msg121061
2010-11-12 19:09:44terry.reedysetnosy: + georg.brandl, terry.reedy
messages: + msg121057
2010-11-11 15:19:47eric.araujosetnosy: + eric.araujo
messages: + msg120956
2010-11-11 02:52:12belopolskycreate