Re: Docstrings and manuals

[Dmitry Gutov]

On 04/17/2016 02:16 PM, Michael Albinus wrote:

> No primary or secondary. If docstring and manual are inconsistent, it is
> a bug which must be fixed.

What's "inconsistent" in this case? They are almost always different.

> There is no automatism that the docstring is
> always right, and the manual is wrong in this case. It could be also
> vice versa.

Wouldn't it be better if we had this "automatism"?

> See also the Elisp Manual (info "(elisp)Caveats")
>
> --8<---------------cut here---------------start------------->8---
>    The manual should be fully correct in what it does cover, and it is
> therefore open to criticism on anything it says—from specific examples
> and descriptive text, to the ordering of chapters and sections.  If
> something is confusing, or you find that you have to look at the sources
> or experiment to learn something not covered in the manual, then perhaps
> the manual should be fixed.  Please let us know.
> --8<---------------cut here---------------end--------------->8---

I'm not arguing in favor of leaving mistakes in the manual. But I think 
it should be strictly a derivative work. I.e. the docstrings must 
contain the complete information (if maybe presented in a terse 
fashion), and the manual could rephrase that, only to make it more 
accessible (but not more informative).