This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Doc doc: incorrect description of some roles as format-only
Type: enhancement Stage: resolved
Components: Devguide Versions:
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, emily.zhao, eric.araujo, ezio.melotti, georg.brandl, python-dev, terry.reedy
Priority: normal Keywords: easy, patch

Created on 2012-08-07 01:24 by chris.jerdonek, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
issue15569.patch emily.zhao, 2014-06-07 18:52
Messages (6)
msg167594 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-08-07 01:24
After the section describing roles that create cross-references to C-language constructs, the Dev Guide says this, "The following roles don’t do anything special except formatting the text in a different style."

However, some of the roles following in that section do do special things other than formatting.  For example--

    An environment variable. Index entries are generated.

    The name of a Python keyword. Using this role will generate a link to the documentation of the keyword....
The description should be changed, or better yet, the roles that do something special should be moved to a different section.
msg168549 - (view) Author: Mike Hoy (mikehoy) * Date: 2012-08-19 07:24
I would like to submit a patch for this. Is anyone currently working on one?
msg217149 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-04-25 03:58
There are no versions for the devguide. There is another misplaced role:
    A command-line option of Python. The leading hyphen(s) must be included. If a matching cmdoption directive exists, it is linked to. For options of other programs or scripts, use simple ``code`` markup.

I think "The following role does possibly create a cross-reference, but does not refer to objects:" should be changed to something like "The following roles do not refer to module objects, but possibly create cross-references or internal links:". Move the three misplaced roles here, along with token and term.
msg219959 - (view) Author: Emily Zhao (emily.zhao) * Date: 2014-06-07 18:52
I moved the 3 misplaced roles (envvar, keyword, and option) and changed the description for the new section per Terry's suggestions. Patch is attached and needs to go in the devguide repo.
msg229081 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-11 12:39
New changeset bef3ddfe5d09 by Georg Brandl in branch 'default':
Closes #15569: some roles do create more than formatting
msg229082 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-10-11 12:39
Date User Action Args
2022-04-11 14:57:33adminsetgithub: 59774
2014-10-11 14:39:09berker.peksagsetstage: needs patch -> resolved
2014-10-11 12:50:09georg.brandlsetstatus: open -> closed
resolution: fixed
2014-10-11 12:39:36georg.brandlsetstatus: closed -> open

nosy: + georg.brandl
messages: + msg229082

resolution: fixed -> (no value)
stage: resolved -> needs patch
2014-10-11 12:39:31python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg229081

resolution: fixed
stage: needs patch -> resolved
2014-06-07 18:52:49emily.zhaosetfiles: + issue15569.patch

nosy: + emily.zhao
messages: + msg219959

keywords: + patch
2014-04-25 03:58:19terry.reedysetnosy: + terry.reedy

messages: + msg217149
versions: - Python 2.7, Python 3.2, Python 3.3, Python 3.4
2012-10-24 20:23:27ezio.melottisettype: enhancement
versions: + Python 2.7, Python 3.2, Python 3.3, Python 3.4
2012-10-21 20:37:23mikehoysetnosy: - mikehoy
2012-08-19 07:24:24mikehoysetnosy: + mikehoy
messages: + msg168549
2012-08-08 22:33:38eric.araujosetassignee: docs@python

nosy: + eric.araujo, docs@python
stage: needs patch
title: Dev Guide format-only roles -> Doc doc: incorrect description of some roles as format-only
2012-08-07 01:24:06chris.jerdonekcreate