[docs] [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 <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` ”?

----------
nosy: +martin.panter

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27036>
_______________________________________