[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Bryce Verdier]

Bryce Verdier  added the comment:

No worries, I totally understand. I was working on it a little bit at a time, 
as life would allow. And being probably more thorough than I needed to be. Here 
is the patch of everything that I've accomplished. Hope this helps.

--
keywords: +patch
Added file: http://bugs.python.org/file23125/issue-12031.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Éric Araujo]

Éric Araujo  added the comment:

After thinking about this, I think it may be easier for everyone if I just did 
the change.  It’s just a list of boring grep-sed combos to run, and it’s easier 
if a core dev just does it instead of reviewing a long patch.  Sorry if you 
invested time, Bryce.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Changing ``x`` to :data:`x` adds 4 chars.
Changing ``x()`` to :func:`x` justs adds 2.
If I were to review, I would prefer that the additions not trigger cascading 
line rewraps.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Ezio Melotti]

Ezio Melotti  added the comment:

``...`` should also be used for common names like True, False, None (no one 
needs links to their doc to see what they are), or, as Éric said, to avoid 
creating links for each occurrence of a name (one such example is the name of a 
module in the page that documents it).

I think that ``getattr(spam, ham)`` could be also written as 
:func:`getattr(spam, ham) ` in case you want to generate explicitly a 
link to getattr.  However in most of the cases this is not necessary.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Éric Araujo]

Éric Araujo  added the comment:

instead of*

An addition: in some cases, it may be on purpose that someone used ``somename`` 
instead of :func:`somename`, for example to avoid a ton of link in the doc of 
the somename function.  For the most part however, I believe it was just 
unawareness (or maybe unavailability) of the :data: construct that explains its 
absence.

One last precision: markup like ``getattr(spam, ham)`` should stay untouched: 
it is a code snippet, not just a reference to the function.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Éric Araujo]

Éric Araujo  added the comment:

> I would like to help out with this, as there seems to be a lot of
> work that needs to be done.

Thanks!  In my initial report, I was talking only about module-level names that 
are documented as code (``sys.path``) instead of module-level data 
(:data:`sys.path`); the point is that the latter form creates a link to the doc 
of the module-level name.

I wasn’t aware that some functions and keywords used code markup instead or 
link-creating markup, like you found out for eval and getattr.  These should be 
fixed too.

Terry: You’re right, ``x`` is the most generic markup for inline code in reST.  
It is used for command lines, program options that are not Python’s options 
(see #9312), bits of Python code, etc.

Now, about the amount of work needed: Don’t waste hours looking for all of 
these in the docs!  If you know basic shell commands, it’s easy to have *all* 
instances of ``sys.path`` changed to :data:`sys.path` in one go.  The thing 
requiring human attention is first listing all of the misuses of , second 
reviewing the changes.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Ezio Melotti]

Ezio Melotti  added the comment:

For global there's :keyword:.  Also note that :data: should be used for 
module-level variables (or constant) not for attributes of e.g. classes and 
instances.

If there are other ``...`` that can be fixed (even using something else like 
e.g. :func: or :meth:), they should be fixed as well, but apparently ``...`` 
was often misused instead of :data: (maybe :data: was a recent addition).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Terry J. Reedy]

Terry J. Reedy  added the comment:

I presume so. I believe ``x`` is meant for general code like ``for thing in 
group: print(thing)``. While Éric specifically mentioned the :data: role, I 
presume the same idea applies to :func: and possibly other link-generating 
roles.

Is there a statement role, so that "effect of the ``global`` statement, " could 
be changed to link to the global statement doc?

This seems like a great project for a beginning developer to contribute patches.

Georg, do you have any reason to not have markup become more specific?

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Bryce Verdier]

Bryce Verdier  added the comment:

Is this more what was in mind for the bug?

--
Added file: http://bugs.python.org/file22850/issue12301.test_patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Ezio Melotti]

Ezio Melotti  added the comment:

Nope, ``...`` can be used for generic pieces of code, whereas e.g. 
:data:`sys.stdout` indicates that stdout is a "data" attribute of the sys 
module.
If you use :data:`...` and rebuild the doc (cd Doc/; make html), you will see 
that e.g. sys.stdout will be then a link to the sys.html page.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Bryce Verdier]

Bryce Verdier  added the comment:

I would like to help out with this, as there seems to be a lot of work that 
needs to be done.

I guess I'm a little unsure about what you mean by ``code`` instead of :data:. 
Is ``code`` generic? Like in Doc/tutorials/classes.rst I see a lot of things 
similar to ``eval()``. Are you saying that dhould be changed to :data:eval()?

--
nosy: +louiscipher

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Ezio Melotti]

Ezio Melotti  added the comment:

+1

--
keywords: +easy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Terry J. Reedy]

Terry J. Reedy  added the comment:

Links are good ;-).

--
nosy: +terry.reedy
stage:  -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Ezio Melotti]

Changes by Ezio Melotti :


--
nosy: +ezio.melotti

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue12301] Use :data:`sys.thing` instead of ``sys.thing`` throughout

[Éric Araujo]

New submission from Éric Araujo :

In a great number of files, the ``code`` markup is used instead of the :data: 
role, which would create a link to the appropriate definition.

Unless someone objects, I would like to change all of them.

--
assignee: eric.araujo
components: Documentation
messages: 138004
nosy: eric.araujo
priority: normal
severity: normal
status: open
title: Use :data:`sys.thing` instead of ``sys.thing`` throughout
versions: Python 2.7, Python 3.2, Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com