This commit was generated by cvs2svn to track changes on a CVS vendor

[unix-history] / usr.bin / vi / vi.1

.\" Copyright (c) 1994
.\"     The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)vi.1	8.7 (Berkeley) 1/23/94
.\"
.Dd "January 23, 1994"
.Dt EX/VI 1
.Os
.Sh Name
.Nm ex, vi, view
.Nd text editors
.Sh SYNOPSIS
.Nm vi
.Op Fl eFlRv
.Op Fl c Ar command
.Op Fl r Ar file
.Op Fl t Ar tag
.Op Fl w Ar size
.Op Fl x Ar aw
.br
.Nm view
.Op Fl eFlRv
.Op Fl c Ar command
.Op Fl r Ar file
.Op Fl t Ar tag
.Op Fl w Ar size
.Op Fl x Ar aw
.br
.Nm ex
.Op Fl eFlRsv
.Op Fl c Ar command
.Op Fl r Ar file
.Op Fl t Ar tag
.Op Fl w Ar size
.Op Fl x Ar aw
.Sh DESCRIPTION
.Nm "Ex"
is a line-oriented text editor.
.Nm Vi
is a screen oriented text editor, based on
.Nm ex .
.Nm View
is the same as using the
.Fl R
(read-only) option of
.Nm vi .
.Nm "Ex"
and
.Nm vi
are really different interfaces to the same program,
and it is possible to switch back and forth during the same edit session.
.Pp
This manual page is the one provided with the
.Nm nex
and
.Nm nvi
versions of the vi text editors.
.Nm Nex
and
.Nm nvi
are intended as bug-for-bug compatible replacements for the original
Fourth Berkeley Software Distribution (4BSD)
.Nm ex
and
.Nm vi
programs.
.Pp
The following options are available:
.Bl -tag -width indent
.It Fl c
Execute
.Ar command
immediately after starting the edit session.
Useful for initial positioning in the file, but
.Ar command
is not limited to positioning commands.
This is the POSIX 1003.2 interface for the historic
.Dq "+command"
syntax.
.Nm Nex/nvi
supports both the old and new syntax.
.It Fl e
Start editing in ex mode, as if the command name was
.Nm ex .
.It Fl F
Don't copy the entire file when first starting to edit.
(The default is to make a copy in case someone else tries to edit
the file too.)
.It Fl l
List the files that may be recovered using the
.Fl r
option of
.Nm vi .
This is the new interface for the historic
.Fl r
without a file argument syntax.
.Nm Nex/nvi
supports both the old and new syntax.
.It Fl R
Start editing in read-only mode, as if the command name was
.Nm view .
.It Fl r
Recover the specified file.
.It Fl s
Enter batch mode; applicable only to
.Nm ex
edit sessions.
Batch mode is useful when running
.Nm ex
scripts.
Prompts, informative messages and other user oriented things are
turned off.
This is the POSIX 1003.2 interface for the historic
.Fl \-
syntax.
.Nm Nex/nvi
supports both the old and new syntax.
.It Fl t
Start editing at the specified tag.
(See
.Xr ctags 1 ).
.It Fl w
Set the initial window size to the specified number of lines.
.It Fl v
Start editing in vi mode, as if the command name was
.Nm vi
or
.Nm view .
.It Fl x
Reserved for X11 interfaces.
Not currently implemented.
.Sh ADDITIONAL FEATURES
This manual page is the one distributed with the
.Nm nvi
and
.Nm nex
reimplementations of
.Nm ex/vi .
There are a few additional features in
.Nm nex/nvi .
.Bl -tag -width indent
.It "8-bit clean data, large lines, files"
.Nm Nvi/nex
will edit any format file.
Line lengths are limited by available memory,
and file sizes are limited by available disk space.
The command
.Dq "^Vx[0-9A-Fa-f]* ,"
in input mode, will insert any
legal character value into the text.
.It "Split screens"
The command
.Dq ":sp[lit] [file ...]"
splits the screen in vi mode.
The key
.Dq "^W"
switches between the foreground screens,
and the
.Dq ":resize count"
command can be used to grow or shrink any
particular screen.
.It "Background and foreground screens"
The command
.Dq ":bg"
backgrounds the current screen,
and the command
.Dq ":fg [file]"
foregrounds the backgrounded screeen
that is editing the specified file, or, by default, the first background
screen on the queue.
The command
.Dq ":di[splay] s[creens]"
lists the background screens.
.It "Shell screens"
The command
.Dq ":sc[ript] [file ...]"
runs a shell in the screen.
Editing is unchanged, with the exception that a <carriage-return>
enters the current line (stripped of any prompt) as input to the
shell.
.It "Tag stacks"
Tags are now maintained in a stack.
The command
.Dq "^T"
returns to the previous tag location.
The command
.Dq ":tagpop [number \| file]"
returns to the most recent tag
location by default, or, optionally to a specific tag number in the
tag stack, or the most recent tag from the specified file.
Use the command
.Dq ":di[splay] t[ags]"
to view the tags stack.
The command
.Dq ":tagtop"
returns to the top of the tag stack.
.It "New displays"
The command
.Dq ":di[splay] b[uffers] \| s[creens] \| t[ags]"
can be
used to display, respectively, the current cut buffers,
the backgrounded screens, and the tags stack.
.It "Infinite undo"
The changes made during an edit session may be rolled backward and
forward.
A '.' command immediately after a 'u' command continues either forward
or backward depending on whether the 'u' command was an undo or a redo.
.It "Usage information"
The command
.Dq ":exu[sage [cmd]"
and
.Dq "viu[sage] [key]"
provide usage
information for all of the ex and vi commands by default, or, optionally,
for a specific command or key.
.It "Extended regular expressions"
The
.Dq ":set extended"
command treats search and other command regular
expressions as extended (egrep(1) style) regular expressions.
.It "Word search"
The command
.Dq "^A"
searches for the word referenced by the cursor.
.It "Number increment"
The command
.Dq "#"
increments the number referenced by the cursor.
.It "Previous file"
The command
.Dq ":prev[ious][!]"
edits the previous file from the
argument list.
.It "Left-Right scrolling"
The command
.Dq ":set leftright"
makes
.Nm nvi
do left-right screen scrolling, instead of the traditional
.Nm vi
line wrapping.
.Sh RECOVERY
There is no recovery program for nvi, nor does it run setuid.
Users may recover any file which they may read, and the superuser
may recover any edit session.
.Pp
Edit sessions are backed by files in
.Pa /var/tmp/vi.recover ,
and are named
.Dq "vi.XXXX" ,
where
.Dq "XXXX"
is a number related to the process id.
When a file is first modified, a second file, which contains an
email message for the user, is created, and is named
.Dq "recover.XXXX" ,
where, again,
.Dq "XXXX"
is associated with the process id.
Both files are removed at the end of a normal edit session,
but will remain if the edit session is abnormally terminated
or the user enters the ex/vi
.Dq "preserve"
command.
The use of the
.Pa /var/tmp
directory may be changed setting the option
.Dq "recdir"
in the user's or system startup information.
.Pp
The recovery directory should have the
.Dq "sticky-bit"
set so that only the owners of files may remove them.
If this is not possible on the system, then a pseudo-user should
own the recovery directory.
The recovery directory must be both read and write-able by
any user.
.Pp
The recovery file has all of the necessary information in it to enable the
user to recover the edit session.
In addition, it has all of the necessary email headers for sendmail.
When the system is rebooted, all of the files in
.Pa /var/tmp/vi.recover
named
.Dq "recover.XXXX"
should be sent by email,
using the
.Fl t
flag of sendmail (or a similar mechanism in other mailers).
A simple way to do this is to insert the following script into your
rc.local (or other startup) file:
.sp
.ne 7v
.Bd -literal -offset indent -compact
# Recover nvi editor files.
virecovery=/var/tmp/vi.recover/recover.*
if [ "$virecovery" != "/var/tmp/vi.recover/recover.*" ]; then
	echo 'Recovering vi editor sessions'
	for i in $virecovery; do
		sendmail -t < $i
	done
fi
.Ed
.Pp
If
.Nm nex/nvi
receives a hangup (SIGHUP) signal, it will email the recovery
information to the user itself.
.Pp
If you don't have the sendmail program on your system, the source file
.Pa nvi/recover.c
will have to be modified to use your mail delivery programs.
.Sh BUGS
This man page is woefully incomplete.
.Pp
Many and varied.
See the file
.Pa nvi/docs/bugs.current
for a list of the known bugs in this version.
.Sh FILES
.Bl -tag -width XXXX/var/tmp/vi.recover -compact
.It Pa /tmp
Storage for temporary files.
.It Pa /var/tmp/vi.recover
Storage for recovery files.
.El
.Sh SEE ALSO
.Xr ctags 1 ,
.Xr more 1 ,
.Xr curses 3 ,
.Xr dbopen 3
.sp
The
.Dq "Vi Quick Reference"
card.
.sp
.Dq "An Introduction to Display Editing with Vi" ,
found in the
.Dq "UNIX User's Manual Supplementary Documents" .
.sp
.Dq "Edit: A tutorial" ,
found in the
.Dq "UNIX User's Manual Supplementary Documents" .
.sp
.Dq "Ex Reference Manual (Version 3.7)" ,
found in the
.Dq "UNIX User's Manual Supplementary Documents" .
.Pp
.Nm Nroff/troff
source for the previous three documents are distributed with
.Nm nex/nvi
in the
.Pa nvi/docs/USD.doc
directory of the
.Nm nex/nvi
source code.
.sp
The files
.Dq "autowrite" ,
.Dq "input" ,
and
.Dq "quoting" ,
found in the
.Pa nvi/docs
directory of the
.Nm nex/nvi
source code.
.Sh HISTORY
The
.Nm nex/nvi
replacements for
.Nm ex/vi
first appeared in 4.4BSD.
.Sh STANDARDS
.Nm Nex/nvi
is fairly close to IEEE Std1003.2 (``POSIX''), but it's
not there yet.