Merge from origin/emacs-27

b4937f64cd (origin/emacs-27) Improve documentation of manually instal...
efd4e973a4 Reflect the emacs-devel ELPA/MELPA dispute in FAQ
28541674cd Consider face inheritance when checking region face backgr...
e75f6be6cc Fix dired default file operation (bug#41261)
406fb0746c Fix documentation related to 'command-switch-alist'.
747e0a2523 Improve ediff readability in misterioso theme (Bug#41221)
48830c73e7 Fix a crash in handle_display_spec
a37290a6f9 In x_hide_tip reset tip_last_frame for GTK+ tooltips only ...
3d81995692 Fix docstring of flymake-make-diagnostic (bug#40351)
632aa9d57a Go back to “Bahá’í”
e2406ff60f * lisp/dired.el (dired-toggle-marks): Doc fix.  (Bug#41097)

# Conflicts:
#	doc/emacs/building.texi

5 files changed, 69 insertions, 12 deletions

diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi
index 77a0e807c2b..7074bd45d71 100644
--- a/doc/emacs/building.texi
+++ b/doc/emacs/building.texi
@@ -1541,6 +1541,11 @@ putting a line like this in your init file (@pxref{Init File}):
 (add-to-list 'load-path "/path/to/my/lisp/library")
 @end example
 
+It is customary to put locally installed libraries in the
+@file{site-lisp} directory that is already in the default value of
+@code{load-path}, or in some subdirectory of @file{site-lisp}.  This
+way, you don't need to modify the default value of @code{load-path}.
+
 @cindex autoload
   Some commands are @dfn{autoloaded}; when you run them, Emacs
 automatically loads the associated library first.  For instance, the
@@ -1563,6 +1568,33 @@ Automatic loading also occurs when completing names for
 prefix being completed.  To disable this feature, change the variable
 @code{help-enable-completion-autoload} to @code{nil}.
 
+  Once you put your library in a directory where Emacs can find and
+load it, you may wish to make it available at startup.  This is useful
+when the library defines features that should be available
+automatically on demand, and manually loading the library is thus
+inconvenient.  In these cases, make sure the library will be loaded by
+adding suitable forms to your init file: either @code{load} or
+@code{require} (if you always need to load the library at startup), or
+@code{autoload} if you need Emacs to load the library when some
+command or function is invoked.  For example:
+
+@smalllisp
+@group
+ ;; Loads @file{my-shining-package.elc} unconditionally.
+ (require 'my-shining-package)
+@end group
+@group
+ ;; Will load @file{my-shining-package.elc} when @code{my-func} is invoked.
+ (autoload 'my-func "my-shining-package")
+@end group
+@end smalllisp
+
+  Note that installing a package using @code{package-install}
+(@pxref{Package Installation}) takes care of placing the package's
+Lisp files in a directory where Emacs will find it, and also writes
+the necessary initialization code into your init files, making the
+above manual customizations unnecessary.
+
 @node Lisp Eval
 @section Evaluating Emacs Lisp Expressions
 @cindex Emacs Lisp mode
diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi
index 8dc1a0b2df8..fe51ad35d77 100644
--- a/doc/emacs/calendar.texi
+++ b/doc/emacs/calendar.texi
@@ -532,7 +532,7 @@ holidays centered around a different month, use @kbd{C-u M-x
 holidays}, which prompts for the month and year.
 
   The holidays known to Emacs include United States holidays and the
-major Bah@'{a}@t{'}@'{i}, Chinese, Christian, Islamic, and Jewish
+major Bahá'í, Chinese, Christian, Islamic, and Jewish
 holidays; also the solstices and equinoxes.
 
 @findex list-holidays
diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi
index 91e44b8eba8..453d9eb4010 100644
--- a/doc/emacs/package.texi
+++ b/doc/emacs/package.texi
@@ -5,23 +5,37 @@
 @node Packages
 @chapter Emacs Lisp Packages
 @cindex Package
-@cindex Emacs Lisp package archive
 @cindex Package archive
 
-Emacs includes a facility that lets you easily download and install
-@dfn{packages} that implement additional features.  Each package is a
-separate Emacs Lisp program, sometimes including other components such
-as an Info manual.
+  Emacs is extended by implementing additional features in
+@dfn{packages}, which are Emacs Lisp libraries.  These could be
+written by you or provided by someone else.  If you want to install
+such a package so it is available in your future Emacs session, you
+need to compile it and put it in a directory where Emacs looks for
+Lisp libraries.  @xref{Lisp Libraries}, for more details about this
+manual installation method.  Many packages provide installation and
+usage instructions in the large commentary near the beginning of the
+Lisp file; you can use those instructions for installing and
+fine-tuning your use of the package.
 
-  @kbd{M-x list-packages} brings up a buffer named @file{*Packages*}
-with a list of all packages.  You can install or uninstall packages
-via this buffer.  @xref{Package Menu}.
+@cindex Emacs Lisp package archive
+  Packages can also be provided by @dfn{package archives}, which are
+large collections of Emacs Lisp packages.  Each package is a separate
+Emacs Lisp program, sometimes including other components such as an
+Info manual.  Emacs includes a facility that lets you easily download
+and install packages from such archives.  The rest of this chapter
+describes this facility.
+
+  To list the packages available for installation from package
+archives, type @w{@kbd{M-x list-packages @key{RET}}}.  It brings up a
+buffer named @file{*Packages*} with a list of all packages.  You can
+install or uninstall packages via this buffer.  @xref{Package Menu}.
 
   The command @kbd{C-h P} (@code{describe-package}) prompts for the
 name of a package, and displays a help buffer describing the
 attributes of the package and the features that it implements.
 
-  By default, Emacs downloads packages from a @dfn{package archive}
+  By default, Emacs downloads packages from a package archive
 maintained by the Emacs developers and hosted by the GNU project.
 Optionally, you can also download packages from archives maintained by
 third parties.  @xref{Package Installation}.
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 8bf48b1dbba..8f2c7439d9f 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -613,7 +613,7 @@ The elements of the @code{command-switch-alist} look like this:
 @end example
 
 The @sc{car}, @var{option}, is a string, the name of a command-line
-option (not including the initial hyphen).  The @var{handler-function}
+option (including the initial hyphen).  The @var{handler-function}
 is called to handle @var{option}, and receives the option name as its
 sole argument.
 
@@ -623,6 +623,14 @@ remaining command-line arguments in the variable
 @code{command-line-args-left} (see below).  (The entire list of
 command-line arguments is in @code{command-line-args}.)
 
+Note that the handling of @code{command-switch-alist} doesn't treat
+equals signs in @var{option} specially.  That is, if there's an option
+like @code{--name=value} on the command line, then only a
+@code{command-switch-alist} member whose @code{car} is literally
+@code{--name=value} will match this option.  If you want to parse such
+options, you need to use @code{command-line-functions} instead (see
+below).
+
 The command-line arguments are parsed by the @code{command-line-1}
 function in the @file{startup.el} file.  See also @ref{Emacs
 Invocation, , Command Line Arguments for Emacs Invocation, emacs, The
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 50a208d233b..d3a2f07e254 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -3478,7 +3478,10 @@ There are other, non-GNU, Emacs Lisp package servers, including:
 @uref{https://marmalade-repo.org, Marmalade}.  To use additional
 package servers, customize the @code{package-archives} variable.  Be
 aware that installing a package can run arbitrary code, so only add
-sources that you trust.
+sources that you trust.  Also, packages hosted on non-GNU package
+servers may encourage or require you to install and use non-free
+software; for example, MELPA is known to host some packages that do
+this.
 
 The @uref{https://lists.gnu.org/mailman/listinfo/gnu-emacs-sources,
 GNU Emacs sources mailing list}, which is gatewayed to the