branch: externals/setup
commit 88499e827db1126bfbda76b673653adcd3988eee
Author: Philip Kaludercic <phil...@posteo.net>
Commit: Philip Kaludercic <phil...@posteo.net>
Restructure README.md
These changes make the README more consistent with Compat's README.
---
README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++----------------
1 file changed, 68 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index 7a574718c8..f70c017862 100644
--- a/README.md
+++ b/README.md
@@ -1,16 +1,31 @@
-`setup.el`
-==========
+Helpful Configuration Macro
+===========================
-The `setup` macro simplifies repetitive configuration patterns, by
+Find here the source for shell-command+.el, that defines the `setup`
+macro. This simplifies repetitive configuration patterns, by
providing context-sensitive local macros in `setup` bodies.
-See [SetupEl][ewiki] on Emacs Wiki for more details and examples.
+This definition is rather terse, but describes the package and the
+main macro pretty well. If you are interested in more details and
+further examples, check out the [SetupEl] page on Emacs Wiki.
+
+Feel free to contribute to this wiki page, either by adding your own
+local macros or adding any other examples. No accounts is necessary
+to make changes to Emacs Wiki, and everything can be done anonymously.
+
+[SetupEl]:
+ https://www.emacswiki.org/emacs/SetupEl
Installation
------------
-`setup.el` is part of [GNU ELPA][elpa], and can be installed using
-`package.el`.
+`setup.el` is avaliable from [GNU ELPA]. It can be installed by
+invoking
+
+ M-x package-install RET setup RET
+
+[GNU ELPA]:
+ http://elpa.gnu.org/packages/setup.html
Usage
-----
@@ -19,24 +34,55 @@ 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.
-Bugs
-----
+There exist no configuration options for `setup`. Anything you might
+want to add or change can be done by defining or overwriting a local
+macro using `setup-define`.
+
+All local macros are (dynamically) documented as part of the `setup`
+docstring.
+
+Contribute
+----------
+
+As `setup.el` is distribed as part of [GNU ELPA], and therefore
+requires a [copyright assignment] to the [FSF], for all non-trivial
+code contributions.
-Bugs or patches can be submitted to my [public inbox][mail]. Note
-that non-trivial contributions require a [copyright assignment][ca] to
-the FSF.
+I am currently hesitant to add more local macros. The current set is
+already reduced to those that (IMO) do a good job at highlighting
+`setup`s features or are instructive examples on how to define your
+own local macros. Anything that could just as well be an alias or a
+custom, context-insensitive macro is not worthwhile adding to
+`setup.el`.
-This package is still young, so wishes, impressions and criticism are
-very appreciated. If you have anything to say, feel free to send an
-email to the aforementioned [public inbox][mail].
+[copyright assignment]:
+
https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html
+[FSF]:
+ https://www.fsf.org/
-Copying
--------
+Source code
+-----------
+
+`setup` is developed on [SourceHut].
+
+[SourceHut]:
+ https://sr.ht/~pkal/setup
+
+Bugs and Patches
+----------------
+
+Bugs, patches, comments or questions can be submitted to my [public
+inbox].
+
+[public inbox]:
+ https://lists.sr.ht/~pkal/public-inbox
+
+Distribution
+------------
-`setup.el` is distributed under the [GPL v3][gpl3] license.
+`setup.el` and all other source files in this directory are
+distributed under the [GNU Public License], Version 3 (like Emacs
+itself).
-[ewiki]: https://www.emacswiki.org/emacs/SetupEl
-[elpa]: http://elpa.gnu.org/packages/setup.html
-[mail]: https://lists.sr.ht/~pkal/public-inbox
-[ca]:
https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html#Copyright-Assignment
-[gpl3]: https://www.gnu.org/licenses/gpl-3.0.en.html
+[GNU Public License]:
+ https://www.gnu.org/licenses/gpl-3.0.en.html
