Subject: Re: bug#59275: Unexpected return value of `string-collate-lessp' on Mac

From: Ihor Radchenko <[email-masked]>
Date: Thu, 24 Nov 2022 02:22:41 +0000

Eli Zaretskii <[email-masked]> writes:

>> Should we update the manual as well?
>> 4.5 Comparison of Characters and Strings section contains the old
>> docstring verbatim.
>
> I see in the manual text that is not a verbatim copy of the doc string, but
> an expanded version of it with more detailed explanations.  Which is how it
> should be: it is IMNSHO bad documentation-fu to have the manual just copycat
> the doc strings.  (We sometimes do it for lack of time, but it is not a Good
> Thing.)

Fair point.

> The note about case-sensitivity of the fallback was missing from the manual,
> so I added it.

Thanks!

>> P.S. I am wondering if there is some automated way to deal with verbatim
>> docstrings in the manuals. They are so easy to slip through when the
>> Elisp docstrings get updated.
>
> There should be no verbatim copies of doc strings in the manual.  So I'm not
> interested in making that bad practice easier ;-)

What about forgetting to update the manual when important changes are
made to the docstring? I know for certain that it happened many times
with Org manual. Maybe something can be done to auto-check if updates
were done to the docstring but not the manual?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>