From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Not using DOC for ELisp files Date: Thu, 30 Dec 2021 09:20:57 +0200 Message-ID: <83sfuaimna.fsf@gnu.org> References: <834k6snbko.fsf@gnu.org> <83fsqclhlh.fsf@gnu.org> <838rw3lgiu.fsf@gnu.org> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="30248"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org, akrl@sdf.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Dec 30 08:23:20 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1n2pmS-0007gp-4r for ged-emacs-devel@m.gmane-mx.org; Thu, 30 Dec 2021 08:23:20 +0100 Original-Received: from localhost ([::1]:48300 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n2pmQ-00034V-MY for ged-emacs-devel@m.gmane-mx.org; Thu, 30 Dec 2021 02:23:18 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:51024) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n2pk9-0002K2-3w for emacs-devel@gnu.org; Thu, 30 Dec 2021 02:20:58 -0500 Original-Received: from [2001:470:142:3::e] (port=36672 helo=fencepost.gnu.org) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n2pk7-0004JX-1q; Thu, 30 Dec 2021 02:20:55 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=lVZvdsez6aFr6iQkGLF/gobBlgYTmrIZNdvh5OYGPx4=; b=T7yX8Du9RXww OE+wV1E6gB2qyeFaIs2zsMZ1KfDFvMr53anKXV6QrVukK/jV689DZZo+BXQU2Af3VzIQQDafPgZIy ixeaP6Nrqyqw2IggZhu6pFlIJXBaWJgdcm01FjP50dgzHEq8RjkTQiDB3i1kDfHQS/SvS4WWmSfwI e8xcC5HL13Y8Efwy2ccKLvEZ82501xCjhZbdNJyDcRj+qvOsGdYRylYjK/3yGsbRzHejD1lGO+43N lB5SwjnlunBPJj/rCtIWr5FNVmDQHwamQT2De3fzhudoNi4y3pGESjRZRjFhsV1QI305Io5Z9r0gE 4CcfFoVtLdeczw7IYR1hQA==; Original-Received: from [87.69.77.57] (port=3070 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n2pk4-0004Pi-86; Thu, 30 Dec 2021 02:20:54 -0500 In-Reply-To: (message from Stefan Monnier on Wed, 29 Dec 2021 18:23:32 -0500) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:283622 Archived-At: > From: Stefan Monnier > Cc: akrl@sdf.org, emacs-devel@gnu.org > Date: Wed, 29 Dec 2021 18:23:32 -0500 > > >> When Emacs starts up, it sets up the value of @code{load-path} > >> -in several steps. First, it initializes @code{load-path} using > >> -default locations set when Emacs was compiled. Normally, this > >> -is a directory something like > >> +in several steps. First, it initializes @code{lisp-directory} using > >> +default locations set when Emacs was compiled. > > You used for lisp-directory the same words as we used for load-path, > > but is that the correct description? > > Good question. I think it should (as in, any difference is likely > a sign of a bug), tho I haven't looked closely at the code to see if the > code matches this expectation. load-path is a list, whereas lisp-directory is a single directory. So we could describe the latter much more accurately. > > Looking at the code that computes the value of lisp-directory, I don't > > think so, I think you can say something much more accurate and > > explicit about lisp-directory. > > Don't know what that would look like. Some text which says what its value should be, or where it should point. > > Moreover, the text about load-path is now completely gone, and that is > > a net loss, I think. > > I don't see it being gone. But yes, I'm not super happy with the text > I have. I already rewrote it three times before the version you saw. > I'd appreciate some help with it. I'm trying to help ;-) If you need more specific help, please show the text you'd like to improve and tell why you are unhappy with it, and I will try to help more. > >> +@defvar lisp-directory > >> +Name of the directory holding Emacs's bundled Lisp files. > > This is not accurate enough, given that it could mean both the place > > where Emacs was built (the "bundled" part can be interpreted that > > way), the place where *.el and *.elc files are installed when the > > built Emacs is being installed, and the place where the *.eln files > > are installed. > > Hmm.. not sure how to avoid those problems: mentioning what it is not > would seem to muddy the waters even further. Why not say that it points to where the *.el and *.elc files are installed in the Emacs installation tree? > >> +Normally, this is a directory something like > >> @example > >> "/usr/local/share/emacs/@var{version}/lisp" > >> @end example > > This should tell what does @var{version} stand for. > > (apparently like the author of that chunk) I don't see why that > would be necessary. I beg to disagree. We always describe every @var meta-syntactic variable in our docs. It takes just one short sentence to do that in this case. > > Likewise. Actually, "files that come with GNU Emacs" is even worse in > > its ambiguity than "bundled". > > Any suggestion for a better wording? See above: mention the installation tree and the files in that directory explicitly. > > And why isn't the main part of the change called out in NEWS? > > I think this is something we should announce. > > AFAIK it's invisible to the end user, so I think it isn't worth > mentioning there. NEWS are not just for users, they are also for Lisp programmers. We have specialized sections there for that very reason.