[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate

[Tony R.]

Tony R. added the comment:

> Here are the original descriptions of the old LaTeX version.

Holy crap!  You all used to use LaTeX?!  :D  

(I know--LaTeX is still going strong in academia.  I just had no idea it was ever part of Python’s documentation, except as an output format.)

> Adding a parameter is explicitly a "versionchanged" kind of change.
> 
> Since the Sphinx items are supposed to be equivalent, this has always been the intention, even if the current devguide deviates.

Ah, okay.  

Well then, if this is the sort of place where the status quo is sacred, then there is nothing more to discuss.  

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.

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.  

If it’s not obvious by now, I feel strongly about good semantic markup.  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.

If you’re reading this, and you feel similarly--speak up!  

What do you think?


Respectfully,

—Tony

----------

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