Re: Not using DOC for ELisp files

[Eli Zaretskii]

> 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.