classification
Title: Doc doc: incorrect description of some roles as format-only
Type: enhancement Stage: resolved
Components: Devguide Versions:
process
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 2014-10-11 14:39 by berker.peksag. This issue is now closed.

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

http://hg.python.org/devguide/file/f518f23d06d5/documenting.rst#l984

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

envvar
    An environment variable. Index entries are generated.

keyword
    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:
:
option
    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.

https://docs.python.org/devguide/docquality.html#helping-with-the-developers-guide
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
https://hg.python.org/devguide/rev/bef3ddfe5d09
msg229082 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-10-11 12:39
Thanks!
History
Date User Action Args
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