Re: perl customization interface stability

[Patrice Dumas]

On Thu, Aug 23, 2012 at 06:53:51PM +0000, Karl Berry wrote:
>      @chapter @command{texi2any} Output Customization
> 
>     address@hidden
>     address@hidden Warning
>     +The information displayed here is likely to change in the future.
>     +In particular, the functions and their behavior may change in any
>     +Texinfo release. 
>     address@hidden quotation
>     address@hidden cartouche
> 
> Must we shout this so loudly?  There are hardly any functions described
> in the following -- set_from_init_file, get_conf, and gdt are all I saw
> at a glance.  Can't we call those "stable"?  What is it that's "likely
> to change"?

I really fear that when devising the API I find that those functions do
not make sense or their name is very inaccurate.  For instance, for the
get_conf function there is an issue, because it is different when used
from the main program (ie from texi2any) and from a converter, as both
have a different view of the customization variables that are set.

The wording may be too strong, instead of 'is likely', 'may' may be
better.  But I really want to avoid both breaking user expectations or
be forced to use a suboptimal API, and I would really like not to be
forced to use a suboptimal API , I'd say at all cost.

> Besides, the intro text to that chapter mentions many more things which
> we intentionally aren't documenting yet because they're not "stable".
> So if we say that what *is* in the manual now isn't stable either
> .. well, I don't get it.

Maybe what could be better, instead of saying that the
interface/names/whatever may change, to say that they are experimental.
That way the idea would be 'they are not stable for now but will be in
the future'.  Would you prefer that?

-- 
Pat