master eab422a653 2/2: Merge branch 'master' of git.sv.gnu.org:/srv/git/emacs

[Po Lu]

branch: master
commit eab422a6532899468a70ec44986c1ee5174287b7
Merge: d1fde0ab8a 95ee6e8b90
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Merge branch 'master' of git.sv.gnu.org:/srv/git/emacs
---
 doc/lispref/loading.texi | 58 +++++++++++++++++--------------
 etc/NEWS                 |  6 ++--
 lisp/startup.el          |  2 +-
 lisp/xwidget.el          | 88 ++++++++++++++++++++++++++++--------------------
 4 files changed, 88 insertions(+), 66 deletions(-)

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index 3efcf055dc..070f763db8 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -293,30 +293,33 @@ directory).
 
   When Emacs starts up, it sets up the value of @code{load-path} in
 several steps.  First, it looks for the directory containing its own
-Lisp files, using default locations set when Emacs was compiled.
-It saves this directory in @code{lisp-directory}.  Normally, this
-is a directory something like
+Lisp files, using default locations set when Emacs was compiled.  It
+saves this directory in @code{lisp-directory}.  Normally, this is a
+directory where the @file{*.elc} files are installed, something like
 
 @example
 "/usr/local/share/emacs/@var{version}/lisp"
 @end example
 
-(In this and the following examples, replace @file{/usr/local} with
-the installation prefix appropriate for your Emacs.)
-These directories contain the standard Lisp files that come with
-Emacs.  If Emacs cannot find them, it will not start correctly.
+@noindent
+where @var{version} is the Emacs version.  (In this and the following
+examples, replace @file{/usr/local} with the prefix appropriate for
+your Emacs installation.)  This directory and its subdirectories
+contain the standard Lisp files that come with Emacs.  If Emacs cannot
+find its own Lisp files, it will not start correctly.
 
 If you run Emacs from the directory where it was built---that is, an
-executable that has not been formally installed---Emacs instead
-initializes @code{lisp-directory} using the @file{lisp}
-directory in the directory containing the sources from which it
-was built.
+executable that has not been installed yet---Emacs instead initializes
+@code{lisp-directory} using the @file{lisp} subdirectory of the
+directory containing the sources from which it was built.
 
-Emacs first initializes @code{load-path} with this @code{lisp-directory}.
+Emacs then initializes @code{load-path} with this @code{lisp-directory}.
 @c Though there should be no *.el files in builddir/lisp, so it's pointless.
 If you built Emacs in a separate directory from the
-sources, it also adds the lisp directories from the build directory.
-(In all cases, elements are represented as absolute file names.)
+sources, it also adds the @file{lisp} subdirectory of the build directory.
+
+All of these directories are stored in the above two variables as
+absolute file names.
 
 @cindex site-lisp directories
 Unless you start Emacs with the @option{--no-site-lisp} option,
@@ -336,12 +339,12 @@ and
 @end example
 
 @noindent
-The first one is for locally installed files for a specific Emacs
-version; the second is for locally installed files meant for use
-with all installed Emacs versions.  (If Emacs is running uninstalled,
-it also adds @file{site-lisp} directories from the source and build
-directories, if they exist.  Normally these directories do not contain
-@file{site-lisp} directories.)
+The first one is for locally installed files for the current Emacs
+@var{version}; the second is for locally installed files meant for use
+with any installed Emacs version.  (If Emacs is running uninstalled,
+it also adds @file{site-lisp} subdirectories from the source and build
+directories, if they exist.  However, normally the source and build
+directories do not contain @file{site-lisp} subdirectories.)
 
 @cindex @env{EMACSLOADPATH} environment variable
 If the environment variable @env{EMACSLOADPATH} is set, it modifies
@@ -363,9 +366,10 @@ export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
 @end example
 
 An empty element in the value of the environment variable, whether
-trailing (as in the above example), leading, or embedded, is replaced
-by the default value of @code{load-path} as determined by the standard
-initialization procedure.  If there are no such empty elements, then
+trailing (as in the above example, note the trailing @samp{:}),
+leading, or embedded, is replaced by the default value of
+@code{load-path} as determined by the standard initialization
+procedure.  If there are no such empty elements, then
 @env{EMACSLOADPATH} specifies the entire @code{load-path}.  You must
 include either an empty element, or the explicit path to the directory
 containing the standard Lisp files, else Emacs will not function.
@@ -394,6 +398,9 @@ add one or more directories to @code{load-path}.  For 
example:
 (push "~/.emacs.d/lisp" load-path)
 @end example
 
+@noindent
+@xref{List Variables, push}, for the description of @code{push}.
+
   Dumping Emacs uses a special value of @code{load-path}.  If you use
 a @file{site-load.el} or @file{site-init.el} file to customize the
 dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path}
@@ -401,10 +408,11 @@ that these files make will be lost after dumping.
 
 @defvar lisp-directory
 This variable holds a string naming the directory which holds
-Emacs's own @code{.el} and @code{.elc} files.  This is usually the
+Emacs's own @file{*.el} and @file{*.elc} files.  This is usually the
 place where those files are located in the Emacs installation tree,
 unless Emacs is run from its build directory in which case it points
-to the @code{lisp} directory in source directory from which it was built.
+to the @file{lisp} subdirectory in the source directory from which
+Emacs was built.
 @end defvar
 
 @deffn Command locate-library library &optional nosuffix path interactive-call
diff --git a/etc/NEWS b/etc/NEWS
index f6ba0167e0..ca6a716ccd 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -72,9 +72,9 @@ work on any underlying window system supported by GDK, such as
 Wayland and Broadway.
 
 ---
-** The docstrings of preloaded files are not in etc/DOC any more.
-Instead, they're fetched from the corresponding '.elc' file, as was already
-the case for all the non-preloaded files.
+** The docstrings of preloaded files are not in 'etc/DOC' any more.
+Instead, they're fetched as needed from the corresponding '.elc' file,
+as was already the case for all the non-preloaded files.
 
 
 * Startup Changes in Emacs 29.1
diff --git a/lisp/startup.el b/lisp/startup.el
index 727432a4cb..76cc9b2ca3 100644
--- a/lisp/startup.el
+++ b/lisp/startup.el
@@ -1057,7 +1057,7 @@ the `--debug-init' option to view a complete error 
backtrace."
       (setq debug-on-error debug-on-error-from-init-file))))
 
 (defvar lisp-directory nil
-  "Directory containing the Lisp files that come with GNU Emacs.")
+  "Directory where Emacs's own *.el and *.elc Lisp files are installed.")
 
 (defun command-line ()
   "A subroutine of `normal-top-level'.
diff --git a/lisp/xwidget.el b/lisp/xwidget.el
index 12ee597504..ab40e81c4d 100644
--- a/lisp/xwidget.el
+++ b/lisp/xwidget.el
@@ -139,7 +139,7 @@ Interactively, URL defaults to the string looking like a 
url around point."
 Get the URL of current session, then browse to the URL
 in `split-window-below' with a new xwidget webkit session."
   (interactive nil xwidget-webkit-mode)
-  (let ((url (xwidget-webkit-current-url)))
+  (let ((url (xwidget-webkit-uri (xwidget-webkit-current-session))))
     (with-selected-window (split-window-below)
       (xwidget-webkit-new-session url))))
 
@@ -148,7 +148,7 @@ in `split-window-below' with a new xwidget webkit session."
 Get the URL of current session, then browse to the URL
 in `split-window-right' with a new xwidget webkit session."
   (interactive nil xwidget-webkit-mode)
-  (let ((url (xwidget-webkit-current-url)))
+  (let ((url (xwidget-webkit-uri (xwidget-webkit-current-session))))
     (with-selected-window (split-window-right)
       (xwidget-webkit-new-session url))))
 
@@ -545,24 +545,31 @@ directory, URL is saved at the specified directory as 
FILE-NAME."
 ;;; Bookmarks integration
 
 (defcustom xwidget-webkit-bookmark-jump-new-session nil
-  "Control bookmark jump to use new session or not.
-If non-nil, use a new xwidget webkit session after bookmark jump.
-Otherwise, it will use `xwidget-webkit-last-session'.
-When you set this variable to nil, consider further customization with
-`xwidget-webkit-last-session-buffer'."
+  "Whether to jump to a bookmarked URL in a new xwidget webkit session.
+If non-nil, create a new xwidget webkit session, otherwise use
+the value of `xwidget-webkit-last-session'."
   :version "28.1"
   :type 'boolean)
 
 (defun xwidget-webkit-bookmark-make-record ()
-  "Create bookmark record in webkit xwidget.
-See `xwidget-webkit-bookmark-jump-new-session' for whether this
-should create a new session or not."
+  "Create a bookmark record for a webkit xwidget."
   (nconc (bookmark-make-record-default t t)
          `((page . ,(xwidget-webkit-uri (xwidget-webkit-current-session)))
-           (handler  . (lambda (bmk)
-                         (xwidget-webkit-browse-url
-                          (bookmark-prop-get bmk 'page)
-                          xwidget-webkit-bookmark-jump-new-session))))))
+           (handler . xwidget-webkit-bookmark-jump-handler))))
+
+;;;###autoload
+(defun xwidget-webkit-bookmark-jump-handler (bookmark)
+  "Jump to the web page bookmarked by the bookmark record BOOKMARK.
+If `xwidget-webkit-bookmark-jump-new-session' is non-nil, create
+a new xwidget-webkit session, otherwise use an existing session."
+  (let* ((url (bookmark-prop-get bookmark 'page))
+        (xwbuf (if (or xwidget-webkit-bookmark-jump-new-session
+                        (not (xwidget-webkit-current-session)))
+                   (xwidget-webkit--create-new-session-buffer url)
+                  (xwidget-buffer (xwidget-webkit-current-session)))))
+    (with-current-buffer xwbuf
+      (xwidget-webkit-goto-uri (xwidget-webkit-current-session) url))
+    (set-buffer xwbuf)))
 
 ;;; xwidget webkit session
 
@@ -810,37 +817,44 @@ For example, use this to display an anchor."
   (add-to-list 'window-size-change-functions
                'xwidget-webkit-adjust-size-in-frame))
 
-(defun xwidget-webkit-new-session (url &optional callback)
-  "Create a new webkit session buffer with URL."
+(defun xwidget-webkit--create-new-session-buffer (url &optional callback)
+  "Create a new webkit session buffer to display URL in an xwidget.
+Optional function CALLBACK specifies the callback for webkit xwidgets;
+see `xwidget-webkit-callback'."
   (let* ((bufname
-          ;; Generate a temp-name based on current buffer name. it
-          ;; will be renamed by `xwidget-webkit-callback' in the
-          ;; future. This approach can limit flicker of buffer-name in
-          ;; mode-line.
+          ;; Generate a temp-name based on current buffer name.  The
+          ;; buffer will subsequently be renamed by
+          ;; `xwidget-webkit-callback'.  This approach can avoid
+          ;; flicker of buffer-name in mode-line.
           (generate-new-buffer-name (buffer-name)))
          (callback (or callback #'xwidget-webkit-callback))
          (current-session (xwidget-webkit-current-session))
          xw)
-    (setq xwidget-webkit-last-session-buffer (switch-to-buffer
-                                              (get-buffer-create bufname)))
+    (setq xwidget-webkit-last-session-buffer (get-buffer-create bufname))
     ;; The xwidget id is stored in a text property, so we need to have
     ;; at least character in this buffer.
     ;; Insert invisible url, good default for next `g' to browse url.
-    (let ((start (point)))
-      (insert url)
-      (put-text-property start (+ start (length url)) 'invisible t)
-      (setq xw (xwidget-insert
-                start 'webkit bufname
-                (xwidget-window-inside-pixel-width (selected-window))
-                (xwidget-window-inside-pixel-height (selected-window))
-                nil current-session)))
-    (when xwidget-webkit-cookie-file
-      (xwidget-webkit-set-cookie-storage-file
-       xw (expand-file-name xwidget-webkit-cookie-file)))
-    (xwidget-put xw 'callback callback)
-    (xwidget-put xw 'display-callback #'xwidget-webkit-display-callback)
-    (xwidget-webkit-mode)
-    (xwidget-webkit-goto-uri (xwidget-webkit-last-session) url)))
+    (with-current-buffer xwidget-webkit-last-session-buffer
+      (let ((start (point)))
+        (insert url)
+        (put-text-property start (+ start (length url)) 'invisible t)
+        (setq xw (xwidget-insert
+                  start 'webkit bufname
+                  (xwidget-window-inside-pixel-width (selected-window))
+                  (xwidget-window-inside-pixel-height (selected-window))
+                  nil current-session)))
+      (when xwidget-webkit-cookie-file
+        (xwidget-webkit-set-cookie-storage-file
+         xw (expand-file-name xwidget-webkit-cookie-file)))
+      (xwidget-put xw 'callback callback)
+      (xwidget-put xw 'display-callback #'xwidget-webkit-display-callback)
+      (xwidget-webkit-mode))
+    xwidget-webkit-last-session-buffer))
+
+(defun xwidget-webkit-new-session (url)
+  "Display URL in a new webkit xwidget."
+  (switch-to-buffer (xwidget-webkit--create-new-session-buffer url))
+  (xwidget-webkit-goto-uri (xwidget-webkit-last-session) url))
 
 (defun xwidget-webkit-import-widget (xwidget)
   "Create a new webkit session buffer from XWIDGET, an existing xwidget.