Merge branch 'master' into feature/igc3feature/igc3

6 files changed, 117 insertions, 9 deletions

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