[nongnu] elpa/macrostep 2c5bda2 090/110: Update README, bump version number

[ELPA Syncer]

branch: elpa/macrostep
commit 2c5bda25f0cad3a46698a5c75e85f310f0b925ac
Author: joddie <jonxfield@gmail.com>
Commit: joddie <jonxfield@gmail.com>

    Update README, bump version number
---
 README.org   | 235 ++++++++++++++++++++++++++++++++++---------------------
 macrostep.el | 250 ++++++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 306 insertions(+), 179 deletions(-)

diff --git a/README.org b/README.org
index 2cfbf08..cdb7fe0 100644
--- a/README.org
+++ b/README.org
@@ -1,33 +1,37 @@
-* macrostep: interactive macro expansion for Emacs Lisp
-
-** Overview
-   This is a minor mode for interactively stepping through the
-   expansion of macros in Emacs Lisp source code. It lets you see
-   exactly what happens at each step of the expansion process by
-   pretty-printing the expanded forms inline in the source buffer,
-   which is read-only while macro expansions are visible. You can
-   expand and collapse macro forms one step at a time, and evaluate or
-   instrument them for debugging with Edebug as normal (but see "Bugs
-   and known limitations", below). Single-stepping through the
-   expansion is useful for debugging macros that expand into another
-   macro form, especially one like =lexical-let= that does significant
-   rewriting. These can be difficult to debug with Emacs' built-in
-   =macroexpand=, because =macroexpand= continues expansion until the
-   top-level form is no longer a macro call.
-
-   The mode also adds some simple additional fontification to
-   macro-expanded code. The heads of macro sub-forms are fontified
-   using =macrostep-macro-face=. Uninterned symbols (gensyms) are
+* macrostep: interactive macro-expander
+
+   =macrostep= is an Emacs minor mode for interactively stepping
+   through the expansion of macros in Emacs Lisp source code.  It lets
+   you see exactly what happens at each step of the expansion process
+   by pretty-printing the expanded forms inline in the source buffer,
+   which is temporarily read-only while macro expansions are visible.
+   You can expand and collapse macro forms one step at a time, and
+   evaluate or instrument the expansions for debugging with Edebug as
+   normal (but see "Bugs and known limitations", below).
+   Single-stepping through the expansion is particularly useful for
+   debugging macros that expand into another macro form.  These can be
+   difficult to debug with Emacs' built-in =macroexpand=, which
+   continues expansion until the top-level form is no longer a macro
+   call.
+
+   Both globally-visible macros as defined by =defmacro= and local
+   macros bound by =(cl-)macrolet= or another macro-defining form can
+   be expanded.  Within macro expansions, calls to macros and compiler
+   macros are fontified specially: macro forms using
+   =macrostep-macro-face=, and functions with compiler macros using
+   =macrostep-compiler-macro-face=.  Uninterned symbols (gensyms) are
    fontified based on which step in the expansion created them, to
-   distinguish them from normal symbols and from other gensyms with
-   the same print name. Use =customize-group= with the =macrostep=
-   group to customize these faces.
+   distinguish them both from normal symbols and from other gensyms
+   with the same print name.
 
-   Both macros defined by =defmacro= and local macros created by
-   =macrolet= and =cl-macrolet= can be expanded.
+   As of version 0.9, it is also possible to extend =macrostep= to
+   work with other languages with macro systems in addition to Emacs
+   Lisp.  An extension for Common Lisp (via SLIME) is in the works;
+   contributions for other languages are welcome.  See "Extending
+   macrostep" below for details.
 
 ** Key-bindings and usage
-   The standard macrostep-mode keybindings are the following:
+   The standard keybindings in =macrostep-mode= are the following:
  
     - e, =, RET  :: expand the macro form following point one step
     - c, u, DEL  :: collapse the form following point
@@ -36,7 +40,7 @@
     - p, M-TAB   :: jump to the previous macro form in the expansion
 
     It's not very useful to enable and disable macrostep-mode
-    directly. Instead, bind =macrostep-expand= to a key in
+    directly.  Instead, bind =macrostep-expand= to a key in
     =emacs-lisp-mode-map=, for example C-c e:
 
 #+BEGIN_SRC emacs-lisp
@@ -46,62 +50,113 @@
     You can then enter macrostep-mode and expand a macro form
     completely by typing =C-c e e e ...= as many times as necessary.
 
-    Exit macrostep-mode either with =q=, =C-c C-c=, or by successively
-    typing =c= to collapse all expanded forms back to their original
-    text.
+    Exit macrostep-mode by typing =q= or =C-c C-c=, or by successively
+    typing =c= to collapse all surrounding expansions.
+
+** Customization options
+   Type =M-x customize-group RET macrostep RET= to customize options
+   and faces.
+
+   To display macro expansions in a separate window, instead of inline
+   in the source buffer, customize
+   =macrostep-expand-in-separate-buffer= to =t=.  The default is
+   =nil=.  Whichever default behavior is selected, the alternative
+   behavior can be obtained temporarily by giving a prefix argument to
+   =macrostep-expand=.
+
+   To have =macrostep= ignore compiler macros, customize
+   =macrostep-expand-compiler-macros= to =nil=.  The default is =t=.
+
+   Customize the faces =macrostep-macro-face=,
+   =macrostep-compiler-macro-face=, and =macrostep-gensym-1= through
+   =macrostep-gensym-5= to alter the appearance of macro expansions.
+
+** Locally-bound macros
+   As of version 0.9, =macrostep= can expand calls to a locally-bound
+   macro, whether defined by a surrounding =(cl-)macrolet= form, or by
+   another macro-defining macro.  In other words, it is possible to
+   expand the inner =local-macro= forms in both the following
+   examples, whether =local-macro= is defined by an enclosing
+   =cl-macrolet= --
+   
+   #+BEGIN_SRC emacs-lisp
+     (cl-macrolet ((local-macro (&rest args)
+                     `(expansion of ,args)))
+       (local-macro (do-something)))
+   #+END_SRC
+
+   -- or by a macro which expands into =cl-macrolet=, provided that
+   its definition of macro is evaluated prior to calling
+   =macrostep-expand=:
+
+   #+BEGIN_SRC emacs-lisp
+     (defmacro with-local-macro (&rest body)
+       `(cl-macrolet ((local-macro (&rest args)
+                        `(expansion of ,args)))
+          ,@body))
+
+     (with-local-macro
+         (local-macro (do something (else)))
+   #+END_SRC
+
+   See the =with-js= macro in Emacs's =js.el= for a real example of
+   the latter kind of macro.
+
+   Expansion of locally-bound macros is implemented by instrumenting
+   Emacs Lisp's macro-expander to capture the environment at point.  A
+   similar trick is used to detect macro- and compiler-macro calls
+   within expanded text so that they can be fontified accurately.
 
 ** Expanding sub-forms
-    By moving point around in the macro expansion (perhaps using the
-    =n= and =p= keys), you can macro-expand sub-forms before fully
-    expanding the enclosing form. This can be useful in some cases,
-    but you should keep in mind that it does not correspond to the way
-    Emacs actually expands macro calls when evaluating or compiling
-    your code.  Macro expansion in Emacs Lisp always proceeds by fully
-    expanding the outer form to a non-macro form before doing anything
-    with the sub-forms.
-    
-    For example, with =cl= loaded, try expanding the following form:
-
-#+BEGIN_SRC emacs-lisp
-   (dolist (l list-of-lists)
-    (incf (car l)))
-#+END_SRC
-
-   to produce the following:
-
-#+BEGIN_SRC emacs-lisp
-  (block nil
-    (let
-        ((--cl-dolist-temp-- list-of-lists)
-         l)
-      (while --cl-dolist-temp--
-        (setq l
-              (car --cl-dolist-temp--))
-        (incf
-         (car l))
-        (setq --cl-dolist-temp--
-              (cdr --cl-dolist-temp--)))
-      nil))
-#+END_SRC
-
-   where the forms beginning =block= and =incf= are both macro calls.
-
-   At this point, you can either continue expanding the =block= form,
-   which corresponds to the real order of macro expansion in
-   evaluation, or type =n= to move point to the unexpanded =incf= and
-   expand it to a =callf= form and finally to a =let*= form.  If you
-   then move point back to the =block= and expand it, an unexpanded
-   =incf= form appears again in the result.  This might look visually
-   confusing, but it does at least correspond to the way real macro
-   expansion works.
-
-   Why allow expanding sub-forms out of order like this at all? The
-   main reason is for debugging macros which expand into another
-   macro, like =lexical-let=, that programmatically expands its
-   contents in order to rewrite them.  In this case, expanding the
-   sub-forms first allows you to see what =lexical-let= would compute
-   via =cl-macroexpand-all=.
-
+   By moving point around in the macro expansion using
+   =macrostep-next-macro= and =macrostep-prev-macro= (bound to the =n=
+   and =p= keys), it is possible to expand other macro calls within
+   the expansion before expanding the outermost form.  This can
+   sometimes be useful, although it does not correspond to the real
+   order of macro expansion in Emacs Lisp, which proceeds by fully
+   expanding the outer form to a non-macro form before expanding
+   sub-forms.
+
+   The main reason to expand sub-forms out of order is to help with
+   debugging macros which programmatically expand their arguments in
+   order to rewrite them.  Expanding the arguments of such a macro
+   lets you visualise what the macro definition would compute via
+   =macroexpand-all=.
+
+** Extending macrostep for other languages
+   Since version 0.9, it is possible to extend macrostep to work with
+   other languages besides Emacs Lisp.  In typical Emacs fashion, this
+   is implemented by setting buffer-local variables to different
+   function values.  Six buffer-local variables define the
+   language-specific part of the implementation:
+
+   - =macrostep-sexp-bounds-function=
+   - =macrostep-sexp-at-point-function=
+   - =macrostep-environment-at-point-function=
+   - =macrostep-expand-1-function=
+   - =macrostep-print-function=
+   - =macrostep-macro-form-p-function=
+
+   Typically, an implementation for another language would set these
+   variables in a major-mode hook.  See the docstrings of each
+   variable for details on how each one is called and what it should
+   return.  At a minimum, another language implementation needs to
+   provide =macrostep-sexp-at-point-function=,
+   =macrostep-expand-1-function=, and =macrostep-print-function=.
+   Lisp-like languages may be able to reuse the default
+   =macrostep-sexp-bounds-function= if they provide another
+   implementation of =macrostep-macro-form-p-function=.  Languages
+   which do not implement locally-defined macros can set
+   =macrostep-environment-at-point-function= to =ignore=.
+   
+   Note that the core =macrostep= machinery only interprets the return
+   value of =macrostep-sexp-bounds-function=, so implementations for
+   other languages can use any internal representations of code and
+   environments which is convenient.  Although the terminology is
+   Lisp-specific, there is no reason that implementations could not be
+   provided for non-Lisp languages with macro systems, provided there
+   is some way of identifying macro calls and calling the compiler /
+   preprocessor to obtain their expansions.
 
 ** Bugs and known limitations
    You can evaluate and edebug macro-expanded forms and step through
@@ -113,13 +168,6 @@
    possible that using =print-circle= and =print-gensym= could get
    around this.
 
-   The macro stepper doesn't bother trying to determine whether or not
-   a sub-form is in an evaluated position before highlighting it as a
-   macro. It does exclude =lambda= from treatment as a macro, since
-   that leads to an endless series of expansions: =(function (function
-   ... ))=. It would be better to recognise =function=, =quote= and
-   other special forms using their =edebug-form-spec= property.
-
    Please send other bug reports and feature requests to the author.
 
 ** Acknowledgements
@@ -130,12 +178,21 @@
      the expanded region and properly handle backquotes.
    - Nic Ferrier for suggesting support for local definitions within
      macrolet forms
+   - Luís Oliveira for suggesting and implementing SLIME support
+
+   =macrostep= was originally inspired by J. V. Toups's 'Deep Emacs
+   Lisp' articles 
([[http://dorophone.blogspot.co.uk/2011/04/deep-emacs-part-1.html][part 1]], 
[[http://dorophone.blogspot.co.uk/2011/04/deep-emacs-lisp-part-2.html][part 
2]], 
[[http://dorophone.blogspot.co.uk/2011/05/monadic-parser-combinators-in-elisp.html][screencast]]).
 
 ** Changelog
+   - v0.9, 2015-10-01:
+     - separate into Elisp-specific and generic components
+     - highlight and expand compiler macros
+     - improve local macro expansion and macro form identification by
+       instrumenting =macroexpand(-all)=
    - v0.8, 2014-05-29: fix a bug with printing the first element of
      lists
    - v0.7, 2014-05-11: expand locally-defined macros within
-     (cl-)macrolet forms
+     =(cl-)macrolet= forms
    - v0.6, 2013-05-04: better handling of quote and backquote
    - v0.5, 2013-04-16: highlight region, maintain cleaner buffer state
    - v0.4, 2013-04-07: only enter macrostep-mode on successful
diff --git a/macrostep.el b/macrostep.el
index 3fcb33f..72fa636 100644
--- a/macrostep.el
+++ b/macrostep.el
@@ -1,12 +1,12 @@
-;;; macrostep.el --- interactive macro stepper for Emacs Lisp
+;;; macrostep.el --- interactive macro expander
 
-;; Copyright (C) 2012-2014 Jonathan Oddie <j.j.oddie@gmail.com>
+;; Copyright (C) 2012-2015 Jonathan Oddie <j.j.oddie@gmail.com>
 
 ;; Author:     joddie <j.j.oddie@gmail.com>
 ;; Maintainer: joddie <j.j.oddie@gmail.com>
 ;; Created:    16 January 2012
-;; Updated:    11 May 2014
-;; Version:    0.8
+;; Updated:    01 October 2015
+;; Version:    0.9
 ;; Keywords:   lisp, languages, macro, debugging
 ;; Url:        https://github.com/joddie/macrostep
 
@@ -27,39 +27,39 @@
 
 ;;; Commentary:
 
-;; 1 Overview
-;; ==========
-
-;;   This is a minor mode for interactively stepping through the expansion
-;;   of macros in Emacs Lisp source code. It lets you see exactly what
-;;   happens at each step of the expansion process by pretty-printing the
-;;   expanded forms inline in the source buffer, which is read-only while
-;;   macro expansions are visible. You can expand and collapse macro forms
-;;   one step at a time, and evaluate or instrument them for debugging with
-;;   Edebug as normal (but see "Bugs and known limitations",
-;;   below). Single-stepping through the expansion is useful for debugging
-;;   macros that expand into another macro form, especially one like
-;;   `lexical-let' that does significant rewriting. These can be difficult
-;;   to debug with Emacs' built-in `macroexpand', because `macroexpand'
-;;   continues expansion until the top-level form is no longer a macro
-;;   call.
-
-;;   The mode also adds some simple additional fontification to
-;;   macro-expanded code. The heads of macro sub-forms are fontified using
-;;   `macrostep-macro-face'. Uninterned symbols (gensyms) are fontified
-;;   based on which step in the expansion created them, to distinguish them
-;;   from normal symbols and from other gensyms with the same print
-;;   name. Use `customize-group' with the `macrostep' group to customize
-;;   these faces.
-
-;;   Both macros defined by `defmacro' and local macros created by
-;;   `macrolet' and `cl-macrolet' can be expanded.
-
-
-;; 2 Key-bindings and usage
+;; `macrostep' is an Emacs minor mode for interactively stepping through
+;; the expansion of macros in Emacs Lisp source code.  It lets you see
+;; exactly what happens at each step of the expansion process by
+;; pretty-printing the expanded forms inline in the source buffer, which is
+;; temporarily read-only while macro expansions are visible.  You can
+;; expand and collapse macro forms one step at a time, and evaluate or
+;; instrument the expansions for debugging with Edebug as normal (but see
+;; "Bugs and known limitations", below).  Single-stepping through the
+;; expansion is particularly useful for debugging macros that expand into
+;; another macro form.  These can be difficult to debug with Emacs'
+;; built-in `macroexpand', which continues expansion until the top-level
+;; form is no longer a macro call.
+
+;; Both globally-visible macros as defined by `defmacro' and local macros
+;; bound by `(cl-)macrolet' or another macro-defining form can be expanded.
+;; Within macro expansions, calls to macros and compiler macros are
+;; fontified specially: macro forms using `macrostep-macro-face', and
+;; functions with compiler macros using `macrostep-compiler-macro-face'.
+;; Uninterned symbols (gensyms) are fontified based on which step in the
+;; expansion created them, to distinguish them both from normal symbols and
+;; from other gensyms with the same print name.
+
+;; As of version 0.9, it is also possible to extend `macrostep' to work
+;; with other languages with macro systems in addition to Emacs Lisp.  An
+;; extension for Common Lisp (via SLIME) is in the works; contributions for
+;; other languages are welcome.  See "Extending macrostep" below for
+;; details.
+
+
+;; 1 Key-bindings and usage
 ;; ========================
 
-;;   The standard macrostep-mode keybindings are the following:
+;;   The standard keybindings in `macrostep-mode' are the following:
 
 ;;   e, =, RET : expand the macro form following point one step
 ;;   c, u, DEL : collapse the form following point
@@ -67,9 +67,9 @@
 ;;   n, TAB    : jump to the next macro form in the expansion
 ;;   p, M-TAB  : jump to the previous macro form in the expansion
 
-;;   It's not very useful to enable and disable macrostep-mode
-;;   directly. Instead, bind `macrostep-expand' to a key in
-;;   `emacs-lisp-mode-map', for example C-c e:
+;;   It's not very useful to enable and disable macrostep-mode directly.
+;;   Instead, bind `macrostep-expand' to a key in `emacs-lisp-mode-map',
+;;   for example C-c e:
 
 ;;   ,----
 ;;   | (define-key emacs-lisp-mode-map (kbd "C-c e") 'macrostep-expand)
@@ -78,63 +78,123 @@
 ;;   You can then enter macrostep-mode and expand a macro form completely
 ;;   by typing `C-c e e e ...' as many times as necessary.
 
-;;   Exit macrostep-mode either with `q', `C-c C-c', or by successively
-;;   typing `c' to collapse all expanded forms back to their original text.
+;;   Exit macrostep-mode by typing `q' or `C-c C-c', or by successively
+;;   typing `c' to collapse all surrounding expansions.
 
 
-;; 3 Expanding sub-forms
-;; =====================
+;; 2 Customization options
+;; =======================
+
+;;   Type `M-x customize-group RET macrostep RET' to customize options and
+;;   faces.
+
+;;   To display macro expansions in a separate window, instead of inline in
+;;   the source buffer, customize `macrostep-expand-in-separate-buffer' to
+;;   `t'.  The default is `nil'.  Whichever default behavior is selected,
+;;   the alternative behavior can be obtained temporarily by giving a
+;;   prefix argument to `macrostep-expand'.
+
+;;   To have `macrostep' ignore compiler macros, customize
+;;   `macrostep-expand-compiler-macros' to `nil'.  The default is `t'.
+
+;;   Customize the faces `macrostep-macro-face',
+;;   `macrostep-compiler-macro-face', and `macrostep-gensym-1' through
+;;   `macrostep-gensym-5' to alter the appearance of macro expansions.
+
 
-;;   By moving point around in the macro expansion (perhaps using the `n'
-;;   and `p' keys), you can macro-expand sub-forms before fully expanding
-;;   the enclosing form. This can be useful in some cases, but you should
-;;   keep in mind that it does not correspond to the way Emacs actually
-;;   expands macro calls when evaluating or compiling your code.  Macro
-;;   expansion in Emacs Lisp always proceeds by fully expanding the outer
-;;   form to a non-macro form before doing anything with the sub-forms.
+;; 3 Locally-bound macros
+;; ======================
 
-;;   For example, with `cl' loaded, try expanding the following form:
+;;   As of version 0.9, `macrostep' can expand calls to a locally-bound
+;;   macro, whether defined by a surrounding `(cl-)macrolet' form, or by
+;;   another macro-defining macro.  In other words, it is possible to
+;;   expand the inner `local-macro' forms in both the following examples,
+;;   whether `local-macro' is defined by an enclosing `cl-macrolet' --
 
 ;;   ,----
-;;   | (dolist (l list-of-lists)
-;;   |  (incf (car l)))
+;;   | (cl-macrolet ((local-macro (&rest args)
+;;   |                 `(expansion of ,args)))
+;;   |   (local-macro (do-something)))
 ;;   `----
 
-;;   to produce the following:
+;;   -- or by a macro which expands into `cl-macrolet', provided that its
+;;   definition of macro is evaluated prior to calling `macrostep-expand':
 
 ;;   ,----
-;;   | (block nil
-;;   |   (let
-;;   |       ((--cl-dolist-temp-- list-of-lists)
-;;   |        l)
-;;   |     (while --cl-dolist-temp--
-;;   |       (setq l
-;;   |             (car --cl-dolist-temp--))
-;;   |       (incf
-;;   |        (car l))
-;;   |       (setq --cl-dolist-temp--
-;;   |             (cdr --cl-dolist-temp--)))
-;;   |     nil))
+;;   | (defmacro with-local-macro (&rest body)
+;;   |   `(cl-macrolet ((local-macro (&rest args)
+;;   |                    `(expansion of ,args)))
+;;   |      ,@body))
+;;   | 
+;;   | (with-local-macro
+;;   |     (local-macro (do something (else)))
 ;;   `----
 
-;;   where the forms beginning `block' and `incf' are both macro calls.
+;;   See the `with-js' macro in Emacs's `js.el' for a real example of the
+;;   latter kind of macro.
 
-;;   At this point, you can either continue expanding the `block' form,
-;;   which corresponds to the real order of macro expansion in evaluation,
-;;   or type `n' to move point to the unexpanded `incf' and expand it to a
-;;   `callf' form and finally to a `let*' form.  If you then move point
-;;   back to the `block' and expand it, an unexpanded `incf' form appears
-;;   again in the result.  This might look visually confusing, but it does
-;;   at least correspond to the way real macro expansion works.
+;;   Expansion of locally-bound macros is implemented by instrumenting
+;;   Emacs Lisp's macro-expander to capture the environment at point.  A
+;;   similar trick is used to detect macro- and compiler-macro calls within
+;;   expanded text so that they can be fontified accurately.
 
-;;   Why allow expanding sub-forms out of order like this at all? The main
-;;   reason is for debugging macros which expand into another macro, like
-;;   `lexical-let', that programmatically expands its contents in order to
-;;   rewrite them.  In this case, expanding the sub-forms first allows you
-;;   to see what `lexical-let' would compute via `cl-macroexpand-all'.
 
+;; 4 Expanding sub-forms
+;; =====================
 
-;; 4 Bugs and known limitations
+;;   By moving point around in the macro expansion using
+;;   `macrostep-next-macro' and `macrostep-prev-macro' (bound to the `n'
+;;   and `p' keys), it is possible to expand other macro calls within the
+;;   expansion before expanding the outermost form.  This can sometimes be
+;;   useful, although it does not correspond to the real order of macro
+;;   expansion in Emacs Lisp, which proceeds by fully expanding the outer
+;;   form to a non-macro form before expanding sub-forms.
+
+;;   The main reason to expand sub-forms out of order is to help with
+;;   debugging macros which programmatically expand their arguments in
+;;   order to rewrite them.  Expanding the arguments of such a macro lets
+;;   you visualise what the macro definition would compute via
+;;   `macroexpand-all'.
+
+
+;; 5 Extending macrostep for other languages
+;; =========================================
+
+;;   Since version 0.9, it is possible to extend macrostep to work with
+;;   other languages besides Emacs Lisp.  In typical Emacs fashion, this is
+;;   implemented by setting buffer-local variables to different function
+;;   values.  Six buffer-local variables define the language-specific part
+;;   of the implementation:
+
+;;   - `macrostep-sexp-bounds-function'
+;;   - `macrostep-sexp-at-point-function'
+;;   - `macrostep-environment-at-point-function'
+;;   - `macrostep-expand-1-function'
+;;   - `macrostep-print-function'
+;;   - `macrostep-macro-form-p-function'
+
+;;   Typically, an implementation for another language would set these
+;;   variables in a major-mode hook.  See the docstrings of each variable
+;;   for details on how each one is called and what it should return.  At a
+;;   minimum, another language implementation needs to provide
+;;   `macrostep-sexp-at-point-function', `macrostep-expand-1-function', and
+;;   `macrostep-print-function'.  Lisp-like languages may be able to reuse
+;;   the default `macrostep-sexp-bounds-function' if they provide another
+;;   implementation of `macrostep-macro-form-p-function'.  Languages which
+;;   do not implement locally-defined macros can set
+;;   `macrostep-environment-at-point-function' to `ignore'.
+
+;;   Note that the core `macrostep' machinery only interprets the return
+;;   value of `macrostep-sexp-bounds-function', so implementations for
+;;   other languages can use any internal representations of code and
+;;   environments which is convenient.  Although the terminology is
+;;   Lisp-specific, there is no reason that implementations could not be
+;;   provided for non-Lisp languages with macro systems, provided there is
+;;   some way of identifying macro calls and calling the compiler /
+;;   preprocessor to obtain their expansions.
+
+
+;; 6 Bugs and known limitations
 ;; ============================
 
 ;;   You can evaluate and edebug macro-expanded forms and step through the
@@ -145,17 +205,10 @@
 ;;   same print name as another symbol in the expansion. It's possible that
 ;;   using `print-circle' and `print-gensym' could get around this.
 
-;;   The macro stepper doesn't bother trying to determine whether or not a
-;;   sub-form is in an evaluated position before highlighting it as a
-;;   macro. It does exclude `lambda' from treatment as a macro, since that
-;;   leads to an endless series of expansions: `(function (function
-;;   ... ))'. It would be better to recognise `function', `quote' and other
-;;   special forms using their `edebug-form-spec' property.
-
 ;;   Please send other bug reports and feature requests to the author.
 
 
-;; 5 Acknowledgements
+;; 7 Acknowledgements
 ;; ==================
 
 ;;   Thanks to:
@@ -165,17 +218,34 @@
 ;;     expanded region and properly handle backquotes.
 ;;   - Nic Ferrier for suggesting support for local definitions within
 ;;     macrolet forms
+;;   - Luís Oliveira for suggesting and implementing SLIME support
 
+;;   `macrostep' was originally inspired by J. V. Toups's 'Deep Emacs Lisp'
+;;   articles ([part 1], [part 2], [screencast]).
 
 ;;   [EmacsConf presentation] http://youtu.be/RvPFZL6NJNQ
 
+;;   [part 1]
+;;   http://dorophone.blogspot.co.uk/2011/04/deep-emacs-part-1.html
+
+;;   [part 2]
+;;   http://dorophone.blogspot.co.uk/2011/04/deep-emacs-lisp-part-2.html
+
+;;   [screencast]
+;;   
http://dorophone.blogspot.co.uk/2011/05/monadic-parser-combinators-in-elisp.html
+
 
-;; 6 Changelog
+;; 8 Changelog
 ;; ===========
 
+;;   - v0.9, 2015-10-01:
+;;     - separate into Elisp-specific and generic components
+;;     - highlight and expand compiler macros
+;;     - improve local macro expansion and macro form identification by
+;;       instrumenting `macroexpand(-all)'
 ;;   - v0.8, 2014-05-29: fix a bug with printing the first element of lists
-;;   - v0.7, 2014-05-11: expand locally-defined macros within (cl-)macrolet
-;;     forms
+;;   - v0.7, 2014-05-11: expand locally-defined macros within
+;;     `(cl-)macrolet' forms
 ;;   - v0.6, 2013-05-04: better handling of quote and backquote
 ;;   - v0.5, 2013-04-16: highlight region, maintain cleaner buffer state
 ;;   - v0.4, 2013-04-07: only enter macrostep-mode on successful