[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.html#documenting Rather, it says to use "``True``" (and similarly for False and None): This issue is to update the documentation to conform to this guidance. While working on the documentation, I noticed many occurrences of ":const:`True`", for example. See here for some examples, where you can see the hyperlinks: http://docs.python.org/dev/library/tarfile.html#tarfile.TarFile.add ---------- assignee: docs@python components: Documentation messages: 167648 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: fix True/False/None reST markup _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 commands to do the replacement on a branch. # Replace the occurrences inside tables, to preserve table alignment. find Doc/c-api/ Doc/library/ Doc/reference/ -type f -name *.rst | \ xargs sed -i '' \ -e 's/\(\|.*\):const:`True`/\1``True`` /g' \ -e 's/\(\|.*\):const:`False`/\1``False`` /g' \ -e 's/\(\|.*\):const:`None`/\1``None`` /g' # Replace the rest of the occurrences. find Doc/c-api/ Doc/library/ Doc/reference/ -type f -name *.rst | \ xargs sed -i '' \ -e 's/:const:`True`/``True``/g' \ -e 's/:const:`False`/``False``/g' \ -e 's/:const:`None`/``None``/g' I left out Doc/whatsnew/ because the What's New is historical and because it includes entries describing the introduction of True/False, which may be considered special. Incidentally, the constants documentation of True/False/None link to the descriptions using ":data:`True`", etc, so they are not affected by this change: http://docs.python.org/dev/library/constants.html#built-in-constants To commit, the commands above could be run on a branch and committed, then merged forward to newer branches, and then the scripts re-run on the next newer branch to catch new introductions of True/False/None, and so on. For illustration purposes only, I'm attaching the patch that results from running the script on the default branch. ---------- keywords: +patch Added file: http://bugs.python.org/file26723/script-result-default-branch.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
Changes by Chris Jerdonek <chris.jerdonek@gmail.com>: ---------- stage: -> patch review versions: +Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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, it just isn't necessary. ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
Georg Brandl added the comment: Agreed with David. ---------- nosy: +georg.brandl resolution: -> wont fix status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 just a means and not the end). We can hold off on refactoring without impacting the end user. With documentation though, these are visible, albeit small changes that will directly improve the user's experience. We would be holding off on improving the pages for the sake of internal churn. (If it was refactoring reST in a way that didn't change the HTML output, it would be a different story.) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 writing more than they have to (since None/True/False occur so often typing the link every time will feel painful after a few times). If the link is already written, it does absolutely no harm, as David said. Therefore, there is no actual improvement as you claim. This is nothing against you and your efforts, Chris -- you've already helped improve the docs quite a lot. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 with the refusal to accept this issue. Python is represented to the outside world through its documentation. As it is, there are inconsistencies in the capitalization and markup of constants. CONSTANTS! This isn’t exactly a nuanced part of the language. Constants are dead-easy to spot, and they’re dead-easy to fix. This issue is **low-hanging fruit**. **Consistency** is also one of Python’s core values. This is built right into the language itself --- as indentation-based scope. The patch by chris.jerdonek helps make the documentation more consistent. I could understand if this isn’t the type of work you like doing. If the inconsistency was identified, but no one was willing to do the work, **then** this might be considered an issue which “cost[...] developer time that can better be spent elsewhere.” But that’s not the case. Chris has already done the work. It’s low-hanging fruit, it improves Python’s image to the outside world, and it noticeably improves the readability (and usability) of the documentation. **Please** reconsider accepting this patch. ---------- nosy: +zearin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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. Having some of them marked up as constants will be enough to lead a newbie to the documentation for them. When writing new docs, I will typically mark them up as constants once or twice in the new docs, and make the remainder code markup. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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, though: I go by feel as to what level of link markup seems appropriate. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 should be known to any programmer"). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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``, ``False``, or ``None`` Of course, these two items only apply when appropriate. But after attempting this myself in #17074, I can say with certainty that this is the case *most of the time*. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
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 start of the patch in 17074, about half the changes to true/false markup were incorrect. Ideally we should never have True unless it is marked up as ``True`` (same for False), but there are *many* cases in the docs where true or false is correct. My guess would be that those cases outnumber the cases where ``True`` or ``False`` is correct, but I haven't tried to measure :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15580> _______________________________________
participants (5)
-
Chris Jerdonek -
Ezio Melotti
-
Georg Brandl
-
R. David Murray
-
Zearin