Hi,
while trying to fix the documentation of screen splitting in the vi(1)
manual page, jmc@ suggested to stop documenting it at all. I like
the idea because splitting is useless and confusing and the already
excessively large documentation profits from simplification.
Rationale:
1. vi screen splitting is confusing and poorly thought out.
Just as one example, try the following:
$ for f in 1 2 3; do echo content$f > test$f; done
$ vi test[123]
:N
# Now you have split screen mode with test1 and test2.
:N # again
# Only results in an error message: No more files to edit.
<control-W>
# Now you are in the upper, test1 screen.
:N # again
# Now you have two copies of test2 open at the same time, with no warning.
A changed text <escape> :w
# Results in error message: Read-only file, not written; use ! to override.
<control-W> A different change <escape> :wq
# Writes the change normally, with no warning.
<control-W> :n
# That opens test2 again in the upper screen, even though you
# already opened it earlier with :N in the lower screen.
:N
# Now you have test3 open, so the behaviour of :N (and :n) depends
# on which screen you are in, but it is quirky and confusing
# in each of the cases as soon as you use more than one screen.
2. It is useless in 2018. There are so many more standard ways to
do the same: Multiple xterms, multiple shells in one terminal
window, tmux(1), even standard shell job control with multiple
vi processes...
Here is a comprehensive diff removing the related clutter from
the manual page and from :exusage and :viusage.
OK?
Ingo
Index: docs/USD.doc/vi.man/vi.1
===================================================================
RCS file: /cvs/src/usr.bin/vi/docs/USD.doc/vi.man/vi.1,v
retrieving revision 1.74
diff -u -p -r1.74 vi.1
--- docs/USD.doc/vi.man/vi.1 22 Aug 2017 20:27:18 -0000 1.74
+++ docs/USD.doc/vi.man/vi.1 7 Feb 2018 18:12:51 -0000
@@ -689,10 +689,6 @@ If this is the first
.Aq Cm control-U
command, scroll half the number of lines in the current screen.
.Pp
-.It Aq Cm control-W
-Switch to the next lower screen in the window,
-or to the first screen if there are no lower screens in the window.
-.Pp
.It Xo
.Op Ar count
.Aq Cm control-Y
@@ -1737,11 +1733,6 @@ The input text is appended after the spe
.It Cm ar Ns Op Cm gs
Display the argument list.
.Pp
-.It Cm bg
-.Nm vi
-only.
-Background the current screen.
-.Pp
.It Xo
.Op Ar range
.Cm c Ns Op Cm hange Ns
@@ -1788,24 +1779,16 @@ Delete the lines from the file.
.It Xo
.Cm di Ns Op Cm splay
.Cm b Ns Oo Cm uffers Oc |
-.Cm s Ns Oo Cm creens Oc |
.Cm t Ns Op Cm ags
.Xc
-Display buffers, screens or tags.
+Display buffers 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
@@ -1823,15 +1806,6 @@ command.
Display and optionally change the file name.
.Pp
.It Xo
-.Op Cm Ff Ns
-.Cm g
-.Op Ar name
-.Xc
-.Nm vi
-mode only.
-Foreground the specified screen.
-.Pp
-.It Xo
.Op Ar range
.Cm g Ns Op Cm lobal
.No / Ns Ar pattern Ns /
@@ -1880,9 +1854,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 +1886,7 @@ Write the abbreviations, editor options
.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 +1906,7 @@ Save the file in a form that can later b
.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 +1929,8 @@ Append buffer contents to the current li
.Op Cm !\&
.Xc
End the editing session.
+This command can also be used to get out of the intentionally
+undocumented, non-standard, split-screen mode.
.Pp
.It Xo
.Op Ar line
@@ -1978,15 +1949,6 @@ Recover
if it was previously saved.
.Pp
.It Xo
-.Cm res Ns Op Cm ize
-.Op Cm + Ns | Ns Cm - Ns
-.Ar size
-.Xc
-.Nm vi
-mode only.
-Grow or shrink the current screen.
-.Pp
-.It Xo
.Cm rew Ns Op Cm ind Ns
.Op Cm !\&
.Xc
@@ -2132,8 +2094,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 +2156,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
@@ -2231,19 +2191,23 @@ command.
.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.
.Pp
.It Xo
.Op Ar range
Index: ex/ex_cmd.c
===================================================================
RCS file: /cvs/src/usr.bin/vi/ex/ex_cmd.c,v
retrieving revision 1.10
diff -u -p -r1.10 ex_cmd.c
--- ex/ex_cmd.c 19 Nov 2015 07:53:31 -0000 1.10
+++ ex/ex_cmd.c 7 Feb 2018 18:12:52 -0000
@@ -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,
@@ -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",
Index: ex/ex_usage.c
===================================================================
RCS file: /cvs/src/usr.bin/vi/ex/ex_usage.c,v
retrieving revision 1.8
diff -u -p -r1.8 ex_usage.c
--- ex/ex_usage.c 12 Nov 2014 04:28:41 -0000 1.8
+++ ex/ex_usage.c 7 Feb 2018 18:12:52 -0000
@@ -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:
@@ -97,28 +97,13 @@ 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);
+ if (cp == &cmds[C_BG] || cp == &cmds[C_FG] ||
+ cp == &cmds[C_RESIZE])
+ continue;
+ (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:
Index: vi/v_cmd.c
===================================================================
RCS file: /cvs/src/usr.bin/vi/vi/v_cmd.c,v
retrieving revision 1.5
diff -u -p -r1.5 v_cmd.c
--- vi/v_cmd.c 13 Mar 2016 18:30:43 -0000 1.5
+++ vi/v_cmd.c 7 Feb 2018 18:12:52 -0000
@@ -108,9 +108,7 @@ VIKEYS const vikeys [MAXVIKEY + 1] = {
"^V",
"^V input a literal character"},
/* 027 ^W */
- {v_screen, 0,
- "^W",
- "^W move to next screen"},
+ {v_screen, 0, NULL, NULL},
/* 030 ^X */
{NULL},
/* 031 ^Y */
