Fix for vi(1) manpage Visual command

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Fix for vi(1) manpage Visual command

trondd-2
The manpage for vi(1) has a small error for the :Visual/:visual command.  The
'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'. But
the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].

The usage text in vi confirms the correct syntax (as does the roff
documentation).

usr.bin/vi/ex/ex_cmd.c - line 386:

/* C_VISUAL_VI */
        {"visual",      ex_edit,        E_NEWSCREEN,
            "f1o",
            "[Vv]i[sual][!] [+cmd] [file]",
            "edit another file (from vi mode only)"},

Tim.


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 3 Feb 2018 02:02:38 -0000
@@ -2200,7 +2200,7 @@ Enter
 .Nm vi .
 .Pp
 .It Xo
-.Op Cm Vi Ns
+.Op Cm Vv Ns
 .Cm i Ns Op Cm sual Ns
 .Op Cm !\&
 .Op Ar +cmd

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Anthony J. Bentley-4
trondd writes:
> The manpage for vi(1) has a small error for the :Visual/:visual command.  The
> 'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'. Bu
> t
> the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].

This reveals a problem with the manpage. Everywhere else [] refers to
optional parts of a command, but in the EX COMMANDS section, [] does
double duty both to mark multiple valid characters as in glob(7) and to
signify optional parts of the command.

Even in EX COMMANDS [] means "optional" only except for a few commands:
[Ee][dit], [Ee]x, [Ff]g, [Nn][ext], [Pp]rev[ious], [Tt]a[g], and now
[Vv]i[sual].

For readability I think these should be separate lines. Doubly so
because the capitalized commands actually behave differently as
explained in the reference documentation, and NOT explained in the
manpage...

This does leave open the question of how the usage strings in ex_cmd.c
should change, and whether the code there should be rearchitected so
that, e.g., "edit" and "Edit" can have different usage strings.

--
Anthony J. Bentley

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Fri, Feb 02, 2018 at 08:17:11PM -0700, Anthony J. Bentley wrote:

> trondd writes:
> > The manpage for vi(1) has a small error for the :Visual/:visual command.  The
> > 'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'. Bu
> > t
> > the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].
>
> This reveals a problem with the manpage. Everywhere else [] refers to
> optional parts of a command, but in the EX COMMANDS section, [] does
> double duty both to mark multiple valid characters as in glob(7) and to
> signify optional parts of the command.
>
> Even in EX COMMANDS [] means "optional" only except for a few commands:
> [Ee][dit], [Ee]x, [Ff]g, [Nn][ext], [Pp]rev[ious], [Tt]a[g], and now
> [Vv]i[sual].
>
> For readability I think these should be separate lines. Doubly so
> because the capitalized commands actually behave differently as
> explained in the reference documentation, and NOT explained in the
> manpage...
>
> This does leave open the question of how the usage strings in ex_cmd.c
> should change, and whether the code there should be rearchitected so
> that, e.g., "edit" and "Edit" can have different usage strings.
>
> --
> Anthony J. Bentley
>

morning.

can you explain how uppercase and lowercase variants differ? it could be
that the simplest fix is not to list the uppercase variant (e.g. Visual)
and just explain in a separate paragraph those few commands that have
the variant.

but that depends on what the difference is.

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Martijn van Duren-5
When running in ex-mode it sets itself in vi-mode.
When running in vi-mode it's basically an alias to the ex and edit
commands. This means that an uppercase first letter splits the screen
in two.

Personally I find this rather confusing, since we overload the function
to mean two different things based on the mode we're in. Does anyone
actually use the visual command instead of edit?

martijn@

On 02/03/18 08:20, Jason McIntyre wrote:

> On Fri, Feb 02, 2018 at 08:17:11PM -0700, Anthony J. Bentley wrote:
>> trondd writes:
>>> The manpage for vi(1) has a small error for the :Visual/:visual command.  The
>>> 'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'. Bu
>>> t
>>> the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].
>>
>> This reveals a problem with the manpage. Everywhere else [] refers to
>> optional parts of a command, but in the EX COMMANDS section, [] does
>> double duty both to mark multiple valid characters as in glob(7) and to
>> signify optional parts of the command.
>>
>> Even in EX COMMANDS [] means "optional" only except for a few commands:
>> [Ee][dit], [Ee]x, [Ff]g, [Nn][ext], [Pp]rev[ious], [Tt]a[g], and now
>> [Vv]i[sual].
>>
>> For readability I think these should be separate lines. Doubly so
>> because the capitalized commands actually behave differently as
>> explained in the reference documentation, and NOT explained in the
>> manpage...
>>
>> This does leave open the question of how the usage strings in ex_cmd.c
>> should change, and whether the code there should be rearchitected so
>> that, e.g., "edit" and "Edit" can have different usage strings.
>>
>> --
>> Anthony J. Bentley
>>
>
> morning.
>
> can you explain how uppercase and lowercase variants differ? it could be
> that the simplest fix is not to list the uppercase variant (e.g. Visual)
> and just explain in a separate paragraph those few commands that have
> the variant.
>
> but that depends on what the difference is.
>
> jmc
>

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Anthony J. Bentley-4
In reply to this post by Jason McIntyre-2
Jason McIntyre writes:

> On Fri, Feb 02, 2018 at 08:17:11PM -0700, Anthony J. Bentley wrote:
> > trondd writes:
> > > The manpage for vi(1) has a small error for the :Visual/:visual command.
>  The
> > > 'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'
> . Bu
> > > t
> > > the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].
> >
> > This reveals a problem with the manpage. Everywhere else [] refers to
> > optional parts of a command, but in the EX COMMANDS section, [] does
> > double duty both to mark multiple valid characters as in glob(7) and to
> > signify optional parts of the command.
> >
> > Even in EX COMMANDS [] means "optional" only except for a few commands:
> > [Ee][dit], [Ee]x, [Ff]g, [Nn][ext], [Pp]rev[ious], [Tt]a[g], and now
> > [Vv]i[sual].
> >
> > For readability I think these should be separate lines. Doubly so
> > because the capitalized commands actually behave differently as
> > explained in the reference documentation, and NOT explained in the
> > manpage...
> >
> > This does leave open the question of how the usage strings in ex_cmd.c
> > should change, and whether the code there should be rearchitected so
> > that, e.g., "edit" and "Edit" can have different usage strings.
> >
> > --
> > Anthony J. Bentley
> >
>
> morning.
>
> can you explain how uppercase and lowercase variants differ? it could be
> that the simplest fix is not to list the uppercase variant (e.g. Visual)
> and just explain in a separate paragraph those few commands that have
> the variant.
>
> but that depends on what the difference is.

For each of them the capitalized variant opens the result in a new
screen instead of the current screen. (Fg foregrounds to a new screen
instead of swapping with the current screen, Tag opens the tag in a
new screen, etc.) Thus the capitalized variants are only available in
vi, not ex.

Of these, "visual" is different from the others in that in ex mode and
vi mode they are actually separate commands. Hence the current
documentation:

     [line] vi[sual] [type] [count] [flags]
             ex mode only.  Enter vi.

     [Vv]i[sual][!] [+cmd] [file]
             vi mode only.  Edit a new file.

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Sat, Feb 03, 2018 at 03:00:15AM -0700, Anthony J. Bentley wrote:

> Jason McIntyre writes:
> > On Fri, Feb 02, 2018 at 08:17:11PM -0700, Anthony J. Bentley wrote:
> > > trondd writes:
> > > > The manpage for vi(1) has a small error for the :Visual/:visual command.
> >  The
> > > > 'V' can be capital or lowercase, followed by an 'i' and optionally 'sual'
> > . Bu
> > > > t
> > > > the manpage shows the command as [Vi]i[sual] instead of [Vv]i[sual].
> > >
> > > This reveals a problem with the manpage. Everywhere else [] refers to
> > > optional parts of a command, but in the EX COMMANDS section, [] does
> > > double duty both to mark multiple valid characters as in glob(7) and to
> > > signify optional parts of the command.
> > >
> > > Even in EX COMMANDS [] means "optional" only except for a few commands:
> > > [Ee][dit], [Ee]x, [Ff]g, [Nn][ext], [Pp]rev[ious], [Tt]a[g], and now
> > > [Vv]i[sual].
> > >
> > > For readability I think these should be separate lines. Doubly so
> > > because the capitalized commands actually behave differently as
> > > explained in the reference documentation, and NOT explained in the
> > > manpage...
> > >
> > > This does leave open the question of how the usage strings in ex_cmd.c
> > > should change, and whether the code there should be rearchitected so
> > > that, e.g., "edit" and "Edit" can have different usage strings.
> > >
> > > --
> > > Anthony J. Bentley
> > >
> >
> > morning.
> >
> > can you explain how uppercase and lowercase variants differ? it could be
> > that the simplest fix is not to list the uppercase variant (e.g. Visual)
> > and just explain in a separate paragraph those few commands that have
> > the variant.
> >
> > but that depends on what the difference is.
>
> For each of them the capitalized variant opens the result in a new
> screen instead of the current screen. (Fg foregrounds to a new screen
> instead of swapping with the current screen, Tag opens the tag in a
> new screen, etc.) Thus the capitalized variants are only available in
> vi, not ex.
>
> Of these, "visual" is different from the others in that in ex mode and
> vi mode they are actually separate commands. Hence the current
> documentation:
>
>      [line] vi[sual] [type] [count] [flags]
>              ex mode only.  Enter vi.
>
>      [Vv]i[sual][!] [+cmd] [file]
>              vi mode only.  Edit a new file.
>

ok, but it does not currently say that. hence the original post:

        [Vi]i[sual]

that seems an obvious mistake, as noted in the original post.

so we could quick-fix that. but now we see that [Vv] itself is
problematic, as also noted. i'd be inclined to say we should just list
them as lowercase commands, and note separately what happens if the
command begins uppercase.

there again, why does the EX COMMANDS section list commands that are
"vi only"?

jmc

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Ingo Schwarze
Hi Jason, hi Anthony,

Jason McIntyre wrote on Sat, Feb 03, 2018 at 02:52:26PM +0000:

> ok, but it does not currently say that. hence the original post:
> [Vi]i[sual]
> that seems an obvious mistake, as noted in the original post.

That section of the manual is full of lies in multiple respects.
I never used split screens, so i never noticed in the past.

> so we could quick-fix that. but now we see that [Vv] itself is
> problematic, as also noted. i'd be inclined to say we should just list
> them as lowercase commands, and note separately what happens if the
> command begins uppercase.

I think the lowercase and uppercase versions are sufficiently different
to document them separately.

> there again, why does the EX COMMANDS section list commands that are
> "vi only"?

Historical misdesign.  Originally, Bill Joy wrote ex(1) for 1BSD in 1977.
Then he wrote vi(1) for 2BSD in 1979.  He completely botched the design
in so far as he kept the concept of "ex commands" and introduced an
additional, completely different concept of "vi commands".  Both
provide distinct, but significantly redundant functionality.

So in vi(1), you can append text to a line using the vi "a" command,
or you can append a new line using the vi "o" command, or you can
append a new line using the ex "a" command, which has completely
different syntax and semantics.

Given that concept of ex commands in vi, even though it originally
emerged as a backward compatibility concept, at some point, ex
commands appeared that can only be used in vi, but not in ex:  KISS!

That said, here is a patch to fix most of the lies in one go.

OK?
  Ingo

P.S.
Note that the concept of screens is not very well thought out.
For example, it interacts very erratically with the concept of
next and previous files from the command line.  I wouldn't mind
completely zapping the concept of split screens from vi(1), it
isn't required by POSIX.  Then again, i won't get myself killed
over the proposal to scrap the feature if anybody wants to keep it.


Index: 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
--- vi.1 22 Aug 2017 20:27:18 -0000 1.74
+++ vi.1 3 Feb 2018 15:54:16 -0000
@@ -1794,19 +1794,22 @@ 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
+Edit a different file.
+.Pp
 .It Xo
-.Op Cm Ee Ns
-.Cm x Ns Op Cm !\&
+.Cm E Ns Op Cm dit Ns | Ns Cm x Ns
+.Op Cm !\&
 .Op Ar +cmd
 .Op Ar file
 .Xc
-Edit a different file.
+.Nm vi
+only.
+Split the screen and edit a different file.
 .Pp
 .It Xo
 .Cm exu Ns Op Cm sage
@@ -1822,14 +1825,15 @@ 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
+only.
+Background the current screen and foreground the specified screen instead.
+.Pp
+.It Cm Fg Op Ar name
 .Nm vi
-mode only.
-Foreground the specified screen.
+only.
+Split the screen and foreground the specified screen.
 .Pp
 .It Xo
 .Op Ar range
@@ -1880,9 +1884,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,12 +1916,20 @@ 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
 Edit the next file from the argument list.
+.Pp
+.It Xo
+.Cm N Ns Op Cm ext Ns
+.Op Cm !\&
+.Op Ar file ...
+.Xc
+.Nm vi
+only.
+Split the screen and edit the next file from the argument list.
 .\" .Pp
 .\" .It Xo
 .\" .Op Ar line
@@ -1933,13 +1945,14 @@ 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 Cm Prev Ns Oo Cm ious Oc Ns Op Cm !\&
+.Nm vi
+only.
+Split the screen and edit the previous file from the argument list.
+.Pp
 .It Xo
 .Op Ar range
 .Cm p Ns Op Cm rint
@@ -1959,7 +1972,7 @@ Append buffer contents to the current li
 .Cm q Ns Op Cm uit Ns
 .Op Cm !\&
 .Xc
-End the editing session.
+End editing the file and close the current screen.
 .Pp
 .It Xo
 .Op Ar line
@@ -1980,10 +1993,10 @@ 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.
+only.
 Grow or shrink the current screen.
 .Pp
 .It Xo
@@ -2132,14 +2145,22 @@ 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
 Edit the file containing the specified tag.
 .Pp
 .It Xo
+.Cm \&Ta Ns Op Cm g Ns
+.Op Cm !\&
+.Ar tagstring
+.Xc
+.Nm vi
+only.
+Split the screen and edit the file containing the specified tag.
+.Pp
+.It Xo
 .Cm tagn Ns Op Cm ext Ns
 .Op Cm !\&
 .Xc
@@ -2195,22 +2216,31 @@ 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
+.Cm Vi Ns Op Cm sual Ns
+.Op Cm !\&
+.Op Ar +cmd
+.Op Ar file
+.Xc
+.Nm vi
+only.
+Split the screen and edit a new file.
+.Pp
+.It Xo
 .Cm viu Ns Op Cm sage
 .Op Ar command
 .Xc
@@ -2231,19 +2261,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 close the current screen.
 .Pp
 .It Xo
 .Op Ar range
@@ -2251,8 +2285,7 @@ Write the file.
 .Op Cm !\&
 .Op Ar file
 .Xc
-Exit the editor,
-writing the file if it has been modified.
+Write the file if it has been modified and close the current screen.
 .Pp
 .It Xo
 .Op Ar range

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Sat, Feb 03, 2018 at 05:26:34PM +0100, Ingo Schwarze wrote:
> Hi Jason, hi Anthony,
>

evening.

> Jason McIntyre wrote on Sat, Feb 03, 2018 at 02:52:26PM +0000:
>
> > ok, but it does not currently say that. hence the original post:
> > [Vi]i[sual]
> > that seems an obvious mistake, as noted in the original post.
>
> That section of the manual is full of lies in multiple respects.
> I never used split screens, so i never noticed in the past.
>
> > so we could quick-fix that. but now we see that [Vv] itself is
> > problematic, as also noted. i'd be inclined to say we should just list
> > them as lowercase commands, and note separately what happens if the
> > command begins uppercase.
>
> I think the lowercase and uppercase versions are sufficiently different
> to document them separately.
>
> > there again, why does the EX COMMANDS section list commands that are
> > "vi only"?
>
> Historical misdesign.  Originally, Bill Joy wrote ex(1) for 1BSD in 1977.
> Then he wrote vi(1) for 2BSD in 1979.  He completely botched the design
> in so far as he kept the concept of "ex commands" and introduced an
> additional, completely different concept of "vi commands".  Both
> provide distinct, but significantly redundant functionality.
>
> So in vi(1), you can append text to a line using the vi "a" command,
> or you can append a new line using the vi "o" command, or you can
> append a new line using the ex "a" command, which has completely
> different syntax and semantics.
>
> Given that concept of ex commands in vi, even though it originally
> emerged as a backward compatibility concept, at some point, ex
> commands appeared that can only be used in vi, but not in ex:  KISS!
>
> That said, here is a patch to fix most of the lies in one go.
>
> OK?
>   Ingo
>
> P.S.
> Note that the concept of screens is not very well thought out.
> For example, it interacts very erratically with the concept of
> next and previous files from the command line.  I wouldn't mind
> completely zapping the concept of split screens from vi(1), it
> isn't required by POSIX.  Then again, i won't get myself killed
> over the proposal to scrap the feature if anybody wants to keep it.
>

thanks for the explanation.

personally i still think it would be simpler to only list these commands
once, but note which subset can take a capital letter (and what that
means). but both ways would fix it and i'm not that fussed. so if you
really prefer to list them twice, fine.

having said that, can of worms, can of worms, there's still stuff like
:exusage and the USD docs to update. so a man page fix will not suffice.

jmc

>
> Index: 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
> --- vi.1 22 Aug 2017 20:27:18 -0000 1.74
> +++ vi.1 3 Feb 2018 15:54:16 -0000
> @@ -1794,19 +1794,22 @@ 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
> +Edit a different file.
> +.Pp
>  .It Xo
> -.Op Cm Ee Ns
> -.Cm x Ns Op Cm !\&
> +.Cm E Ns Op Cm dit Ns | Ns Cm x Ns
> +.Op Cm !\&
>  .Op Ar +cmd
>  .Op Ar file
>  .Xc
> -Edit a different file.
> +.Nm vi
> +only.
> +Split the screen and edit a different file.
>  .Pp
>  .It Xo
>  .Cm exu Ns Op Cm sage
> @@ -1822,14 +1825,15 @@ 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
> +only.
> +Background the current screen and foreground the specified screen instead.
> +.Pp
> +.It Cm Fg Op Ar name
>  .Nm vi
> -mode only.
> -Foreground the specified screen.
> +only.
> +Split the screen and foreground the specified screen.
>  .Pp
>  .It Xo
>  .Op Ar range
> @@ -1880,9 +1884,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,12 +1916,20 @@ 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
>  Edit the next file from the argument list.
> +.Pp
> +.It Xo
> +.Cm N Ns Op Cm ext Ns
> +.Op Cm !\&
> +.Op Ar file ...
> +.Xc
> +.Nm vi
> +only.
> +Split the screen and edit the next file from the argument list.
>  .\" .Pp
>  .\" .It Xo
>  .\" .Op Ar line
> @@ -1933,13 +1945,14 @@ 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 Cm Prev Ns Oo Cm ious Oc Ns Op Cm !\&
> +.Nm vi
> +only.
> +Split the screen and edit the previous file from the argument list.
> +.Pp
>  .It Xo
>  .Op Ar range
>  .Cm p Ns Op Cm rint
> @@ -1959,7 +1972,7 @@ Append buffer contents to the current li
>  .Cm q Ns Op Cm uit Ns
>  .Op Cm !\&
>  .Xc
> -End the editing session.
> +End editing the file and close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar line
> @@ -1980,10 +1993,10 @@ 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.
> +only.
>  Grow or shrink the current screen.
>  .Pp
>  .It Xo
> @@ -2132,14 +2145,22 @@ 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
>  Edit the file containing the specified tag.
>  .Pp
>  .It Xo
> +.Cm \&Ta Ns Op Cm g Ns
> +.Op Cm !\&
> +.Ar tagstring
> +.Xc
> +.Nm vi
> +only.
> +Split the screen and edit the file containing the specified tag.
> +.Pp
> +.It Xo
>  .Cm tagn Ns Op Cm ext Ns
>  .Op Cm !\&
>  .Xc
> @@ -2195,22 +2216,31 @@ 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
> +.Cm Vi Ns Op Cm sual Ns
> +.Op Cm !\&
> +.Op Ar +cmd
> +.Op Ar file
> +.Xc
> +.Nm vi
> +only.
> +Split the screen and edit a new file.
> +.Pp
> +.It Xo
>  .Cm viu Ns Op Cm sage
>  .Op Ar command
>  .Xc
> @@ -2231,19 +2261,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 close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar range
> @@ -2251,8 +2285,7 @@ Write the file.
>  .Op Cm !\&
>  .Op Ar file
>  .Xc
> -Exit the editor,
> -writing the file if it has been modified.
> +Write the file if it has been modified and close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar range
>

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Ingo Schwarze
Hi Jason,

Jason McIntyre wrote on Sat, Feb 03, 2018 at 05:41:01PM +0000:

> personally i still think it would be simpler to only list these commands
> once, but note which subset can take a capital letter (and what that
> means).

I seems you are right, amybe i should believe you the first time
you say something.  See below for an updated patch.

> can of worms, there's still stuff like :exusage

I think that can remain as it is.  It isn't very precise anyway,
with very short half-line descriptions only and not saying how
the ex commands can be abbreviated.  So at least the usage of []
isn't inconsistent in there.

In principle, :exusage ought to be deleted.  It's not the job of a
program to contain documentation.  Documentation belongs in the
manual page, and there it is indeed.  But that's a different matter.

> and the USD docs to update. so a man page fix will not suffice.

I wouldn't bother.  They are not installed, and the base system
doesn't even provide tools to process them.  If we ever decide
to do anything with them, they will require a full check of accuracy
anyway.

Yours,
  Ingo


Index: 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
--- vi.1 22 Aug 2017 20:27:18 -0000 1.74
+++ vi.1 3 Feb 2018 19:04:16 -0000
@@ -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,14 +1815,10 @@ 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.
-Foreground the specified screen.
+only.
+Background the current screen and foreground the specified screen instead.
 .Pp
 .It Xo
 .Op Ar range
@@ -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
 .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 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
@@ -1959,7 +1943,7 @@ Append buffer contents to the current li
 .Cm q Ns Op Cm uit Ns
 .Op Cm !\&
 .Xc
-End the editing session.
+End editing the file and close the current screen.
 .Pp
 .It Xo
 .Op Ar line
@@ -1980,10 +1964,10 @@ 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.
+only.
 Grow or shrink the current screen.
 .Pp
 .It Xo
@@ -2132,8 +2116,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 +2178,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 +2213,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 close the current screen.
 .Pp
 .It Xo
 .Op Ar range
@@ -2251,8 +2237,7 @@ Write the file.
 .Op Cm !\&
 .Op Ar file
 .Xc
-Exit the editor,
-writing the file if it has been modified.
+Write the file if it has been modified and close the current screen.
 .Pp
 .It Xo
 .Op Ar range
@@ -2271,6 +2256,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

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Sat, Feb 03, 2018 at 08:10:14PM +0100, Ingo Schwarze wrote:

> Hi Jason,
>
> Jason McIntyre wrote on Sat, Feb 03, 2018 at 05:41:01PM +0000:
>
> > personally i still think it would be simpler to only list these commands
> > once, but note which subset can take a capital letter (and what that
> > means).
>
> I seems you are right, amybe i should believe you the first time
> you say something.  See below for an updated patch.
>
> > can of worms, there's still stuff like :exusage
>
> I think that can remain as it is.  It isn't very precise anyway,
> with very short half-line descriptions only and not saying how
> the ex commands can be abbreviated.  So at least the usage of []
> isn't inconsistent in there.
>

i think it's worth taking the time to fix. if it gets deleted, that's
another thing, but until then why mislead people? it will be simpler and
clearer just to list lowercase variants.

> In principle, :exusage ought to be deleted.  It's not the job of a
> program to contain documentation.  Documentation belongs in the
> manual page, and there it is indeed.  But that's a different matter.
>
> > and the USD docs to update. so a man page fix will not suffice.
>
> I wouldn't bother.  They are not installed, and the base system
> doesn't even provide tools to process them.  If we ever decide
> to do anything with them, they will require a full check of accuracy
> anyway.
>

actually a fair bit of time has been spent on vi's USD docs. it would be
a shame to let that slip. i'm not saying they're 100% in sync, but why
worsen it? we could have (another) discussion about removing them but
until then, i think it's worth trying to keep this up to date. if
nothing else, it will make someone else's job easier in the future if
they try to check it.

> Yours,
>   Ingo
>

diff reads ok, but one comment:

>
> Index: 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
> --- vi.1 22 Aug 2017 20:27:18 -0000 1.74
> +++ vi.1 3 Feb 2018 19:04:16 -0000
> @@ -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,14 +1815,10 @@ 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.
> -Foreground the specified screen.
> +only.
> +Background the current screen and foreground the specified screen instead.
>  .Pp
>  .It Xo
>  .Op Ar range
> @@ -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
>  .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 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
> @@ -1959,7 +1943,7 @@ Append buffer contents to the current li
>  .Cm q Ns Op Cm uit Ns
>  .Op Cm !\&
>  .Xc
> -End the editing session.
> +End editing the file and close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar line
> @@ -1980,10 +1964,10 @@ 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.
> +only.
>  Grow or shrink the current screen.
>  .Pp
>  .It Xo
> @@ -2132,8 +2116,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 +2178,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 +2213,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 close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar range
> @@ -2251,8 +2237,7 @@ Write the file.
>  .Op Cm !\&
>  .Op Ar file
>  .Xc
> -Exit the editor,
> -writing the file if it has been modified.
> +Write the file if it has been modified and close the current screen.
>  .Pp
>  .It Xo
>  .Op Ar range
> @@ -2271,6 +2256,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 .

it would be better, i think, to emphasise the behaviour rather than the
commands. so i'd do it the other way round:

        It is possible to start a command in a new screen by ...
        This applies to the commands ..., in vi mode only.

like that? again, no biggie.

jmc

>  .Sh SET OPTIONS
>  There are a large number of options that may be set
>  .Pq or unset
>

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Ingo Schwarze
Hi Jason,

Jason McIntyre wrote on Sat, Feb 03, 2018 at 07:23:59PM +0000:
> On Sat, Feb 03, 2018 at 08:10:14PM +0100, Ingo Schwarze wrote:
>> Jason McIntyre wrote on Sat, Feb 03, 2018 at 05:41:01PM +0000:

>>> can of worms, there's still stuff like :exusage

>> I think that can remain as it is.  It isn't very precise anyway,
>> with very short half-line descriptions only and not saying how
>> the ex commands can be abbreviated.  So at least the usage of []
>> isn't inconsistent in there.

> i think it's worth taking the time to fix. if it gets deleted, that's
> another thing, but until then why mislead people? it will be simpler
> and clearer just to list lowercase variants.

See below for a patch to do that.

Note that the man page and :exusage are already out of sync in multiple
respects, mostly in the sense of using gratuitiously different
wordings.  I didn't try to fix that in this patch, to not expand
the scope of the patch beyond what is reasonable, and did not check
whether anything unrelated in there is actually wrong.

>>> and the USD docs to update. so a man page fix will not suffice.

>> I wouldn't bother.  They are not installed, and the base system
>> doesn't even provide tools to process them.  If we ever decide
>> to do anything with them, they will require a full check of accuracy
>> anyway.

> actually a fair bit of time has been spent on vi's USD docs. it would be
> a shame to let that slip. i'm not saying they're 100% in sync, but why
> worsen it? we could have (another) discussion about removing them but
> until then, i think it's worth trying to keep this up to date. if
> nothing else, it will make someone else's job easier in the future if
> they try to check it.

Even if we consider maintaining the USD docs worthwhile, i don't think
that ought to delay fixing the manual page.

> diff reads ok, but one comment:
[...]

>> +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 .

> it would be better, i think, to emphasise the behaviour rather than the
> commands. so i'd do it the other way round:
>
> It is possible to start a command in a new screen by ...
> This applies to the commands ..., in vi mode only.
>
> like that? again, no biggie.

Actually, i don't like that.  That makes it sound as if it were a
general principle applicable to most commands, while it is actually
a non-standard, non-portable, poorly designed and barely working
quirk implemented only for a handful of commands.  So i think
emphasizing the limitations rather than the benefits serves the
users better.  I'd rather discourage it even more, if i could see
a good way to do so without additional verbiage.

Yours,
  Ingo


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 3 Feb 2018 20:10:59 -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,
@@ -262,7 +262,7 @@ EXCMDLIST const cmds[] = {
  {"quit", ex_quit, 0,
     "!",
     "q[uit][!]",
-    "exit ex/vi"},
+    "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,
@@ -407,12 +407,12 @@ EXCMDLIST const cmds[] = {
  {"wq", ex_wq, E_ADDR2_ALL|E_ADDR_ZERODEF,
     "!s",
     "[line [,line]] wq[!] [>>] [file]",
-    "write the file and exit"},
+    "write the file and close the current screen"},
 /* C_XIT */
  {"xit", ex_xit, E_ADDR2_ALL|E_ADDR_ZERODEF,
     "!f1o",
     "[line [,line]] x[it][!] [file]",
-    "exit"},
+    "write if modified and close the current screen"},
 /* 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 3 Feb 2018 20:10:59 -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:
@@ -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();

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Sat, Feb 03, 2018 at 09:28:11PM +0100, Ingo Schwarze wrote:

> Hi Jason,
>
> Jason McIntyre wrote on Sat, Feb 03, 2018 at 07:23:59PM +0000:
> > On Sat, Feb 03, 2018 at 08:10:14PM +0100, Ingo Schwarze wrote:
> >> Jason McIntyre wrote on Sat, Feb 03, 2018 at 05:41:01PM +0000:
>
> >>> can of worms, there's still stuff like :exusage
>
> >> I think that can remain as it is.  It isn't very precise anyway,
> >> with very short half-line descriptions only and not saying how
> >> the ex commands can be abbreviated.  So at least the usage of []
> >> isn't inconsistent in there.
>
> > i think it's worth taking the time to fix. if it gets deleted, that's
> > another thing, but until then why mislead people? it will be simpler
> > and clearer just to list lowercase variants.
>
> See below for a patch to do that.
>

i'll take your word for it that it does what you say ;)

> Note that the man page and :exusage are already out of sync in multiple
> respects, mostly in the sense of using gratuitiously different
> wordings.  I didn't try to fix that in this patch, to not expand
> the scope of the patch beyond what is reasonable, and did not check
> whether anything unrelated in there is actually wrong.
>

agreed

> >>> and the USD docs to update. so a man page fix will not suffice.
>
> >> I wouldn't bother.  They are not installed, and the base system
> >> doesn't even provide tools to process them.  If we ever decide
> >> to do anything with them, they will require a full check of accuracy
> >> anyway.
>
> > actually a fair bit of time has been spent on vi's USD docs. it would be
> > a shame to let that slip. i'm not saying they're 100% in sync, but why
> > worsen it? we could have (another) discussion about removing them but
> > until then, i think it's worth trying to keep this up to date. if
> > nothing else, it will make someone else's job easier in the future if
> > they try to check it.
>
> Even if we consider maintaining the USD docs worthwhile, i don't think
> that ought to delay fixing the manual page.
>

hmm. not that i entirely agree with this sentiment but fair enough, i will
look at updating the USD docs.

> > diff reads ok, but one comment:
> [...]
> >> +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 .
>
> > it would be better, i think, to emphasise the behaviour rather than the
> > commands. so i'd do it the other way round:
> >
> > It is possible to start a command in a new screen by ...
> > This applies to the commands ..., in vi mode only.
> >
> > like that? again, no biggie.
>
> Actually, i don't like that.  That makes it sound as if it were a
> general principle applicable to most commands, while it is actually
> a non-standard, non-portable, poorly designed and barely working
> quirk implemented only for a handful of commands.  So i think
> emphasizing the limitations rather than the benefits serves the
> users better.  I'd rather discourage it even more, if i could see
> a good way to do so without additional verbiage.
>

a good way to do it without adding verbiage would be to not document it!
if it really is a crappy quirk, let's just leave it out then.
i presumed it was all meant to be there...

> Yours,
>   Ingo
>
>
> 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 3 Feb 2018 20:10:59 -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,
> @@ -262,7 +262,7 @@ EXCMDLIST const cmds[] = {
>   {"quit", ex_quit, 0,
>      "!",
>      "q[uit][!]",
> -    "exit ex/vi"},
> +    "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,
> @@ -407,12 +407,12 @@ EXCMDLIST const cmds[] = {
>   {"wq", ex_wq, E_ADDR2_ALL|E_ADDR_ZERODEF,
>      "!s",
>      "[line [,line]] wq[!] [>>] [file]",
> -    "write the file and exit"},
> +    "write the file and close the current screen"},
>  /* C_XIT */
>   {"xit", ex_xit, E_ADDR2_ALL|E_ADDR_ZERODEF,
>      "!f1o",
>      "[line [,line]] x[it][!] [file]",
> -    "exit"},
> +    "write if modified and close the current screen"},
>  /* 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 3 Feb 2018 20:10:59 -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:
> @@ -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();
>

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Ingo Schwarze
Hi Jason,

Jason McIntyre wrote on Sat, Feb 03, 2018 at 08:52:16PM +0000:

> hmm. not that i entirely agree with this sentiment but fair enough,
> i will look at updating the USD docs.

Thanks.  Don't waste your time on that until after commit, of course.

> a good way to do it without adding verbiage would be to not document it!
> if it really is a crappy quirk, let's just leave it out then.

I actually like that idea, it makes the long list of EX COMMANDS
a bit simpler, making the relevant stuff easier to find.

Of course, we still have to say how to get out of split screen
mode when you stumble into it unintentionally - which esily
happens because the colon requires the shift key on many keyboards,
so accidentally hitting ":N" instead of ":n" is not uncommon.

If people like the idea, i'll also fix up :exusage (unless people
want :exusage deleted, which i would of course prefer).

OK?
  Ingo


Index: 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
--- vi.1 22 Aug 2017 20:27:18 -0000 1.74
+++ vi.1 3 Feb 2018 21:14:48 -0000
@@ -1737,11 +1737,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 +1783,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 +1810,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 +1858,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 +1890,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 +1910,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 +1933,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 +1953,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 +2098,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 +2160,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 +2195,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

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Jason McIntyre-2
On Sat, Feb 03, 2018 at 10:28:20PM +0100, Ingo Schwarze wrote:

>
> > a good way to do it without adding verbiage would be to not document it!
> > if it really is a crappy quirk, let's just leave it out then.
>
> I actually like that idea, it makes the long list of EX COMMANDS
> a bit simpler, making the relevant stuff easier to find.
>
> Of course, we still have to say how to get out of split screen
> mode when you stumble into it unintentionally - which esily
> happens because the colon requires the shift key on many keyboards,
> so accidentally hitting ":N" instead of ":n" is not uncommon.
>
> If people like the idea, i'll also fix up :exusage (unless people
> want :exusage deleted, which i would of course prefer).
>
> OK?
>   Ingo
>

pretty much ok me. but:

>
> Index: 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
> --- vi.1 22 Aug 2017 20:27:18 -0000 1.74
> +++ vi.1 3 Feb 2018 21:14:48 -0000
> @@ -1737,11 +1737,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 +1783,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 +1810,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 +1858,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 +1890,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 +1910,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 +1933,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.

as-is, i'd add a comma after "non-standard".

but i wonder if we'd be better just saying "... get out of split-screen
mode." and running for cover? the comment might draw less attention to
itself that way.

your call. ok either way, with exusage fix-up or removal.

jmc

>  .Pp
>  .It Xo
>  .Op Ar line
> @@ -1978,15 +1953,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 +2098,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 +2160,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 +2195,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

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

trondd-2
In reply to this post by Ingo Schwarze
On Sat, February 3, 2018 4:28 pm, Ingo Schwarze wrote:

>
>> a good way to do it without adding verbiage would be to not document it!
>> if it really is a crappy quirk, let's just leave it out then.
>
> I actually like that idea, it makes the long list of EX COMMANDS
> a bit simpler, making the relevant stuff easier to find.
>
> Of course, we still have to say how to get out of split screen
> mode when you stumble into it unintentionally - which esily
> happens because the colon requires the shift key on many keyboards,
> so accidentally hitting ":N" instead of ":n" is not uncommon.
>
> If people like the idea, i'll also fix up :exusage (unless people
> want :exusage deleted, which i would of course prefer).
>
> OK?
>   Ingo
>

Well this is kind of a bummer.  I agree the documentation is inconsistent
and confusing, but once I got past reading the man page, I was so excited
to discover that I could get split screens in base vi without having to
install vim with its extra baggage.  I'm sad that a feature I use
constantly will now become undocumented (if not removed) and hidden from
other's who might find it valuable.

Not to discourage your work.  I'm not the one maintaining vi, and I can go
crawling back to ports for nvi if I need to.

Tim.


Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Raf Czlonka-2
On Sun, Feb 04, 2018 at 12:05:47AM GMT, trondd wrote:

> On Sat, February 3, 2018 4:28 pm, Ingo Schwarze wrote:
> >
> >> a good way to do it without adding verbiage would be to not document it!
> >> if it really is a crappy quirk, let's just leave it out then.
> >
> > I actually like that idea, it makes the long list of EX COMMANDS
> > a bit simpler, making the relevant stuff easier to find.
> >
> > Of course, we still have to say how to get out of split screen
> > mode when you stumble into it unintentionally - which esily
> > happens because the colon requires the shift key on many keyboards,
> > so accidentally hitting ":N" instead of ":n" is not uncommon.
> >
> > If people like the idea, i'll also fix up :exusage (unless people
> > want :exusage deleted, which i would of course prefer).
> >
> > OK?
> >   Ingo
> >
>
> Well this is kind of a bummer.  I agree the documentation is inconsistent
> and confusing, but once I got past reading the man page, I was so excited
> to discover that I could get split screens in base vi without having to
> install vim with its extra baggage.  I'm sad that a feature I use
> constantly will now become undocumented (if not removed) and hidden from
> other's who might find it valuable.
>
> Not to discourage your work.  I'm not the one maintaining vi, and I can go
> crawling back to ports for nvi if I need to.
>
> Tim.

I have to second Tim here - I like base vi/ex the way it is.

Very recently, I found a file where I had saved the output of both
:visuage and :exusage - this was from a time when I had noticed as
small alignment issue in :viusage.  I actually learnt a handful
of commands form both of these and would be sad to see either of
them go.  Personally, I don't treat them as *documentation* sensu
stricto, but more like a quick command guide - an index.

All that being said, I'm obviously in no position to make requests
- merely £0.02 from a base vi user and one who found :{ex,vi}usage
actually useful in the past.

Raf

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Anthony J. Bentley-4
In reply to this post by Ingo Schwarze
Ingo Schwarze writes:
> > and the USD docs to update. so a man page fix will not suffice.
>
> I wouldn't bother.  They are not installed, and the base system
> doesn't even provide tools to process them.  If we ever decide
> to do anything with them, they will require a full check of accuracy
> anyway.

I am not interested in updating the USD docs, but we *should* continue
to migrate information from them to the manpage. Many user-facing parts
of vi are not adequately documented right now except in there.

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Ingo Schwarze
In reply to this post by Jason McIntyre-2
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 */

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Claudio Jeker
On Wed, Feb 07, 2018 at 07:28:42PM +0100, Ingo Schwarze wrote:

> 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.

I normaly use :Vi or :E for screen splitting. They have less issues than
:N (:n and :prev are funky anyway)
 
>  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...

I don't agree with 2. Especially if you want to copy paste between to
files using the screen splitting is nice since you can yank a block in on
window and paste it in the other.
 
> Here is a comprehensive diff removing the related clutter from
> the manual page and from :exusage and :viusage.
>
> OK?

I don't like this.

>   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 */
>

--
:wq Claudio

Reply | Threaded
Open this post in threaded view
|

Re: Fix for vi(1) manpage Visual command

Christian Weisgerber
On 2018-02-07, Claudio Jeker <[hidden email]> wrote:

> On Wed, Feb 07, 2018 at 07:28:42PM +0100, Ingo Schwarze wrote:
>> 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.
>
> I don't agree with 2. Especially if you want to copy paste between to
> files using the screen splitting is nice since you can yank a block in on
> window and paste it in the other.
>
> I don't like this.

Neither do I.  I'm in agreement with Claudio.

--
Christian "naddy" Weisgerber                          [hidden email]

12