GNU bug report logs - #66554
[PATCH] Add the public API of Compat to the core

Previous Next

Full log

View this message in rfc822 format

From: Philip Kaludercic <philipk <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mail <at> daniel-mendler.de, stefankangas <at> gmail.com, monnier <at> iro.umontreal.ca, 66554 <at> debbugs.gnu.org
Subject: bug#66554: [PATCH] Add the public API of Compat to the core
Date: Sat, 10 Feb 2024 16:29:00 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Philip Kaludercic <philipk <at> posteo.net>
>> Cc: mail <at> daniel-mendler.de,  66554 <at> debbugs.gnu.org,  stefankangas <at> gmail.com,
>>   monnier <at> iro.umontreal.ca
>> Date: Thu, 08 Feb 2024 07:40:23 +0000
>> 
>> Eli Zaretskii <eliz <at> gnu.org> writes:
>> 
>> >> Daniel, do have any ideas how to improve the documentation here?  It
>> >> seems to me that the authoritative source of information on what
>> >> functions to compat-call is Compat itself, right?
>> >
>> > What does Compat manual say about this aspect?
>> 
>> --8<---------------cut here---------------start------------->8---
>> Note that Compat provides replacement functions with extended
>> functionality for functions that are already defined (@code{sort},
>> @code{assoc}, @dots{}).  These functions may have changed their
>> calling convention (additional optional arguments) or may have changed
>> their behavior.  These functions must be looked up explicitly with
>> @code{compat-function} or called explicitly with @code{compat-call}.
>> We call them ``Extended Definitions''.  In contrast, newly ``Added
>> Definitions'' can be called as usual.
>
> Thanks.  I suggest to copy the above paragraph to the ELisp reference
> manual, 

OK, can do.

>         and add a cross-reference to the Compat manual after it.

IIUC the cross-reference will be broken, unless the user has installed
Compat manually.  Moreover, if I am not mistaken, the documentation
bundled with the Compat package might not be loaded at all, if the
package isn't activated due to the versioning trick.  I'd add a link to
the HTML manual, rendered on elpa.gnu.org, but I don't know if this is
conventional.

> Btw, whenever you introduce terminology in our manuals, as in
> ``Extended Definitions'' above, it is best to use the @dfn markup
> instead of literal quotes: the results look better in HTML and printed
> output formats.

Ok.

-- 
Philip Kaludercic

Previous Next

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