Documentation?

[Thomas Dickey]

On Thu, 9 Apr 2009, Bill Crawford wrote:

>
> On 04/08/2009 05:00 PM, Thomas Dickey wrote:
> ...
>>>>>> If only the latest release is "API-stable", by definition it's not
>>>>>> stable.
>
> On Wed, Apr 08, 2009 at 05:34:48PM -0400, Behdad Esfahbod wrote:
> ...
>>> This cannot be deduced from that line.  You need to review your math.
>
> On Wednesday 08 April 2009 22:52:12 Thomas Dickey wrote:
>
>> Behdad's comment doesn't make sense in English.
>>
>> (Perhaps someone can help Behdad with that - or else explain to him
>> what "API-stable" might mean).
>
> It makes perfect sense. He's saying that (f(A) ⊢ g(B)) ⊬ (¬f(A) ⊢ ¬g(B)), where
> A is "release", f is "latest", B is "API" and g is "stable" ;o)
>
> The point is not that it has to be the "latest" release to be "stable", the
> point is that it needs to be an actual release, because between those, they
> might experiment with things and change them before release, and you don't want
> to depend on any temporary change that might be withdrawn rapidly. Over the
> longer term, sure, things get deprecated, but it's to be hoped that over quite
> a long period of time.
>
> At least, I *think* that's what he said.

He might have.  His response doesn't contain any useful information.

In the context of the remark that I was curious about, I'd have
understood "API-stable" to mean that no further changes will be made in 
the API which would require recompilation.  Regarding the latest-releases 
tie-in on the web-page, that's problematic since it's only the portion of 
the API which has been unchanging for an extended period of time that 
would be (in the normal sense of the word) "stable".

I suppose that someone with time to spare could compare the successive 
releases of cairo and measure the fraction of the API which is actually
stable.  (If there's some evidence of this in the source code itself,
we might want to discuss that).

-- 
Thomas E. Dickey
http://invisible-island.net
ftp://invisible-island.net