[elpa] externals/setup 1925ed2 06/10: Mention defsetup macro in tips section

[Stefan Monnier]

branch: externals/setup
commit 1925ed20c5855bfdd642e5f38efbe0dcc03311de
Author: Philip K <philipk@posteo.net>
Commit: Philip K <philipk@posteo.net>

    Mention defsetup macro in tips section
---
 README.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 49 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 93ae38d..8d1aa63 100644
--- a/README.md
+++ b/README.md
@@ -63,20 +63,56 @@ The `setup` macro is autoloaded, and can be used directly.  
The code
 generated by `setup` does not depend on `setup.el`, meaning that your
 initialization file can be byte-compiled more efficiently.
 
-Tip
----
-
-The first element of a `setup` body can but does not have to be a
-name. That can be exploited to use `setup` in your own macros. I have
-this macro in my personal configuration, when I'm only interested in
-modifying user options:
+Tips
+----
 
-~~~elisp
-(defmacro setc (&rest args)
-  "Customize user options using ARGS like `setq'."
-  (declare (debug setq))
-  `(setup (:option ,@args)))
-~~~
+1. The first element of a `setup` body can but does not have to be a
+   name. That can be exploited to use `setup` in your own macros. I have
+   this macro in my personal configuration, when I'm only interested in
+   modifying user options:
+
+   ~~~elisp
+   (defmacro setc (&rest args)
+     "Customize user options using ARGS like `setq'."
+     (declare (debug setq))
+     `(setup (:option ,@args)))
+   ~~~
+
+2. If you wish to define you own macros, use `setup-define`. In case the
+   syntax is too cumbersome, you can use a macro like this:
+
+   ~~~elisp
+   (defmacro defsetup (name signature &rest body)
+     "Shorthand for `setup-define'.
+   NAME is the name of the local macro.  SIGNATURE is used as the
+   argument list for FN.  If BODY starts with a string, use this as
+   the value for :documentation.  Any following keywords are passed
+   as OPTS to `setup-define'."
+     (declare (debug defun))
+     (let (opts)
+       (when (stringp (car body))
+         (setq opts (nconc (list :documentation (pop body))
+                           opts)))
+       (while (keywordp (car body))
+         (let* ((prop (pop body))
+                (val `',(pop body)))
+           (setq opts (nconc (list prop val) opts))))
+       `(setup-define ,name
+          (cl-function (lambda ,signature ,@body))
+          ,@opts)))
+   ~~~
+
+   To declare local macros more like `defun` or `defmacro`. Here is how
+   the definition for `:package` could be rewritten:
+
+   ~~~elisp
+   (defsetup :package (package)
+     "Install PACKAGE if it hasn't been installed yet."
+     :repeatable t
+     :shorthand #'cadr
+     `(unless (package-installed-p ',package)
+          (package-install ',package)))
+   ~~~
 
 Bugs
 ----