Subject: Re: bug#37527: [PATCH] Install C source code for for debugging help

From: Paul Eggert <[email-masked]>
Date: Sun, 26 Jan 2020 01:00:34 -0800

On 1/24/20 11:58 PM, Eli Zaretskii wrote:

> Thanks, but the name of this variable gives no clue about the sources
> being installed as part of "make install", and neither does its
> documentation.  How about emacs-installed-source-directory?

We don't use 'installed-' in other names that have similar roles, e.g., 
'data-directory'. These variables and their uses don't care how the files got 
there, and their names and documentation should focus on what the variables are 
used for, not on the build process that set them up.

>> +Emacs installs a compressed copy of much of its source code, to make
> 
> "optionally installs", right?  This is an opt-in feature, right?

It's optional, but it's opt-out. I installed the attached patch, which changes 
the wording to "typically installs". I thought it pretty clear during the 
discussion that it would be opt-out; that's what my original patch proposed, 
anyway. I don't see why we'd want it to be opt-in.

>> +** The new variable 'emacs-source-directory' gives the Emacs source
>> +code location.
> 
> This should explain that this is a copy of the sources, different
> from the original source tree where Emacs was built.

Also done in the attached patch.

>>   (defvar find-function-C-source-directory
>> -  (let ((dir (expand-file-name "src" source-directory)))
>> -    (if (file-accessible-directory-p dir) dir))
>> +  (let ((dir (expand-file-name "src" emacs-source-directory)))
>> +    (if (file-accessible-directory-p dir) dir
>> +      (setq dir (expand-file-name "src" source-directory))
>> +      (if (file-accessible-directory-p dir) dir)))
> 
> This is backwards, IMO: it should first try the original source tree,
> and only next the installed sources.

The original source tree location is unreliable and is documented to be 
unreliable, whereas the installed sources are supposed to match the Emacs you're 
running and that is more useful for C-h f and friends. I'd rather try the 
reliable copy first.
>From d438f86698b69bd4a245724f7efcfa708d4b336f Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Sun, 26 Jan 2020 00:58:57 -0800
Subject: [PATCH] Improve doc for emacs-source-directory (Bug#36527).

---
 INSTALL  | 4 ++--
 etc/NEWS | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/INSTALL b/INSTALL
index cb12e4a17a..7a1b46872d 100644
--- a/INSTALL
+++ b/INSTALL
@@ -219,8 +219,8 @@ DEBUGGING AN INSTALLED EMACS
 
 * Installed Emacs source code
 
-Emacs installs a compressed copy of much of its source code, to make
-it easy for users to read the source code of Emacs via commands like
+Emacs typically installs a compressed copy of much of its source code,
+to make it easy for users to read Emacs source code via commands like
 M-x describe-function (C-h f) to display the definition of a function.
 This compressed copy ordinarily includes both the Elisp source code
 that Emacs is mostly written in, as well as the C source code for the
diff --git a/etc/NEWS b/etc/NEWS
index c3a71ade8a..276b8f46e8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -148,8 +148,9 @@ called when the function object is garbage-collected.  Use
 ** 'parse-time-string' can now parse ISO 8601 format strings,
 such as "2020-01-15T16:12:21-08:00".
 
-** The new variable 'emacs-source-directory' gives the Emacs source
-code location.
+** The new variable 'emacs-source-directory' gives the location of
+a copy of the Emacs source code, which is now typically installed as a
+set of compressed source-code files.
 
 
 * Changes in Emacs 28.1 on Non-Free Operating Systems
-- 
2.17.1