From 141fe8b827399057e2f854cd5e6b0c148c5fe12b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Thu, 8 Dec 2022 02:25:53 +0100
Subject: [PATCH] use-package: Improve :mode keyword documentation

* doc/misc/use-package.texi (Modes and interpreters): Improve
section and document the use of a list of regexps.

Resolves https://github.com/jwiegley/use-package/issues/996
---
 doc/misc/use-package.texi | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 7819cb250d0..c1cc22808e6 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -1064,19 +1064,43 @@ Similar to @code{:bind}, you can use @code{:mode} and
 @code{:interpreter} to establish a deferred binding within the
 @code{auto-mode-alist} and @code{interpreter-mode-alist} variables.
 The specifier to either keyword can be a cons cell, a list of cons
-cells, or a string or regexp:
+cells, or a string or regexp.
+
+The following example reproduces the default @code{ruby-mode}
+configuration, exactly as it is in Emacs out-of-the-box.  That mode is
+enabled automatically when a file whose name matches the regexp
+@code{"\\.rb\\'"} (a file with the @samp{.rb} extension), or when the
+first line of the file (known as the ``shebang'') matches the string
+@code{"ruby"}:
 
 @lisp
 (use-package ruby-mode
   :mode "\\.rb\\'"
   :interpreter "ruby")
+@end lisp
+
+The default @code{python-mode} configuration can be reproduced using
+the below declaration.  Note that the package that should be loaded
+differs from the mode name in this case, so we must use a cons:
 
+@lisp
 ;; The package is "python" but the mode is "python-mode":
 (use-package python
   :mode ("\\.py\\'" . python-mode)
   :interpreter ("python" . python-mode))
 @end lisp
 
+Both the @code{:mode} and @code{:interpreter} keywords also accept a
+list of regexps:
+
+@lisp
+(use-package foo
+  ;; Equivalent to "\\(ba[rz]\\)\\'":
+  :mode ("\\.bar\\'" "\\.baz\\'")
+  ;; Equivalent to "\\(foo[ab]\\)":
+  :interpreter ("fooa" "foob"))
+@end lisp
+
 @node Magic handlers
 @section Magic handlers
 
-- 
2.39.2