[issue15580] fix True/False/None reST markup

R. David Murray added the comment: They should be capitalized and marked up as code if they refer to the objects. If they refer only to (to use bad english) the truthiness or falsiness of the value in question, then they should be lower case and not marked up as code. Quickly scanning the st

[issue15580] fix True/False/None reST markup

Zearin added the comment: I agree that globally linking all occurrences of True/False/None is overkill. Perhaps linking the first occurrence per webpage would be a good standard? However, I *strongly* believe that: 1. The words be capitalized 2. The words should be marked up as ``True``

[issue15580] fix True/False/None reST markup

Changes by Ezio Melotti : -- nosy: +ezio.melotti ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.py

[issue15580] fix True/False/None reST markup

R. David Murray added the comment: True. I disagree with the existing language, as I've indicated, but I'll leave it up to Georg as doc master. -- ___ Python tracker ___ __

[issue15580] fix True/False/None reST markup

Chris Jerdonek added the comment: It might be worth clarifying in the devguide then if True/False/etc shouldn't be treated differently from other things. The current wording suggests that links shouldn't be used at all in those cases (e.g. "given that they’re fundamental to the language and s

[issue15580] fix True/False/None reST markup

R. David Murray added the comment: Note, by the way, that I apply the same rule to most link markup. If I refer to, say, a module name in a paragraph or set of related paragraphs multiple times, I will typically only mark up the first occurrence as a :mod: link. It's not a hard and fast rule

[issue15580] fix True/False/None reST markup

R. David Murray added the comment: I prefer to have some of them be links and some of them be code markup. That is, I think there is value in having some of them be links. As Georg said, the devguide rule is more about it not being *necessary* to waste time marking them *all* up as constants

[issue15580] fix True/False/None reST markup

Zearin added the comment: I recently attempted to enhance the documentation in #17074. While I wasn’t linking all occurrences of True/False/None, I did mark them up as ``True``/``False``/``None``. Additionally, I made sure that these were (when appropriate) capitalized. I really disagree wi

[issue15580] fix True/False/None reST markup

Georg Brandl added the comment: We have to draw the line somewhere. Otherwise there will be dozens of issues like this, introducing potential breakage and costing developer time that can better be spent elsewhere. The rule in the devguide is mostly there so that developers don't bother writi

[issue15580] fix True/False/None reST markup

Chris Jerdonek added the comment: Yes, I can see the trade off. However, is there a sense in which the situation for documentation could be different from the situation for code? With code, style and refactoring changes cause churn without directly benefiting the end user (because code is jus

[issue15580] fix True/False/None reST markup

Georg Brandl added the comment: Agreed with David. -- nosy: +georg.brandl resolution: -> wont fix status: open -> closed ___ Python tracker ___ _

[issue15580] fix True/False/None reST markup

R. David Murray added the comment: I think changing these is unnecessary churn. Change them when you change surrounding text, just like we refrain from refactoring for PEP 8 compliance, etc, unless we are changing the code for other reasons. There is nothing *wrong* with these being links, i

[issue15580] fix True/False/None reST markup

Changes by Chris Jerdonek : -- stage: -> patch review versions: +Python 2.7, Python 3.2, Python 3.3 ___ Python tracker ___ ___ Python

[issue15580] fix True/False/None reST markup

Chris Jerdonek added the comment: Here is a command to find the file names of all occurrences: find Doc -type f -name *.rst | xargs grep -ERl ":const:\`(True|False|None)\`" The occurrences are in the following directories: Doc/c-api/ Doc/library/ Doc/reference/ Doc/whatsnew/ And here are comm

[issue15580] fix True/False/None reST markup

New submission from Chris Jerdonek: The Dev Guide says not to markup True, False, and None in the documentation in a way that generates a link (e.g. ":const:`True`") because "they’re fundamental to the language and should be known to any programmer": http://docs.python.org/devguide/documenting