From: Eli Zaretskii <eliz@gnu.org>
To: Stefan Monnier <monnier@iro.umontreal.ca>
Cc: emacs-devel@gnu.org, akrl@sdf.org
Subject: Re: Not using DOC for ELisp files
Date: Thu, 30 Dec 2021 09:20:57 +0200 [thread overview]
Message-ID: <83sfuaimna.fsf@gnu.org> (raw)
In-Reply-To: <jwv7dbn57qq.fsf-monnier+emacs@gnu.org> (message from Stefan Monnier on Wed, 29 Dec 2021 18:23:32 -0500)
> From: Stefan Monnier <monnier@iro.umontreal.ca>
> 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.
next prev parent reply other threads:[~2021-12-30 7:20 UTC|newest]
Thread overview: 31+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-28 1:48 Not using DOC for ELisp files Stefan Monnier
2021-12-28 2:25 ` Po Lu
2021-12-28 3:48 ` Stefan Kangas
2021-12-28 5:39 ` Po Lu
2021-12-28 4:11 ` LdBeth
2021-12-28 5:03 ` Stefan Monnier
2021-12-28 5:38 ` Po Lu
2021-12-28 9:52 ` Phil Sainty
2021-12-28 10:31 ` Po Lu
2021-12-28 12:47 ` Po Lu
2021-12-28 7:10 ` Lars Ingebrigtsen
2021-12-28 3:39 ` Stefan Kangas
2021-12-28 5:10 ` Stefan Monnier
2021-12-28 6:56 ` Lars Ingebrigtsen
2021-12-28 12:44 ` Eli Zaretskii
2021-12-28 17:14 ` Stefan Monnier
2021-12-28 18:17 ` Eli Zaretskii
2021-12-29 0:15 ` Stefan Monnier
2021-12-29 12:30 ` Johann Klähn
2021-12-29 23:08 ` Stefan Monnier
2021-12-29 12:52 ` Eli Zaretskii
2021-12-29 23:23 ` Stefan Monnier
2021-12-30 7:20 ` Eli Zaretskii [this message]
2021-12-31 4:19 ` Stefan Monnier
2021-12-31 8:57 ` Eli Zaretskii
2021-12-31 16:16 ` Stefan Monnier
2021-12-31 18:45 ` Eli Zaretskii
2022-01-03 13:48 ` Ken Raeburn
2022-01-03 14:30 ` Eli Zaretskii
2022-01-07 22:59 ` Ken Raeburn
2022-01-08 7:08 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83sfuaimna.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=akrl@sdf.org \
--cc=emacs-devel@gnu.org \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.