[src/trunk]: src/lib/libedit documentation improvements (Ingo Schwarze)

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a3b3f50a7d52
branches:  trunk
changeset: 345375:a3b3f50a7d52
user:      christos <christos%NetBSD.org@localhost>
date:      Sun May 22 23:54:20 2016 +0000

description:
documentation improvements (Ingo Schwarze)

diffstat:

 lib/libedit/editline.3 |  42 +++++++++++++++++++++++-------------------
 lib/libedit/editrc.5   |  38 +++++++++++++++++++-------------------
 2 files changed, 42 insertions(+), 38 deletions(-)

diffs (168 lines):

diff -r 9f05846c5086 -r a3b3f50a7d52 lib/libedit/editline.3
--- a/lib/libedit/editline.3    Sun May 22 23:04:27 2016 +0000
+++ b/lib/libedit/editline.3    Sun May 22 23:54:20 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: editline.3,v 1.91 2016/05/21 17:06:44 christos Exp $
+.\"    $NetBSD: editline.3,v 1.92 2016/05/22 23:54:20 christos Exp $
 .\"
 .\" Copyright (c) 1997-2014 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -26,7 +26,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 9, 2016
+.Dd May 22, 2016
 .Dt EDITLINE 3
 .Os
 .Sh NAME
@@ -94,9 +94,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
@@ -113,7 +113,7 @@
 .Fn el_source "EditLine *e" "const char *file"
 .Ft void
 .Fn el_resize "EditLine *e"
-.Fn int
+.Ft int
 .Fn el_cursor "EditLine *e" "int count"
 .Ft const LineInfo *
 .Fn el_line "EditLine *e"
@@ -250,10 +250,8 @@
 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,
@@ -284,17 +282,23 @@
 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 -r 9f05846c5086 -r a3b3f50a7d52 lib/libedit/editrc.5
--- a/lib/libedit/editrc.5      Sun May 22 23:04:27 2016 +0000
+++ b/lib/libedit/editrc.5      Sun May 22 23:54:20 2016 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: editrc.5,v 1.31 2016/04/28 15:50:34 christos Exp $
+.\"    $NetBSD: editrc.5,v 1.32 2016/05/22 23:54:20 christos Exp $
 .\"
 .\" Copyright (c) 1997-2000 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -26,7 +26,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd December 25, 2014
+.Dd May 22, 2016
 .Dt EDITRC 5
 .Os
 .Sh NAME
@@ -88,21 +88,19 @@
 .Pp
 The following builtin commands are available:
 .Bl -tag -width 4n
-.It Ic bind Oo Fl a Oc Oo Fl e Oc Oo Fl k Oc Oo Fl l Oc Oo Fl r Oc \
-Oo Fl s Oc Oo Fl v Oc Oo Ar key Oo Ar command Oc Oc
-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
@@ -121,13 +119,15 @@
 .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.
@@ -137,10 +137,10 @@
 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