Re: Not using DOC for ELisp files

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Andrea Corallo <akrl@sdf.org>,  emacs-devel@gnu.org
> Date: Tue, 28 Dec 2021 19:15:11 -0500
> 
> Seeing how I haven't heard any opposition to the idea, I fixed a few
> loose ends, and I think it's now ready.  See below.
> Any objection?

This seems to do much more than just what you said, even if I include
the obvious cleanups, like unnecessary variables and support code no
longer required.  Are all the changes really necessary/derived, or did
you take the chance to make some additional changes, which should
perhaps be discussed separately?

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

Moreover, the text about load-path is now completely gone, and that is
a net loss, I think.

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

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

> ++++
> +** New variable 'lisp-directory' holds the directory of Emacs's own Lisp files.

This suffers from the same accuracy problems.

> +(defvar lisp-directory nil
> +  "Directory containing the Lisp files that come with GNU Emacs.")

Likewise.  Actually, "files that come with GNU Emacs" is even worse in
its ambiguity than "bundled".

And why isn't the main part of the change called out in NEWS?  I think
this is something we should announce.

Thanks.