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.

classification
Title: Mark up of references in different form
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, martin.panter, python-dev, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2016-05-16 08:33 by serhiy.storchaka, last changed 2022-04-11 14:58 by admin.

Files
File name Uploaded Description Edit
refs_forms.patch serhiy.storchaka, 2016-05-16 08:33 review
refs_forms2.patch serhiy.storchaka, 2016-05-16 20:34 review
refs_forms3.patch serhiy.storchaka, 2016-05-18 11:14 review
Messages (9)
msg265686 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-16 08:33
When there is a reference from the term in different form (e.g. in plural), the modified part can be appended outside of the reference: ":term:`bytes-like object`\ s". But this looks not very nice in rendered document, since only a part of the word is undescored. Proposed patch expands similar references to full words: ":term:`bytes-like objects <bytes-like object>`".
msg265688 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-05-16 09:32
These bug me too. For the changes like the bytes-like objects example, you have my full support.

But for the changes that modify identifier names, I think the both the old and the new versions are pretty bad. Example:

- . . . for some :exc:`SyntaxError`\ s.
+ . . . for some :exc:`SyntaxErrors <SyntaxError>`.

In Firefox, the new version renders as if it is talking about something literally called SyntaxErrors. It is only obvious that the exception is called SyntaxError when you hover the mouse, follow the link, etc.

I wonder if it would be better to find another way to write these kind of cases. E.g.:

* . . . for some syntax errors. [Just drop the link and markup.]
* . . . for some :exc:`SyntaxError` exceptions.

For cases like “eval()uated”, would it be acceptable changing to “evaluated with :func:`eval` ”?
msg265731 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-16 20:34
Thank you for your review Martin! Absolutely agreed with you about references to classes and exceptions. I have removed this from the next version of the patch. I left your idea about ":exc:`SyntaxError` exceptions" for other patch.

“evaluated with :func:`eval` ” looks tautologically to me. In hypertext we can avoid the repetition.
msg265746 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-05-17 01:48
It _would_ be nice to sort out the SyntaxErrors problem as well, but don’t let that stop fixing the easier problems. I would be interested in other people’s thoughts.

My problem with things like :func:`evaluated <eval>` is that the meaning is less clear, and it is not obvious what the hyperlink is for. If you print the sentence out, or casually look in a browser, there is not much indication that the function eval() is specified. Ugly as it is, “eval()uated” is more obvious.

Other options that I would be happier with, if you want to avoid the repeated “evaluated with eval()”, etc:

Level values are passed through :func:`eval`
list of channels waited with select() or poll()
The ``args`` entry, after passing through :func:`eval`
and :meth:`~Thread.join` cannot be called on them [dummy threads]
Module objects now support :mod:`weakref`.
msg265759 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-17 07:13
I think you make an accent on wrong thing. All these sentences look correct to me if remove any hyperlinks. Hyperlinks are optional. In the phrase "Level values are evaluated" the reference is to the term "evaluating", not to the eval() function. But since this term is not in glossary and is explained only in eval() description, the reference points to the eval() function. The same is for "weakly referencable" and "joining". It would be more correct ton add explicit labels "evaluating", "weak reference" and "join" and use they in references (":ref:`evaluated <evaluating>`"). This would create links without changing the style of the text.
msg265760 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-17 07:36
Georg, is it possible to refer to function without changing a style? Something like :ref:`evaluated <func:eval>`?
msg265767 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2016-05-17 15:34
Not really, no. You have to add a :ref: target label for the function. If it's only a few instances, that should be manageable.
msg265824 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-05-18 10:55
New changeset ef6d3a537cf5 by Serhiy Storchaka in branch '3.5':
Issue #27036: Fixed formatting references to "bytes-like object" in plural.
https://hg.python.org/cpython/rev/ef6d3a537cf5

New changeset d6b9a4c3f8ef by Serhiy Storchaka in branch 'default':
Issue #27036: Fixed formatting references to "bytes-like object" in plural.
https://hg.python.org/cpython/rev/d6b9a4c3f8ef
msg265826 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-05-18 11:14
Pushed a part about "bytes-like objects".

Here is a patch that adds explicit labels for referencing without changing the style.
History
Date User Action Args
2022-04-11 14:58:31adminsetgithub: 71223
2016-05-18 11:14:52serhiy.storchakasetfiles: + refs_forms3.patch

messages: + msg265826
2016-05-18 10:55:36python-devsetnosy: + python-dev
messages: + msg265824
2016-05-17 15:34:09georg.brandlsetmessages: + msg265767
2016-05-17 07:36:50serhiy.storchakasetmessages: + msg265760
2016-05-17 07:13:32serhiy.storchakasetmessages: + msg265759
2016-05-17 01:48:34martin.pantersetmessages: + msg265746
2016-05-16 20:34:35serhiy.storchakasetfiles: + refs_forms2.patch

messages: + msg265731
2016-05-16 09:32:20martin.pantersetnosy: + martin.panter
messages: + msg265688
2016-05-16 08:33:49serhiy.storchakacreate