Message260525
> 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.
Isn’t language fun?!?! *insane smile* 8)
> It sounds
> like that needs to be clarified in the documentation, and possibly
> provision added for a more fine-grained form of annotation.
Okay. I can participate in the discussion of that, if it would help...but adding a completely new annotation type is outside my current ability to contribute.
----
> > Well then, if this is the sort of place where the status quo is sacred,
> > then there is nothing more to discuss.
>
> That wasn't my intention when quoting the old documenting guide, it was just
> to show what the intent was (and still is), and that I didn't just invent it.
Your intent was clear to me! I did not mean to say that you -- or anyone -- just invented it.
I only know that mature projects (like Python) tend to hold more strongly to the status quo, and that I was advocating a change that was probably going to be an uphill battle to convince others as worthwhile.
> That's a nice strawman -- we all feel semantic markup is important, and we
> are talking about nothing but semantic markup here. We're just discussing
> the interpretation of one aspect of the semantics.
It was not my wish to set up a strawman. (I have no formal training in logic, anyways; I’d probably screw it up if I deliberately tried!)
The reason I was stressing semantic markup is because I anticipated resistance from the mindset of “Ugh, I don’t want to deal with this tedious crap!” I wanted to emphasize semantic markup as something valuable -- worth making an effort for, even if it might appear tedious or trivial at first glance.
----
That said, I think it’s time for me to bow out of this conversation. I’ve never made a successful contribution to any part of Python, including the documentation. There was some talk of updating the devguide or adding new annotations, so I hope that something good comes out of that! But the issue patch is where my comfort level is right now, and it appears that it’s a no-go.
Thank you for your time, your consideration, and the discussion!
—Tony |
|
Date |
User |
Action |
Args |
2016-02-19 17:21:05 | Tony R. | set | recipients:
+ Tony R., fdrake, georg.brandl, ezio.melotti, docs@python, berker.peksag, martin.panter |
2016-02-19 17:21:05 | Tony R. | set | messageid: <1455902465.65.0.490056045558.issue26366@psf.upfronthosting.co.za> |
2016-02-19 17:21:05 | Tony R. | link | issue26366 messages |
2016-02-19 17:21:05 | Tony R. | create | |
|