[elpa] externals/shell-command+ a3499cc625 1/2: Restructure README.md

[ELPA Syncer]

branch: externals/shell-command+
commit a3499cc6259ed9cd7a4ebb29c679f635d8021fa9
Author: Philip Kaludercic <philipk@posteo.net>
Commit: Philip Kaludercic <philipk@posteo.net>

    Restructure README.md
    
    These changes make the README more consistent with Compat's README.
---
 README.md | 102 +++++++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 78 insertions(+), 24 deletions(-)

diff --git a/README.md b/README.md
index 166a9bf342..47e5d4265e 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,47 @@
-`shell-command+.el`
-===================
+`shell-command` With a Few Extra Features
+=========================================
 
-`shell-command+` is a `shell-command` substitute that makes it easier
-to run commands on regions or whole buffers, among other things.
+Find here the source for shell-command+.el, that defines an extended
+version of Emacs' `shell-command` (bound to <kbd>M-!</kbd> by
+default). See [(emacs) Single Shell] if you are
+unfamiliar with the command.
 
 `shell-command+` has been based on a function named `bang` by [Leah
-Neukirchen][leah].
+Neukirchen].
 
-How to use
-----------
+[(emacs) Single Shell]:
+       
https://www.gnu.org/software/emacs/manual/html_node/emacs/Single-Shell.html
+[Leah Neukirchen]:
+       http://leahneukirchen.org/dotfiles/.emacs
+
+Installation
+------------
 
-`shell-command+` is available from [ELPA]. It can be installed by
+`shell-command+` is available from [GNU ELPA]. It can be installed by
 invoking
 
        M-x package-install RET shell-command+ RET
 
-Bind the command `shell-command+` to any key, for example `M-!`.
+[GNU ELPA]:
+       http://elpa.gnu.org/packages/shell-command+.html
+
+Usage
+-----
+
+Bind the command `shell-command+` to any key, for example
+<kbd>M-!</kbd>:
+
+~~~elisp
+(global-set-key (kbd "M-!") #'shell-command+)
+~~~
+
+No further changes are necessary.  It is recommended to consult the
+`shell-command+` documentation string (`C-h f shell-command+`) and the
+`shell-command+` customisation group (`M-x customize-group
+shell-command+`).
 
-Using [`setup`][setup] I configure `shell-command+` as so:
+Note that [Dired] rebinds <kbd>M-!</kbd>, so it might be necessary to
+also bind `shell-command+` in `dired-mode-map`.  I do this using [setup]:
 
 ~~~elisp
 (setup (:package shell-command+)
@@ -27,21 +51,51 @@ Using [`setup`][setup] I configure `shell-command+` as so:
   (:global "M-!" shell-command+))
 ~~~
 
-Bugs
-----
+[Dired]:
+       https://www.gnu.org/software/emacs/manual/html_node/emacs/Dired.html
+[setup]:
+       http://elpa.gnu.org/packages/setup.html
+
+Contribute
+----------
+
+As `shell-command+.el` is distribed as part of [GNU ELPA], and
+therefore requires a [copyright assignment] to the [FSF], for all
+non-trivial code contributions.
+
+[copyright assignment]:
+       
https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html
+[FSF]:
+       https://www.fsf.org/
+
+Source code
+-----------
+
+`shell-command+` is developed on [SourceHut].
+
+[SourceHut]:
+       https://sr.ht/~pkal/shell-command-plus
+
+Bugs and Patches
+----------------
+
+Bugs or comments can be submitted to my [public inbox].
+
+When contributing, make sure to provide test and use the existing
+tests defined in shell-command+-tests.el.  These can be easily
+executed using the bundled Makefile:
+
+       make test
 
-Bugs or comments can be submitted to my [public inbox][mail].  Note
-that non-trivial contributions require a [copyright assignment][ca] to
-the FSF.
+[public inbox]:
+       https://lists.sr.ht/~pkal/public-inbox
 
-Copying
--------
+Distribution
+------------
 
-`shell-command+.el` is distributed under the [GPL v3][gpl3] license.
+shell-command+.el and all other source files in this directory are
+distributed under the [GNU Public License], Version 3 (like Emacs
+itself).
 
-[leah]: http://leahneukirchen.org/dotfiles/.emacs
-[ELPA]: http://elpa.gnu.org/packages/shell-command+.html
-[mail]: https://lists.sr.ht/~pkal/public-inbox
-[setup]: http://elpa.gnu.org/packages/setup.html
-[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