10 files changed, 228 insertions, 35 deletions

diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index bf137ef946b..77fff25b7b2 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -868,13 +868,20 @@ otherwise stated, affects only the current Emacs session.  The only
 way to alter the variable in future sessions is to put something in
 your initialization file (@pxref{Init File}).
 
-  If you're setting a customizable variable in your initialization
-file, and you don't want to use the Customize interface, you can use
-the @code{setopt} macro.  For instance:
-
 @findex setopt
+  If you're setting a customizable variable, and you don't want to use
+the Customize interface, you can use the @code{setopt} macro.  For
+instance:
+
 @example
-(setopt fill-column 75)
+ M-: (setopt fill-column 75) @key{RET}
+@end example
+
+@noindent
+Or, if you want to do this in your initialization file:
+
+@example
+ (setopt fill-column 75)
 @end example
 
 This works the same as @code{setq}, but if the variable has any
@@ -883,6 +890,34 @@ special setter functions, they will be run automatically when using
 non-customizable variables, but this is less efficient than using
 @code{setq}.
 
+@findex setopt-local
+  There is also a buffer-local version of @code{setopt}, called
+@code{setopt-local}, that you can use to set buffer specific values for
+customizable options, for example, in mode hooks (@pxref{Hooks}).
+
+This works the same as @code{setq-local}, but if the variable has any
+special setter functions, they will be run automatically when using
+@code{setopt-local}.  You can also use @code{setopt-local} on other,
+non-customizable variables, but this is less efficient than using
+@code{setq-local}.
+
+  If you want to change the value of a customizable variable only in
+your current buffer, you can use the @code{setopt-local} macro.  For
+instance:
+
+@example
+ M-: (setopt-local fill-column 75) @key{RET}
+@end example
+
+@noindent
+Or, if you want to do this in your initialization file, use the
+following inside a mode hook so this variable will be automatically
+customized in buffers of that mode (@pxref{Hooks}):
+
+@example
+ (setopt-local fill-column 75)
+@end example
+
 @node Hooks
 @subsection Hooks
 @cindex hook
@@ -3262,7 +3297,7 @@ acquainted with conventions from other programs.
   The functionality enabled by the @code{newcomers-presets} theme will
 change between releases of Emacs.  We may add new functionality, and
 also remove old functionality that we think has been superseded.
-Therefore, if you get used to the newcomers' presets, consider copying
-them into your own configuration and then disabling the theme again.
-You can use the command @code{copy-theme-options} (@pxref{Custom
-Themes}) to do this.
+Therefore, if you get used to the newcomers' presets, you should copy
+them into your own configuration and then disable the theme again.  You
+can use the command @code{copy-theme-options} (@pxref{Custom Themes}) to
+do this.
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 4aee5e1045d..697a13dbe7b 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -2764,10 +2764,10 @@ Table}.)
 @node Xref Commands
 @subsubsection Commands Available in the @file{*xref*} Buffer
 @cindex commands in @file{*xref*} buffers
-@cindex XREF mode
+@cindex Xref mode
 
   The following commands are provided in the @file{*xref*} buffer by
-the special XREF mode:
+the special Xref mode:
 
 @table @kbd
 @item @key{RET}
@@ -2880,7 +2880,7 @@ prompt always, customize the value of the variable
 to prompt only if there's no usable identifier at point.)  The command
 then presents the @file{*xref*} buffer with all the references to the
 identifier, showing the file name and the line where the identifier is
-referenced.  The XREF mode commands are available in this buffer, see
+referenced.  The Xref mode commands are available in this buffer, see
 @ref{Xref Commands}.
 
 When invoked in a buffer whose major mode uses the @code{etags} backend,
@@ -2926,6 +2926,16 @@ matches of that regexp in the names of the identifiers with
 @code{xref-query-replace-in-results}, but is more convenient when you
 want to rename a single identifier specified by its name @var{from}.
 
+@findex xref-change-to-xref-edit-mode
+@cindex Xref Edit mode
+@cindex mode, Xref Edit
+  Typing @kbd{e} in the @file{*xref*} buffer makes the buffer writable
+and enters the Xref Edit mode.  Similar to Occur Edit mode (@pxref{Other
+Repeating Search}), you can edit the matching lines reported by
+Xref backend and have those changes reflected in the buffer visiting the
+originating file.  Type @kbd{C-c C-c} to leave the Xref Edit mode and
+return to the Xref mode.
+
 @findex tags-search
   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
 searches for matches in all the files in the selected tags table, one
diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi
index 1497a9906bd..a712b3a1b46 100644
--- a/doc/lispintro/emacs-lisp-intro.texi
+++ b/doc/lispintro/emacs-lisp-intro.texi
@@ -14660,9 +14660,9 @@ beginning of the file.  The function definition looks like this:
 @smallexample
 @group
 (defun lengths-list-file (filename)
-  "Return list of definitions' lengths within FILE.
+  "Return list of definitions' lengths within the file named FILENAME.
 The returned list is a list of numbers.
-Each number is the number of words or
+Each number in the list is the number of words or
 symbols in one function definition."
 @end group
 @group
@@ -14683,10 +14683,10 @@ symbols in one function definition."
 @end smallexample
 
 @noindent
-The function is passed one argument, the name of the file on which it
-will work.  It has four lines of documentation, but no interactive
-specification.  Since people worry that a computer is broken if they
-don't see anything going on, the first line of the body is a
+The function is passed one argument @var{filename}, the name of the file
+on which it will work.  It has four lines of documentation, but no
+interactive specification.  Since people worry that a computer is broken
+if they don't see anything going on, the first line of the body is a
 message.
 
 The next line contains a @code{save-excursion} that returns Emacs's
@@ -14730,8 +14730,8 @@ definition and constructs a lengths' list containing the information.
 Emacs kills the buffer after working through it.  This is to save
 space inside of Emacs.  My version of GNU Emacs 19 contained over 300
 source files of interest; GNU Emacs 22 contains over a thousand source
-files.  Another function will apply @code{lengths-list-file} to each
-of the files.
+files, and Emacs 30.2 more than 1600.  Another function will apply
+@code{lengths-list-file} to each of the files.
 
 Finally, the last expression within the @code{let} expression is the
 @code{lengths-list} variable; its value is returned as the value of
@@ -14744,13 +14744,13 @@ C-e} (@code{eval-last-sexp}).
 @c !!! 22.1.1 lisp sources location here
 @smallexample
 (lengths-list-file
- "/usr/local/share/emacs/22.1/lisp/emacs-lisp/debug.el")
+ "/usr/local/share/emacs/30.2/lisp/emacs-lisp/debug.el")
 @end smallexample
 
 @noindent
-You may need to change the pathname of the file; the one here is for
-GNU Emacs version 22.1.  To change the expression, copy it to
-the @file{*scratch*} buffer and edit it.
+You may need to change the name of the file; the one here is for default
+installation tree of GNU Emacs version 30.2.  To change the expression,
+copy it to the @file{*scratch*} buffer and edit it.
 
 @need 1200
 @noindent
@@ -14768,10 +14768,11 @@ Then evaluate the @code{lengths-list-file} expression.)
 
 @need 1200
 The lengths' list for @file{debug.el} takes less than a second to
-produce and looks like this in GNU Emacs 22:
+produce and looks like this in GNU Emacs 30.2:
 
 @smallexample
-(83 113 105 144 289 22 30 97 48 89 25 52 52 88 28 29 77 49 43 290 232 587)
+(79 26 140 34 17 112 81 24 155 54 43 102 21 36 36 117 28 29 102 49 43
+ 208 101 28 22 728 15 27)
 @end smallexample
 
 @need 1500
diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi
index 364edf63031..705af15e4e2 100644
--- a/doc/lispref/customize.texi
+++ b/doc/lispref/customize.texi
@@ -372,12 +372,15 @@ added by calls to @code{custom-add-frequent-value} (see below).
 @item :set @var{setfunction}
 Specify @var{setfunction} as the way to change the value of this
 option when using the Customize interface.  The function
-@var{setfunction} should take two arguments, a symbol (the option
-name) and the new value, and should do whatever is necessary to update
+@var{setfunction} should take two or three arguments, a symbol (the option
+name), the new value, and an optional @var{buffer-local} indicator.
+@var{setfunction} should do whatever is necessary to update
 the value properly for this option (which may not mean simply setting
 the option as a Lisp variable); preferably, though, it should not
-modify its value argument destructively.  The default for
-@var{setfunction} is @code{set-default-toplevel-value}.
+modify its value argument destructively.  If optional @var{buffer-local}
+is non-nil, the new value should be set buffer locally and not affect its
+global or default values.  The default for @var{setfunction} is
+@code{set-default-toplevel-value}.
 
 If defined, @var{setfunction} will also be called when evaluating a
 @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp mode and when the
@@ -387,7 +390,7 @@ If defined, @var{setfunction} will also be called when evaluating a
 If you specify this keyword, the variable's documentation string
 should describe how to do the same job in hand-written Lisp code,
 either by invoking @var{setfunction} directly or by using
-@code{setopt}.
+@code{setopt} or @code{setopt-local}.
 
 @kindex get@r{, @code{defcustom} keyword}
 @item :get @var{getfunction}
diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index 656a422cf6e..9115b3a4691 100644
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1661,6 +1661,7 @@ Tips and Conventions
 * Compilation Tips::        Making compiled code run fast.
 * Warning Tips::            Turning off compiler warnings.
 * Documentation Tips::      Writing readable documentation strings.
+* Documentation Group Tips::  Writing useful documentation groups.
 * Comment Tips::            Conventions for writing comments.
 * Library Headers::         Standard headers for library packages.
 
diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi
index 049e8ac3e84..f86a18fd896 100644
--- a/doc/lispref/files.texi
+++ b/doc/lispref/files.texi
@@ -2777,6 +2777,9 @@ the end of the file name.
 
 If @var{text} is a string, @code{make-temp-file} inserts it in the file.
 
+On Posix systems, Emacs creates the file with permissions that limit its
+access to the current user.
+
 To prevent conflicts among different libraries running in the same
 Emacs, each Lisp program that uses @code{make-temp-file} should have its
 own @var{prefix}.  The number added to the end of @var{prefix}
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index d57d643e922..c50619a2de0 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -89,6 +89,20 @@ displayed on that terminal; the list of possible values is the same as
 for @code{framep} above.
 @end defun
 
+@defun frame-initial-p &optional frame
+This predicate returns non-@code{nil} if @var{frame} is or holds the
+initial text frame that is used internally during daemon mode
+(@pxref{Initial Options, daemon,, emacs, The GNU Emacs Manual}), batch
+mode (@pxref{Batch Mode}), and the early stages of startup
+(@pxref{Startup Summary}).  Interactive and graphical programs, for
+instance, can use this predicate to avoid operating on the initial
+frame, which is never displayed.
+
+If @var{frame} is a terminal, this function returns non-@code{nil} if
+@var{frame} holds the initial frame.  If @var{frame} is omitted or
+@code{nil}, it defaults to the selected one.
+@end defun
+
 @cindex top-level frame
 On a graphical terminal we distinguish two types of frames: A normal
 @dfn{top-level frame} is a frame whose window-system window is a child
@@ -3029,7 +3043,7 @@ direction.
   See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
 Window Ordering}.
 
-  Some Lisp programs need to find one or more frames that satisfy a
+  Some Lisp programs need to find one or more frames that satisfy
 given criteria.  The function @code{filtered-frame-list} is provided for
 this purpose.
 
diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi
index 3261cf838f7..a9bc9221912 100644
--- a/doc/lispref/help.texi
+++ b/doc/lispref/help.texi
@@ -828,14 +828,16 @@ if the user types the help character again.
 @cindex documentation groups
 @cindex groups of functions
 @cindex function groups
+@cindex shortdoc groups
 
 Emacs can list functions based on various groupings.  For instance,
 @code{string-trim} and @code{mapconcat} are ``string'' functions, so
-@kbd{M-x shortdoc RET string RET} will give an overview
-of functions that operate on strings.
+@kbd{M-x shortdoc RET string RET} will give an overview of these and
+other functions that operate on strings.
 
 The documentation groups are created with the
-@code{define-short-documentation-group} macro.
+@code{define-short-documentation-group} macro.  @xref{Documentation
+Group Tips}, for how to write good documentation groups.
 
 @defmac define-short-documentation-group group &rest functions
 Define @var{group} as a group of functions, and provide short
@@ -846,6 +848,7 @@ summaries of using those functions.  The optional argument
 (@var{func} [@var{keyword} @var{val}]@dots{})
 @end lisp
 
+@cindex documentation group keywords
 The following keywords are recognized:
 
 @table @code
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 7f22dc06ef2..2fbac9508d6 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -35,6 +35,7 @@ in batch mode, e.g., with a command run by @kbd{@w{M-x compile
 * Compilation Tips::          Making compiled code run fast.
 * Warning Tips::              Turning off compiler warnings.
 * Documentation Tips::        Writing readable documentation strings.
+* Documentation Group Tips::  Writing useful documentation groups.
 * Comment Tips::              Conventions for writing comments.
 * Library Headers::           Standard headers for library packages.
 @end menu
@@ -934,6 +935,89 @@ If you do not anticipate anyone editing your code with older Emacs
 versions, there is no need for this work-around.
 @end itemize
 
+@node Documentation Group Tips
+@section Tips for Documentation Groups
+@cindex documentation groups, tips
+@cindex tips for documentation groups
+
+@cindex documentation groups, compatibility
+  Documentation groups, available since Emacs 28, are useful to document
+functions of Lisp packages based on various groupings
+(@pxref{Documentation Groups}).  This section gives some tips on how you
+can define documentation groups in your Lisp package in a way such that
+users of different Emacs versions can equally well use these groups.
+
+@itemize @bullet
+@item
+To define documentation groups for your own Lisp package across
+different Emacs versions, you can use a boilerplate template along the
+lines of the following to make your package compile and load without
+errors:
+
+@smallexample
+@group
+;;; well-doc.el --- a well-documented package -*- lexical-binding: t; -*-
+
+@dots{} package header and contents @dots{}
+@end group
+
+@group
+;; Explicitly require shortdoc for Emacs 28, which does not have an
+;; autoload for macro `define-short-documentation-group'.  And for
+;; Emacs 30, so that we can redefine `shortdoc--check' later.
+(require 'shortdoc nil t)
+
+(eval-when-compile
+
+  ;; Default macro `define-short-documentation-group' for Emacs 27
+  ;; and older, which do not have the shortdoc feature at all.
+  (unless (fboundp 'define-short-documentation-group)
+    (defmacro define-short-documentation-group (&rest _)))
+
+  ;; Disable too rigid shortdoc checks for Emacs 30, which let it
+  ;; error out on newer shortdoc keywords.
+  (when (eq emacs-major-version 30)
+    (fset 'shortdoc--check #'ignore)))
+@end group
+
+@group
+(define-short-documentation-group well-doc
+  @dots{})
+
+;;; well-doc.el ends here
+@end group
+@end smallexample
+
+@findex define-short-documentation-group
+If you do not intend to support some of the Emacs versions mentioned
+above, you can safely omit the corresponding forms from the template.
+If you intend to support only Emacs 31 and newer, you do not need any
+of the above and can just use @code{define-short-documentation-group}.
+
+@item
+@cindex documentation group keywords, compatibility
+Newer Emacs versions might introduce newer documentation group features
+and keywords.  However, these features or keywords will never break the
+display of a documentation group in older Emacs versions.  Suppose you
+use a hypothetical group keyword @code{:super-pretty-print}, available
+in some future Emacs version, like this in your Lisp package
+@file{well-doc.el}:
+
+@smallexample
+@group
+(define-short-documentation-group well-doc
+  (well-doc-foo
+   :eval (well-doc-foo)
+   :super-pretty-print t))
+@end group
+@end smallexample
+
+That future Emacs version will then supposedly super-pretty-print the
+example for function @code{well-doc-foo}.  Older Emacs versions will
+silently ignore keyword @code{:super-pretty-print} and show the example
+according to their regular display rules.
+@end itemize
+
 @node Comment Tips
 @section Tips on Writing Comments
 @cindex comments, Lisp convention for
diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index b75a037f78b..23b6dce2ec6 100644
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -6728,6 +6728,45 @@ See the docstring of variable @code{tramp-methods} for possible
 @code{foo-tramp-executable} in this example would be a Lisp constant,
 which is the program name of @command{foo}.
 
+If a parameter doesn't have a static value but must be computed at
+runtime, a format specifier can be used, like @t{"%h"} in the example
+above.  See the docstring of @code{tramp-methods}, which patterns are
+expanded in which parameter.  Furthermore, other format specifiers can
+be added via the variable @code{tramp-extra-expand-args}.
+
+The following parameters expand format specifiers for the
+@code{tramp-sh} backend: @code{tramp-copy-args},
+@code{tramp-copy-env}, @code{tramp-copy-file-name},
+@code{tramp-login-args}, @code{tramp-login-program},
+@code{tramp-remote-copy-args}.
+
+The example above could use
+
+@lisp
+(tramp-login-program "%1")
+@end lisp
+
+And you could set @code{tramp-extra-expand-args} as connection-local value:
+
+@lisp
+@group
+(defun foo-tramp-get-login-program (vec)
+  "Return connection-local value of `tramp-login-program'."
+  @dots{})
+@end group
+
+@group
+(connection-local-set-profile-variables
+ 'foo-tramp-connection-local-default-profile
+ '((tramp-extra-expand-args
+    ?1 (foo-tramp-get-login-program (car tramp-current-connection)))))
+
+(connection-local-set-profiles
+ '(:application tramp :protocol "foo")
+ foo-tramp-connection-local-default-profile)
+@end group
+@end lisp
+
 Another initialization could tell @value{tramp} which are the default
 user and host name for method @option{foo}.  This is done by calling
 @code{tramp-set-completion-function}: