Fred L. Drake, Jr. added the comment: On Fri, Feb 19, 2016 at 10:02 AM, Tony R. <rep...@bugs.python.org> wrote: > Holy crap! You all used to use LaTeX?! :D
Python's documentation has a long & colorful history. :-) > Well then, if this is the sort of place where the status quo is sacred, then > there is nothing more to discuss. Status quo is not sacred, but does have some value. Changing how busy people do things is non-trivial. > But if anyone reading this is open to the idea, please re-read my previous > comment in this thread. The quoted LaTeX docs are clear, but I still > believe my “all changes = (deprecated-removed changes) + (added > changes) + (other changes)” interpretation makes more sense than the > LaTeX definition. > > I also think it is more helpful to the *reader*--which, I respectfully > suggest, > should be the basis for any documentation’s guidelines--by marking up > changes according to this grouping. I think we all agree that the documentation is for the reader. > It’s not my desire to be troublesome by making one more appeal. > I simply want to point out that just because somebody wrote the > LaTeX definitions a long time ago doesn’t mean that we cannot > rewrite them. They were written by somebody just like us, after all. As the person who wrote them, I don't consider them sacred or unchangeable. Having some rational basis for whatever we use is good, and it should be clearly documented clearly. > If it’s not obvious by now, I feel strongly about good semantic markup. We're on the same page here. > The purpose of semantic markup is to describe what something *is*. > I just think that changes form a hierarchy, with a generic “change” as > something of the base class, and “deprecated”, “removed”, and “added” > as specializations. Again, agreed. That doesn't imply that the specializations encompass all changes, though. For some, 'versionchanged' is reasonable. Part of the problem is getting the granularity right. The initial intent was that 'version*' were annotations for the enclosing object (function, class, method, etc.). If we want to have something more granular (parameter added / deprecated / whatever), we should have distinct markup for that. That could look something like: .. parameteradded:: alternate 3.6 Further explanation goes here. It's helpful to think of these annotations as pronouns; the antecedent needs to be clear before they can be interpreted correctly. It sounds like that needs to be clarified in the documentation, and possibly provision added for a more fine-grained form of annotation. -Fred ---------- nosy: +fdrake title: Use “.. versionadded” over “.. versionchanged” where appropriate -> Use “.. versionadded” over “.. versionchanged” where appropriate _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue26366> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com