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.

3 files changed, 58 insertions, 76 deletions

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 960dae17864..559cd56a686 100644
--- 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 a7665b52709..289d4b2b444 100644
--- 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 4787bcc1b03..446877de7c5 100644
--- 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();