Document el_wpush(3) and fix the description of el_push(3).

Improve precision in the description of the "bind" builtin command.
Tweak terminology to better match editline(7).

2 files changed, 42 insertions, 39 deletions

diff --git a/lib/libedit/editline.3 b/lib/libedit/editline.3
index 25b9bc81a4d..0deef4aa88c 100644
--- a/lib/libedit/editline.3
+++ b/lib/libedit/editline.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: editline.3,v 1.45 2016/05/21 16:34:30 schwarze Exp $
+.\"	$OpenBSD: editline.3,v 1.46 2016/05/22 22:08:42 schwarze Exp $
 .\"	$NetBSD: editline.3,v 1.88 2016/02/25 14:59:22 wiz Exp $
 .\"
 .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 21 2016 $
+.Dd $Mdocdate: May 22 2016 $
 .Dt EDITLINE 3
 .Os
 .Sh NAME
@@ -89,9 +89,9 @@
 .Ft int
 .Fn el_wgetc "EditLine *e" "wchar_t *wc"
 .Ft void
-.Fn el_push "EditLine *e" "const char *str"
+.Fn el_push "EditLine *e" "const char *mbs"
 .Ft void
-.Fn el_wpush "EditLine *e" "const wchar_t *str"
+.Fn el_wpush "EditLine *e" "const wchar_t *wcs"
 .Ft int
 .Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
 .Ft int
@@ -232,10 +232,8 @@ The return value may not remain valid across calls to
 and must be copied if the data is to be retained.
 .It Fn el_wgetc
 Read a wide character from the tty, respecting the current locale,
-or from the input stream written by
-.Fn el_wpush
-and
-.Fn el_push
+or from the input queue described in
+.Xr editline 7
 if that is not empty, and store it in
 .Fa wc .
 If an invalid or incomplete character is found, it is discarded,
@@ -266,17 +264,23 @@ to
 and return \-1.
 In the C or POSIX locale, this simply reads a byte, but for any other
 locale, including UTF-8, this is rarely useful.
+.It Fn el_wpush
+Push the wide character string
+.Fa wcs
+back onto the input queue described in
+.Xr editline 7 .
+If the queue overflows, for example due to a recursive macro,
+or if an error occurs, for example because
+.Fa wcs
+is
+.Dv NULL
+or memory allocation fails, the function beeps at the user,
+but does not report the problem to the caller.
 .It Fn el_push
-Pushes
-.Fa str
-back onto the input stream.
-This is used by the macro expansion mechanism.
-Refer to the description of
-.Ic bind
-.Fl s
-in
-.Xr editrc 5
-for more information.
+Use the current locale to convert the multibyte string
+.Fa mbs
+to a wide character string, and pass the result to
+.Fn el_wpush .
 .It Fn el_parse
 Parses the
 .Fa argv
diff --git a/lib/libedit/editrc.5 b/lib/libedit/editrc.5
index 18fb41cdb5d..5e06e6bbcc8 100644
--- a/lib/libedit/editrc.5
+++ b/lib/libedit/editrc.5
@@ -1,5 +1,5 @@
-.\"	$OpenBSD: editrc.5,v 1.31 2016/04/20 01:11:45 schwarze Exp $
-.\"	$NetBSD: editrc.5,v 1.30 2016/04/17 18:39:14 christos Exp $
+.\"	$OpenBSD: editrc.5,v 1.32 2016/05/22 22:08:42 schwarze Exp $
+.\"	$NetBSD: editrc.5,v 1.31 2016/04/28 15:50:34 christos Exp $
 .\"
 .\" Copyright (c) 1997-2000 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: April 20 2016 $
+.Dd $Mdocdate: May 22 2016 $
 .Dt EDITRC 5
 .Os
 .Sh NAME
@@ -85,22 +85,19 @@ These are based on similar named builtins present in the tcsh shell.
 .Pp
 The following builtin commands are available:
 .Bl -tag -width 4n
-.It Ic bind Fl aeklrsv Xo
-.Op Ar key Op Ar command
-.Xc
-Without options, list all bound keys, and the editor command to which
-each is bound.
-If
+.It Ic bind Oo Fl aeklrsv Oc Op Ar key Op Ar command
+Without options and arguments, list all bound keys and macros, and
+the editor command or input string to which each one is bound.
+If only
 .Ar key
-is supplied, show the bindings for
-.Ar key .
+is supplied, show the binding for that key or macro.
 If
 .Ar key command
-is supplied, bind
+is supplied, bind the editor
 .Ar command
-to
-.Ar key .
-Options include:
+to that key or macro.
+.Pp
+The options are as follows:
 .Bl -tag -width 4n
 .It Fl a
 List or change key bindings in the
@@ -119,13 +116,15 @@ or
 .It Fl l
 List all editor commands and a short description of each.
 .It Fl r
-Remove a key's binding.
+Remove the binding of the key or macro
+.Ar key .
 .It Fl s
+Define a keyboard macro rather than a key binding or command macro:
 .Ar command
-is taken as a literal string and treated as terminal input when
+is taken as a literal string and appended to the input queue whenever
 .Ar key
 is typed.
-Bound keys in
+Bound keys and macros in
 .Ar command
 are themselves reinterpreted, and this continues for ten levels of
 interpretation.
@@ -135,10 +134,10 @@ Bind all keys to the standard
 bindings.
 .El
 .Pp
-.Ar command
-may be one of the editor commands documented in the
+The
 .Xr editline 7
-manual, or another key.
+manual documents all editor commands and contains more information
+about macros and the input queue.
 .Pp
 .Ar key
 and