bug#3888: Some variables get the wrong, platform-specific, documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: cyd@stupidchicken.com,  3888@emacsbugs.donarmstrong.com
> Date: Wed, 22 Jul 2009 14:32:49 -0400
> 
> A defvar can trivially be moved from Lisp to C.  I don't see any
> obstacle here.  As for functions, it's even easier since you can rename
> one of the two from `foo' to `foo-internal' or somesuch and move some
> code from one to the other.  We've already done such things for lote and
> lots of functions.  There's no technical problem here.

No technical problems, but experience teaches me that these solutions
don't hold in practice, i.e. new non-internal functions that overload
others pop up with time.

Also, the `foo-internal' trick does not solve the problem of the doc
string that needs to say something platform-specific without bothering
too much the users of other platforms.

Finally, there's (an admittedly very specific and quite rare) problem
of ls-lisp and its ilk that overload the default implementation with
something utterly different, and whose doc string _must_ be very
different if we want it to be useful.

I tried to think of an infrastructure that would solve all these
use-cases in a relatively elegant way that would not become a
maintenance burden.