GNU bug report logs - #59275
Unexpected return value of `string-collate-lessp' on Mac

Previous Next

Full log

Message #49 received at 59275 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59275 <at> debbugs.gnu.org
Subject: Re: bug#59275: Unexpected return value of `string-collate-lessp' on
 Mac
Date: Thu, 24 Nov 2022 02:22:41 +0000

Eli Zaretskii <eliz <at> gnu.org> 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>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.