[elpa] externals/async 54977d6 10/60: Improve formatting in README.

[Stefan Monnier]

branch: externals/async
commit 54977d6c596a295f7519a0da36407c3a3e055b36
Author: Thierry Volpiatto <address@hidden>
Commit: Thierry Volpiatto <address@hidden>

    Improve formatting in README.
---
 README.md | 81 +++++++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 48 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 91dfffc..5b2dd6c 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,11 @@
 # emacs-async
 
 `async.el` is a module for doing asynchronous processing in Emacs.
+Some async applications are provided as well with this package:
+
+* Dired-async
+* smtp-mail-async
+* async-bytecomp
 
 # Install
 
@@ -46,7 +51,7 @@ to do this, add to your init file:
 You can control which packages will compile async with 
`async-bytecomp-allowed-packages`.
 Set it to `'(all)` to be sure you will compile all packages asynchronously.
 
-# Usage
+# Async usage
 
 The interface is intended to be very easy to use:
 
@@ -57,41 +62,47 @@ The interface is intended to be very easy to use:
 Execute START-FUNC (often a lambda) in a subordinate Emacs process.  When
 done, the return value is passed to FINISH-FUNC.  Example:
 
-    (async-start
-       ;; What to do in the child process
-       (lambda ()
-         (message "This is a test")
-         (sleep-for 3)
-         222)
-
-       ;; What to do when it finishes
-       (lambda (result)
-         (message "Async process done, result should be 222: %s" result)))
+```elisp
+(async-start
+   ;; What to do in the child process
+   (lambda ()
+     (message "This is a test")
+     (sleep-for 3)
+     222)
+
+   ;; What to do when it finishes
+   (lambda (result)
+     (message "Async process done, result should be 222: %s" result)))
+```
 
 If FINISH-FUNC is `nil` or missing, a future is returned that can be inspected
 using `async-get`, blocking until the value is ready.  Example:
 
-    (let ((proc (async-start
-                   ;; What to do in the child process
-                   (lambda ()
-                     (message "This is a test")
-                     (sleep-for 3)
-                     222))))
+```elisp
+(let ((proc (async-start
+               ;; What to do in the child process
+               (lambda ()
+                 (message "This is a test")
+                 (sleep-for 3)
+                 222))))
 
-        (message "I'm going to do some work here") ;; ....
+    (message "I'm going to do some work here") ;; ....
 
-        (message "Waiting on async process, result should be 222: %s"
-                 (async-get proc)))
+    (message "Waiting on async process, result should be 222: %s"
+             (async-get proc)))
+```
 
 If you don't want to use a callback, and you don't care about any return value
 from the child process, pass the `'ignore` symbol as the second argument (if
 you don't, and never call `async-get`, it will leave ``*emacs*`` process 
buffers
 hanging around):
 
-    (async-start
-     (lambda ()
-       (delete-file "a remote file on a slow link" nil))
-     'ignore)
+```elisp
+(async-start
+ (lambda ()
+   (delete-file "a remote file on a slow link" nil))
+ 'ignore)
+```
 
 Note: Even when FINISH-FUNC is present, a future is still returned except that
 it yields no value (since the value is passed to FINISH-FUNC).  Calling
@@ -138,18 +149,22 @@ the value for every variable matching INCLUDE-REGEXP and 
also PREDICATE.  It
 will not perform injection for any variable matching EXCLUDE-REGEXP (if
 present).  It is intended to be used as follows:
 
-    (async-start
-       `(lambda ()
-          (require 'smtpmail)
-          (with-temp-buffer
-            (insert ,(buffer-substring-no-properties (point-min) (point-max)))
-            ;; Pass in the variable environment for smtpmail
-            ,(async-inject-variables "\\`\\(smtpmail\\|\\(user-\\)?mail\\)-")
-            (smtpmail-send-it)))
-       'ignore)
+```elisp
+(async-start
+   `(lambda ()
+      (require 'smtpmail)
+      (with-temp-buffer
+        (insert ,(buffer-substring-no-properties (point-min) (point-max)))
+        ;; Pass in the variable environment for smtpmail
+        ,(async-inject-variables "\\`\\(smtpmail\\|\\(user-\\)?mail\\)-")
+        (smtpmail-send-it)))
+   'ignore)
+```
 
 ## async-let
 
+    async-let BINDINGS &rest FORMS
+    
 Allow to establish let bindings asynchronously.
 Each value of binding can refer to the symbols already bound in BINDINGS (like 
`let*`).
 FORMS are executed once BINDINGS have been evaluated, but without blocking 
emacs.