[issue27036] Mark up of references in different form

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

Pushed a part about "bytes-like objects".

Here is a patch that adds explicit labels for referencing without changing the 
style.

--
Added file: http://bugs.python.org/file42890/refs_forms3.patch

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Georg Brandl]

Georg Brandl added the comment:

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.

--

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

Georg, is it possible to refer to function without changing a style? Something 
like :ref:`evaluated `?

--

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

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 `"). This would create links without 
changing the style of the text.

--

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Martin Panter]

Martin Panter added the comment:

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 ` 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`.

--

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Serhiy Storchaka]

Serhiy Storchaka added the comment:

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.

--
Added file: http://bugs.python.org/file42877/refs_forms2.patch

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Martin Panter]

Martin Panter added the comment:

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 `.

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` ”?

--
nosy: +martin.panter

___
Python tracker 

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

[issue27036] Mark up of references in different form

[Serhiy Storchaka]

New submission from Serhiy Storchaka:

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

--
assignee: docs@python
components: Documentation
files: refs_forms.patch
keywords: patch
messages: 265686
nosy: docs@python, georg.brandl, serhiy.storchaka
priority: normal
severity: normal
stage: patch review
status: open
title: Mark up of references in different form
type: enhancement
versions: Python 2.7, Python 3.5, Python 3.6
Added file: http://bugs.python.org/file42869/refs_forms.patch

___
Python tracker 

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