Fred L. Drake, Jr. added the comment:
On Fri, Feb 19, 2016 at 10:02 AM, Tony R. <[email protected]> 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 <[email protected]>
<http://bugs.python.org/issue26366>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
