freebsd-skq/usr.bin/vi/docs/README

#	@(#)README	8.84 (Berkeley) 8/15/94

This is the README for version 1.32 of nex/nvi, a freely redistributable
replacement for the Berkeley ex and vi text editors.  The compressed or
gzip'd archive, for this and future versions, can be retrieved by using
anonymous ftp to ftp.cs.berkeley.edu, from the file ucb/4bsd/nvi.tar.Z,
or ucb/4bsd/nvi.tar.gz.

If you have any questions about nvi, or problems making it work, please
contact me by electronic mail at one of the following addresses:

	uunet!bostic
	bostic@cs.berkeley.edu

Keith Bostic

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
o Redistribution:

This software is copyrighted by the The Regents of the University of
California, but may be freely redistributed (or sold, or used to line
your birdcage) under the following conditions:

/*-
 * Copyright (c) 1991, 1992, 1993, 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.
 */

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
o Credit where it's due:

	This software was originally derived from software contributed
	to the University of California, Berkeley by Steve Kirkendall,
	the author of the vi clone elvis.  Without his work, this work
	would have been far more difficult.

	POSIX 1003.2 style regular expression support is courtesy of
	Henry Spencer, for which I am *very* grateful.

	The curses library was originally done by Ken Arnold.  Scrolling
	and general reworking for 4.4BSD was done by Elan Amir.

o From the original vi acknowledgements, by William Joy and Mark Horton:

	Bruce Englar encouraged the early development of this display
	editor.  Peter Kessler helped bring sanity to version 2's
	command layout.  Bill Joy wrote versions 1 and 2.0 through 2.7,
	and created the framework that users see in the present editor.
	Mark Horton added macros and other features and made the editor
	work on a large number of terminals and Unix systems.

o And...
	The financial support of UUNET Communications Services is gratefully
	acknowledged.

=-=-=-=-=-=-=-=-=-=-=
o Status:

This software is in beta test, and it's pretty stable.  Almost all of
the historic functionality in ex/vi is there, the only major missing
pieces are open mode and the lisp option.  (Also, the options hardtabs,
optimize, redraw, and slowopen are recognized, but ignored.)

Nvi is mostly 8-bit clean.  This isn't difficult to fix, and was left
in during initial development to keep things simple.  Wide character
support will be integrated at the same time that it is made fully 8-bit
clean.

There aren't a lot of new features in nex/nvi, but there are a few things
you might like.  The "Additional Features" section of the reference page
(USD.doc/vi.ref/vi.ref.txt, USD.doc/vi.ref/vi.ref.ps) has more information.

=-=-=-=-=-=-=-=-=-=-=
o Porting information:

The directory "PORT" has directories for specific OS/machine combinations,
including V7-style Makefiles, for building nex/nvi on different machines.
See the file PORT/README for detailed information.

=-=-=-=-=-=-=-=-=-=-=
o Debugging:

Code fixes are appreciated, of course, but if you can't provide them,
please email me as much information as you can as to how to reproduce
the bug, and I'll try to fix it locally.  Stack traces of core dumps
are only rarely helpful -- an example file with a set of keystrokes that
causes the problem is almost invariably necessary.

Please include the following in the bug report;

	o The version of nvi you're running (use :version to get it).
	o The row/column dimensions of the screen (80 x 32).
	o Unless you're confident that they're not part of the problem,
	  your startup files (.exrc, .nexrc) and the environment variable
	  (EXININT, NEXINIT) values.  (Cutting and pasting the output
	  of ":set all" is usually sufficient.)

If you're running a memory checker (e.g. Purify) on nvi, you will want
to  recompile everything with "-DPURIFY" in the CFLAGS, first.  By
default, allocated pages are not initialized by the DB code, and they
will show up as reads of uninitialized memory in the buffer write routines.

=-=-=-=-=-=-=-=-=-=-=
o Directory layout:

nvi/USD.doc:
	Ex/vi documentation, both historic and current.

	edit/		Roff source for "Edit: A tutorial", USD:14 in the
			4.3BSD manuals.
	ex/		Roff source for "Ex Reference Manual -- Version
			3.7", USD:16 in the 4.3BSD manuals.
	vi/		Roff source for "An Introduction to Display
			Editing with Vi", USD:15 in the 4.3BSD manuals.
			Includes the "Vi Quick Reference" card.
	vi.man/		Manual page for nex/nvi; an updated version of
			the document distributed with 4.4BSD-Lite.
	vi.ref/		Reference document for nex/nvi; an updated version
			of the document distributed with 4.4BSD-Lite.

nvi/common:
	Source files for pieces of code that are shared by all the editors,
	like searching and logging code or code translating line numbers
	into requests to the dbopen(3) database code.  It also has the
	interface code for modifying "records" in the underlying database.

nvi/docs:
	Random nvi documentation:

	README		-- Nvi main README file.
	bugs.current	-- Major known bugs in the current nvi.
	changelog	-- Log of changes from version to version.
	features	-- Todo list, suggested features list.
	internals/
	    autowrite	-- Vi autowrite option discussion.
	    gdb.script	-- GDB debugging scripts.
	    input	-- Vi maps, executable buffers, and input discussion.
	    quoting	-- Vi quoting discussion.
	    structures	-- Out-of-date nvi internal structure description.
	tutorial/	-- Historic vi tutorial(s), of unknown quality.

nvi/ex:
	The ex source code.  Because vi has the colon command, lots of
	this code is used by vi.  Generally, if functionality is shared
	by both ex and vi, it's in nvi/ex.  If it's vi only, it's in
	nvi/vi.  Files are generally named by the command(s) they support,
	but occasionally with a name that describes their functionality.

nvi/install:
	Things to install on the local system.

	recover.script	-- Vi recovery script.

nvi/PORT:
	Porting directories, one per OS/architecture combination.  See
	nvi/PORT/README for porting information.

	curses/		-- 4.4BSD curses implementation
	db/		-- 4.4BSD DB routines.
	regex/		-- Henry Spencer's POSIX.2 RE support.

nvi/sex:
	The screen support for the ex editor.

nvi/svi:
	The screen support for a curses based vi editor.

nvi/vi:
	The vi source code.

nvi/xaw:
	Place reserved for an X11 (Athena Widget) screen.