Simplify documentation of split-screen mode, avoiding abuse of []

to sometimes mean "character set", which conflicts with the normal
meaning of "optional element" in manual pages.  While here, add a
few related clarifications and tweak a few details.
Triggered by a minor bug report from <trondd at kagu-tsuchi dot com>,
and by bentley@ subsequently pointing out the abuse of [].
Patch using input from jmc@, who also agreed with some previous versions.

diff --git a/usr.bin/vi/docs/USD.doc/vi.man/vi.1 b/usr.bin/vi/docs/USD.doc/vi.man/vi.1
index 960dae1..559cd56 100644 (file)
--- a/usr.bin/vi/docs/USD.doc/vi.man/vi.1
+++ b/usr.bin/vi/docs/USD.doc/vi.man/vi.1
@@ -1,4 +1,4 @@
-.\"    $OpenBSD: vi.1,v 1.74 2017/08/22 20:27:18 anton Exp $
+.\"    $OpenBSD: vi.1,v 1.75 2018/02/12 01:10:46 schwarze Exp $
 .\"
 .\" Copyright (c) 1994
 .\"     The Regents of the University of California.  All rights reserved.
@@ -14,7 +14,7 @@
 .\"
 .\"     @(#)vi.1       8.51 (Berkeley) 10/10/96
 .\"
-.Dd $Mdocdate: August 22 2017 $
+.Dd $Mdocdate: February 12 2018 $
 .Dt VI 1
 .Os
 .Sh NAME
@@ -1794,18 +1794,11 @@ Delete the lines from the file.
 Display buffers, screens or tags.
 .Pp
 .It Xo
-.Op Cm Ee Ns
-.Op Cm dit Ns
+.Cm e Ns Op Cm dit Ns | Ns Cm x Ns
 .Op Cm !\&
 .Op Ar +cmd
 .Op Ar file
 .Xc
-.It Xo
-.Op Cm Ee Ns
-.Cm x Ns Op Cm !\&
-.Op Ar +cmd
-.Op Ar file
-.Xc
 Edit a different file.
 .Pp
 .It Xo
@@ -1822,13 +1815,9 @@ command.
 .Xc
 Display and optionally change the file name.
 .Pp
-.It Xo
-.Op Cm Ff Ns
-.Cm g
-.Op Ar name
-.Xc
+.It Cm fg Op Ar name
 .Nm vi
-mode only.
+only.
 Foreground the specified screen.
 .Pp
 .It Xo
@@ -1880,9 +1869,9 @@ Display the lines unambiguously.
 .Cm map Ns Op Cm !\&
 .Op Ar lhs rhs
 .Xc
-Define or display maps (for
 .Nm vi
-only).
+only.
+Define or display maps.
 .Pp
 .It Xo
 .Op Ar line
@@ -1912,8 +1901,7 @@ Write the abbreviations, editor options and maps to the specified
 .Ar file .
 .Pp
 .It Xo
-.Op Cm Nn Ns
-.Op Cm ext Ns
+.Cm n Ns Op Cm ext Ns
 .Op Cm !\&
 .Op Ar file ...
 .Xc
@@ -1933,11 +1921,7 @@ Save the file in a form that can later be recovered using the
 .Fl r
 option.
 .Pp
-.It Xo
-.Op Cm \&Pp Ns
-.Cm rev Ns Op Cm ious Ns
-.Op Cm !\&
-.Xc
+.It Cm prev Ns Oo Cm ious Oc Ns Op Cm !\&
 Edit the previous file from the argument list.
 .Pp
 .It Xo
@@ -1960,6 +1944,8 @@ Append buffer contents to the current line.
 .Op Cm !\&
 .Xc
 End the editing session.
+In split-screen mode, only close the current screen
+and switch to the previous one.
 .Pp
 .It Xo
 .Op Ar line
@@ -1980,7 +1966,7 @@ if it was previously saved.
 .It Xo
 .Cm res Ns Op Cm ize
 .Op Cm + Ns | Ns Cm - Ns
-.Ar size
+.Ar lines
 .Xc
 .Nm vi
 mode only.
@@ -2132,8 +2118,7 @@ character is usually
 .Aq control-Z .
 .Pp
 .It Xo
-.Op Cm Tt Ns
-.Cm a Ns Op Cm g Ns
+.Cm ta Ns Op Cm g Ns
 .Op Cm !\&
 .Ar tagstring
 .Xc
@@ -2195,19 +2180,18 @@ editor.
 .Op Ar flags
 .Xc
 .Nm ex
-mode only.
+only.
 Enter
 .Nm vi .
 .Pp
 .It Xo
-.Op Cm Vi Ns
-.Cm i Ns Op Cm sual Ns
+.Cm vi Ns Op Cm sual Ns
 .Op Cm !\&
 .Op Ar +cmd
 .Op Ar file
 .Xc
 .Nm vi
-mode only.
+only.
 Edit a new file.
 .Pp
 .It Xo
@@ -2225,25 +2209,25 @@ command.
 .Op >>
 .Op Ar file
 .Xc
-.It Xo
-.Op Ar range
-.Cm w Ns Op Cm rite
-.Op Cm !\&
-.Op Ar file
-.Xc
+Write the file.
+.Pp
 .It Xo
 .Op Ar range
 .Cm wn Ns Op Cm !\&
 .Op >>
 .Op Ar file
 .Xc
+Write the file and edit the next file from the argument list.
+.Pp
 .It Xo
 .Op Ar range
 .Cm wq Ns Op Cm !\&
 .Op >>
 .Op Ar file
 .Xc
-Write the file.
+Write the file and exit the editor.
+In split-screen mode, close the current screen
+and switch to the previous one.
 .Pp
 .It Xo
 .Op Ar range
@@ -2253,6 +2237,8 @@ Write the file.
 .Xc
 Exit the editor,
 writing the file if it has been modified.
+In split-screen mode, close the current screen
+and switch to the previous one.
 .Pp
 .It Xo
 .Op Ar range
@@ -2271,6 +2257,21 @@ Copy the specified lines to a buffer.
 .Xc
 Adjust the window.
 .El
+.Pp
+For
+.Cm e ,
+.Cm fg ,
+.Cm n ,
+.Cm prev ,
+.Cm ta ,
+and
+.Cm vi ,
+if the first letter of the command is capitalized, the current screen is
+split and the new file is displayed in addition to the current screen.
+This feature is only available in
+.Nm vi ,
+not in
+.Nm ex .
 .Sh SET OPTIONS
 There are a large number of options that may be set
 .Pq or unset

diff --git a/usr.bin/vi/ex/ex_cmd.c b/usr.bin/vi/ex/ex_cmd.c
index a7665b5..289d4b2 100644 (file)
--- a/usr.bin/vi/ex/ex_cmd.c
+++ b/usr.bin/vi/ex/ex_cmd.c
@@ -1,4 +1,4 @@
-/*     $OpenBSD: ex_cmd.c,v 1.10 2015/11/19 07:53:31 bentley Exp $     */
+/*     $OpenBSD: ex_cmd.c,v 1.11 2018/02/12 01:10:46 schwarze Exp $    */
 
 /*-
  * Copyright (c) 1992, 1993, 1994
@@ -111,7 +111,7 @@ EXCMDLIST const cmds[] = {
        {"bg",          ex_bg,          E_VIONLY,
            "",
            "bg",
-           "put a foreground screen into the background"},
+           "put the current screen into the background"},
 /* C_CHANGE */
        {"change",      ex_change,      E_ADDR2|E_ADDR_ZERODEF,
            "!ca",
@@ -150,12 +150,12 @@ EXCMDLIST const cmds[] = {
 /* C_EDIT */
        {"edit",        ex_edit,        E_NEWSCREEN,
            "f1o",
-           "[Ee][dit][!] [+cmd] [file]",
+           "e[dit][!] [+cmd] [file]",
            "begin editing another file"},
 /* C_EX */
        {"ex",          ex_edit,        E_NEWSCREEN,
            "f1o",
-           "[Ee]x[!] [+cmd] [file]",
+           "ex[!] [+cmd] [file]",
            "begin editing another file"},
 /* C_EXUSAGE */
        {"exusage",     ex_usage,       0,
@@ -170,7 +170,7 @@ EXCMDLIST const cmds[] = {
 /* C_FG */
        {"fg",          ex_fg,          E_NEWSCREEN|E_VIONLY,
            "f1o",
-           "[Ff]g [file]",
+           "fg [file]",
            "bring a backgrounded screen into the foreground"},
 /* C_GLOBAL */
        {"global",      ex_global,      E_ADDR2_ALL,
@@ -225,7 +225,7 @@ EXCMDLIST const cmds[] = {
 /* C_NEXT */
        {"next",        ex_next,        E_NEWSCREEN,
            "!fN",
-           "[Nn][ext][!] [+cmd] [file ...]",
+           "n[ext][!] [+cmd] [file ...]",
            "edit (and optionally specify) the next file"},
 /* C_NUMBER */
        {"number",      ex_number,      E_ADDR2|E_CLRFLAG,
@@ -250,7 +250,7 @@ EXCMDLIST const cmds[] = {
 /* C_PREVIOUS */
        {"previous",    ex_prev,        E_NEWSCREEN,
            "!",
-           "[Pp]rev[ious][!]",
+           "prev[ious][!]",
            "edit the previous file in the file argument list"},
 /* C_PUT */
        {"put",         ex_put, 
@@ -262,7 +262,7 @@ EXCMDLIST const cmds[] = {
        {"quit",        ex_quit,        0,
            "!",
            "q[uit][!]",
-           "exit ex/vi"},
+           "exit ex/vi or close the current screen"},
 /* C_READ */
        {"read",        ex_read,        E_ADDR1|E_ADDR_ZERO|E_ADDR_ZERODEF,
            "s",
@@ -331,7 +331,7 @@ EXCMDLIST const cmds[] = {
 /* C_TAG */
        {"tag",         ex_tag_push,    E_NEWSCREEN,
            "!w1o",
-           "[Tt]a[g][!] [string]",
+           "ta[g][!] [string]",
            "edit the file containing the tag"},
 /* C_TAGNEXT */
        {"tagnext",     ex_tag_next,    0,
@@ -386,7 +386,7 @@ EXCMDLIST const cmds[] = {
 /* C_VISUAL_VI */
        {"visual",      ex_edit,        E_NEWSCREEN,
            "f1o",
-           "[Vv]i[sual][!] [+cmd] [file]",
+           "vi[sual][!] [+cmd] [file]",
            "edit another file (from vi mode only)"},
 /* C_VIUSAGE */
        {"viusage",     ex_viusage,     0,
@@ -412,7 +412,7 @@ EXCMDLIST const cmds[] = {
        {"xit",         ex_xit,         E_ADDR2_ALL|E_ADDR_ZERODEF,
            "!f1o",
            "[line [,line]] x[it][!] [file]",
-           "exit"},
+           "write if modified and exit"},
 /* C_YANK */
        {"yank",        ex_yank,        E_ADDR2,
            "bca",

diff --git a/usr.bin/vi/ex/ex_usage.c b/usr.bin/vi/ex/ex_usage.c
index 4787bcc..446877d 100644 (file)
--- a/usr.bin/vi/ex/ex_usage.c
+++ b/usr.bin/vi/ex/ex_usage.c
@@ -1,4 +1,4 @@
-/*     $OpenBSD: ex_usage.c,v 1.8 2014/11/12 04:28:41 bentley Exp $    */
+/*     $OpenBSD: ex_usage.c,v 1.9 2018/02/12 01:10:46 schwarze Exp $   */
 
 /*-
  * Copyright (c) 1992, 1993, 1994
@@ -58,7 +58,7 @@ ex_usage(SCR *sp, EXCMD *cmdp)
        ARGS *ap;
        EXCMDLIST const *cp;
        int newscreen;
-       char *name, *p, nb[MAXCMDNAMELEN + 5];
+       char *p;
 
        switch (cmdp->argc) {
        case 1:
@@ -96,30 +96,11 @@ ex_usage(SCR *sp, EXCMD *cmdp)
                }
                break;
        case 0:
-               for (cp = cmds; cp->name != NULL && !INTERRUPTED(sp); ++cp) {
-                       /*
-                        * The ^D command has an unprintable name.
-                        *
-                        * XXX
-                        * We display both capital and lower-case versions of
-                        * the appropriate commands -- no need to add in extra
-                        * room, they're all short names.
-                        */
-                       if (cp == &cmds[C_SCROLL])
-                               name = "^D";
-                       else if (F_ISSET(cp, E_NEWSCREEN)) {
-                               nb[0] = '[';
-                               nb[1] = toupper(cp->name[0]);
-                               nb[2] = cp->name[0];
-                               nb[3] = ']';
-                               for (name = cp->name + 1,
-                                   p = nb + 4; (*p++ = *name++) != '\0';);
-                               name = nb;
-                       } else
-                               name = cp->name;
-                       (void)ex_printf(sp,
-                           "%*s: %s\n", MAXCMDNAMELEN, name, cp->help);
-               }
+               for (cp = cmds; cp->name != NULL && !INTERRUPTED(sp); ++cp)
+                       (void)ex_printf(sp, "%*s: %s\n", MAXCMDNAMELEN,
+                           /* The ^D command has an unprintable name. */
+                           cp == &cmds[C_SCROLL] ? "^D" : cp->name,
+                           cp->help);
                break;
        default:
                abort();