Merge branch 'future-doc'

README.adoc

@@ -54,6 +54,7 @@ endif::[]
 :since-0-9: image:https://img.shields.io/badge/since-0.9-8be[Since 0.9,float=right]
 :since-0-10: image:https://img.shields.io/badge/since-0.10-8be[Since 0.10,float=right]
 :since-0-11: image:https://img.shields.io/badge/since-0.11-8be[Since 0.11,float=right]
+:since-1-1: image:https://img.shields.io/badge/since-1.1-8be[Since 1.1,float=right]
 
 = Eldev
 
@@ -498,25 +499,31 @@ init`).  For example:
 ----
 
 Eldev knows about three “standard” archives, which should cover most
-of your needs: `gnu`, `nongnu` (since 0.10) and `melpa`.  When using
-MELPA, you can also explicitly choose `melpa-stable` or
-`melpa-unstable` instead.
+of your needs: `gnu-elpa`, `nongnu-elpa` and `melpa`.
+
+You can also explicitly choose stable (a.k.a. release: `gnu`, `nongnu`
+and `melpa-stable`) or unstable (a.k.a. snapshot or development:
+`gnu-devel`, `nongnu-devel` and `melpa-unstable`) variants instead.
+There are some naming inconsistencies here, because for GNU and NonGNU
+only the stable variants had been added at first (`nongnu` only in
+0.10), nonstable (development) were added later, in 1.1.
 
 {since-0-5} A better way is provided by two global options: `--stable`
 (the default) and `--unstable`.  Normally, Eldev will try to install
-everything from MELPA Stable (you wouldn’t want your tests fail only
-because a dependency in an unstable version has a bug).  However, if a
-package is not available (at all or in the required version) from the
-stable archive, unstable will be used automatically.  If you specify
-`--unstable` on the command line, Eldev will behave in the opposite
-way: prefer the unstable archive and use the stable only as a
-fallback.
+everything from stable archive variants (you wouldn’t want your tests
+fail only because a dependency in an unstable version has a bug).
+However, if a package is not available (at all or in the required
+version) from the stable archive, unstable will be used automatically.
+If you specify `--unstable` on the command line, Eldev will behave in
+the opposite way: prefer the unstable archive and use the stable only
+as a fallback.
 
 Emacs 25 and up supports package archive priorities.  Eldev backports
 this to Emacs 24 and utilizes the feature to assign the standard
-archives it knows about priorities 300 (GNU ELPA), 250 (NonGNU ELPA),
-and 200 and 100 (MELPA Stable/Unstable).  A dependency from a package
-with a lower priority is installed only if there are no other options.
+archives it knows about priorities 300/190 (GNU ELPA, stable/unstable
+variants), 250/150 (NonGNU ELPA), and 200/100 (MELPA).  A dependency
+from a package with a lower priority is installed only if there are no
+other options.
 
 If dependencies for your project are only available from some other
 archive, you can still use the same function.  Just substite the
@@ -1646,12 +1653,12 @@ evaluate expressions stored in a file using `--file` (`-f`) option:
 
 Note that this is _not_ performed using Elisp file loading.  Instead,
 the file is parsed as a sequence of Elisp expression and those are
-then evaluated/executed as if specified on the command line.  In
-particular, for command `eval` results are still printed after every
-expression, even if they all come from the same file.  As in several
-other places, when variable `eldev-dwim` (“do what I mean”) is
-non-nil, option `-f` can be omitted as long as filename ends in `.el`.
-In other words, you can just invoke:
+then evaluated/executed in exactly the same way as if specified on the
+command line.  In particular, for command `eval` results are still
+printed after every expression, even if they all come from the same
+file.  As in several other places, when variable `eldev-dwim` (“do
+what I mean”) is non-nil, option `-f` can be omitted as long as
+filename ends in `.el`.  In other words, you can just invoke:
 
     $ eldev eval useful-expressions.el
 
@@ -1665,8 +1672,33 @@ E.g.:
     3
     7
 
-{since-0-11} These commands also have a few options aimed at code
-profiling.  See <<profiling-eval,relevant section below>>.
+{since-1-1} There are “magic” variables called `@`, `@1`, `@2` and so
+on, aimed at simplifying accessing to previous form results from
+subsequent forms.  Variable `@` always holds the result of previous
+form evaluation; it is thus not available in the very first form.
+Variables `@N`, where `N` is a number, hold result of `N`’s form (`N`
+starts with 1, not 0).  They can be used both in `eval` and `exec`,
+even if the latter doesn’t print the results.
+
+All forms for evaluation/execution are indexed with the same number
+sequence, regardless if they come from command line (including
+multiple forms per parameter) or from a file.
+
+To illustrate:
+
+    $ eldev eval "(generate-new-buffer \"abc\") (buffer-name @)"
+    #<buffer abc>
+    "abc"
+
+Or:
+
+    $ eldev eval "(+ 1 2) (+ 3 4) (* @1 @2)"
+    3
+    7
+    21
+
+{since-0-11} Commands `eval` and `exec` also have a few options aimed
+at code profiling.  See <<profiling-eval,relevant section below>>.
 
 
 == Running Emacs