unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Eli Zaretskii <eliz@gnu.org>
To: Alan Mackenzie <acm@muc.de>
Cc: emacs-devel@gnu.org
Subject: Re: How does one find out what file a library has been loaded from?
Date: Thu, 21 Jul 2022 09:13:03 +0300	[thread overview]
Message-ID: <83mtd3ngcw.fsf@gnu.org> (raw)
In-Reply-To: <YthmvWi7lIFfGAGR@ACM> (message from Alan Mackenzie on Wed, 20 Jul 2022 20:34:05 +0000)

> Date: Wed, 20 Jul 2022 20:34:05 +0000
> Cc: emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> Here's a first preliminary effort at amending loading.texi:

Thanks, but in "needs work"(TM).

>  @defun symbol-file symbol &optional type
> -This function returns the name of the file that defined @var{symbol}.
> -If @var{type} is @code{nil}, then any kind of definition is acceptable.
> -If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that
> -specifies function definition, variable definition, or face definition
> -only.
> +This function returns a file name associated with the file that
> +defined @var{symbol} (@pxref{eln files}).  If @var{type} is
> +@code{nil}, then any kind of definition is acceptable.  If @var{type}
> +is @code{defun}, @code{defvar}, or @code{defface}, that specifies
> +function definition, variable definition, or face definition only.

This change is for the worse: it introduces a vague and confusing
notion of "file name associated with the file that defines" a symbol.
This should be removed from the patch, as it doesn't add any useful
information, just muddies the waters.

>  @defvar load-history
> -The value of this variable is an alist that associates the names of
> -loaded library files with the names of the functions and variables
> -they defined, as well as the features they provided or required.
> +The value of this variable is an alist that associates names
> +associated with loaded library files (@pxref{eln files}) with the
> +names of the functions and variables the files defined, as well as the
> +features they provided or required.

Likewise.

>  Each element in this alist describes one loaded library (including
>  libraries that are preloaded at startup).  It is a list whose @sc{car}
> -is the absolute file name of the library (a string).  The rest of the
> -list elements have these forms:
> +is an absolute file name associated with the library (a string)
> +(@pxref{eln files}).  The rest of the list elements have these forms:

Likewise.

> -  The command @code{eval-region} updates @code{load-history}, but does so
> -by adding the symbols defined to the element for the file being visited,
> -rather than replacing that element.  @xref{Eval}.
> +@anchor{eln files} For backwards compatibility, @code{load-history}
> +stores and @code{symbol-file} returns the name of a notional byte
> +compiled @file{.elc} file in the same directory as its source file
> +when the real file loaded from is a natively compiled file elsewhere.
> +This @file{.elc} file may or may not actually exist.  For other files,
> +their absolute file names are used.

This last sentence is "out of the blue": what "other files"?  The text
should also have a cross-reference to where native compilation is
described in the manual.

>                                        If you want to find the actual
> +file loaded from, and you suspect if may really be a native compiled
> +file, something like the following should help.  You need to know the
> +name of a function which hasn't been advised, say @var{foo}, defined
> +in the suspected native compiled file.  Then
> +
> +@lisp
> +(let ((foo-fun (symbol-function #'FOO)))
> +       (and foo-fun (subr-native-elisp-p foo-fun)
> +            (native-comp-unit-file (subr-native-comp-unit foo-fun))))
> +@end lisp
> +
> +@noindent
> +will return either the name of the native compiled file defining
> +@var{foo}, or @code{nil} if there is no such file.

This is not a good way of documenting some technique in this manual.
The way we describe such stuff is by documenting the functions a
program needs to use, not by giving a random example which calls the
functions without any documentation of the functions themselves.

Also, native-comp-unit-file doesn't exist in a build without native
compilation support, so some feature test is missing.

Finally, "FOO" is not how we refer to a meta-syntactic variable in the
manual: we use @var{foo} instead.

> +The command @code{eval-region} updates @code{load-history}, but does
> +so by adding the symbols defined to the element for the file being
> +visited, rather than replacing that element.  @xref{Eval}.

This part should be before the text which explains the issues with
loading *.eln files.



  reply	other threads:[~2022-07-21  6:13 UTC|newest]

Thread overview: 43+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-07-19 10:52 How does one find out what file a library has been loaded from? Alan Mackenzie
2022-07-19 12:39 ` Eli Zaretskii
2022-07-19 15:01   ` Alan Mackenzie
2022-07-19 15:32     ` Andrea Corallo
2022-07-24 16:07       ` Eli Zaretskii
2022-07-24 17:46         ` Andrea Corallo
2022-07-31 12:52           ` Eli Zaretskii
2022-08-01  9:23             ` Andrea Corallo
2022-08-02  8:43               ` Andrea Corallo
2022-08-02 12:12                 ` Eli Zaretskii
2022-08-02 14:13                   ` Andrea Corallo
2022-08-03 14:19                     ` Eli Zaretskii
2022-08-01 19:31             ` Alan Mackenzie
2022-08-03 14:16               ` Eli Zaretskii
2022-07-19 15:50     ` Eli Zaretskii
2022-07-19 17:07       ` Alan Mackenzie
2022-07-19 19:13         ` Eli Zaretskii
2022-07-20 11:47           ` Alan Mackenzie
2022-07-20 15:31             ` Stefan Monnier
2022-07-20 20:34             ` Alan Mackenzie
2022-07-21  6:13               ` Eli Zaretskii [this message]
2022-07-21 17:37                 ` Alan Mackenzie
2022-07-21 17:52                   ` Stefan Monnier
2022-07-21 18:24                     ` Alan Mackenzie
2022-07-21 18:37                       ` Stefan Monnier
2022-07-21 21:03                         ` Alan Mackenzie
2022-07-21 23:15                           ` Stefan Monnier
2022-07-21 17:53                   ` Eli Zaretskii
2022-07-21 20:39                     ` Alan Mackenzie
2022-07-23 10:11                       ` Eli Zaretskii
2022-07-24 11:27                         ` Alan Mackenzie
2022-07-24 12:16                           ` Eli Zaretskii
2022-07-24 15:37                             ` Eli Zaretskii
2022-07-24 15:42                               ` Eli Zaretskii
2022-07-24 15:32                           ` Stefan Monnier
2022-07-24 15:49                             ` T.V Raman
2022-07-24 16:11                               ` Stefan Monnier
2022-07-24 18:21                                 ` T.V Raman
2022-07-24 18:50                                   ` Stefan Monnier
2022-07-24 16:19                               ` Eli Zaretskii
2022-07-19 16:27     ` Stefan Monnier
2022-07-20 18:36       ` Andrea Corallo
2022-07-21  7:20         ` 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

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=83mtd3ngcw.fsf@gnu.org \
    --to=eliz@gnu.org \
    --cc=acm@muc.de \
    --cc=emacs-devel@gnu.org \
    /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 public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).