doc.sh

操作系统源代码

XTo add text, you must specify
Xthe text to insert (as a NUL-terminated string)
Xand the place to insert it (as a mark).
XThe block into which the text is to be inserted may need to be split into
Xas many as four blocks, with new intervening blocks needed as well...
Xor it could be as simple as modifying a single block.
XThis is implemented in the function \fBadd()\fR.
X.PP
XThere is also a \fBchange()\fR function,
Xwhich generally just calls delete() and add().
XFor the special case where a single character is being replaced by another
Xsingle character, though, change() will optimize things somewhat.
XThe add(), delete(), and change() functions are all defined in "modify.c".
X.PP
XThe \fBinput()\fR function reads text from a user and inserts it into the file.
XIt makes heavy use of the add(), delete(), and change() functions.
XIt inserts characters one at a time, as they are typed.
X.PP
XWhen text is modified, an internal file-revision counter, called \fBchanges\fR,
Xis incremented.
XThis counter is used to detect when certain caches are out of date.
X(The "changes" counter is also incremented when we switch to a different file,
Xand also in one or two similar situations -- all related to invalidating caches.)
X.NH 2
XMarks and the Cursor
X.PP
XMarks are places within the text.
XThey are represented internally as 32-bit values which are split
Xinto two bitfields:
Xa line number and a character index.
XLine numbers start with 1, and character indexes start with 0.
XLines can be up to 1023 characters long, so the character index is 10 bits
Xwide and the line number fills the remaining 22 bits in the long int.
X.PP
XSince line numbers start with 1,
Xit is impossible for a valid mark to have a value of 0L.
X0L is therefore used to represent unset marks.
X.PP
XWhen you do the "delete text" change, any marks that were part of
Xthe deleted text are unset, and any marks that were set to points
Xafter it are adjusted.
XMarks are adjusted similarly after new text is inserted.
X.PP
XThe cursor is represented as a mark.
X.NH 2
XColon Command Interpretation
X.PP
XColon commands are parsed, and the command name is looked up in an array
Xof structures which also contain a pointer to the function that implements
Xthe command, and a description of the arguments that the command can take.
XIf the command is recognized and its arguments are legal,
Xthen the function is called.
X.PP
XEach function performs its task; this may cause the cursor to be
Xmoved to a different line, or whatever.
X.NH 2
XScreen Control
X.PP
XIn input mode or visual command mode,
Xthe screen is redrawn by a function called \fBredraw()\fR.
XThis function is called in the getkey() function before each keystroke is
Xread in, if necessary.
X.PP
XRedraw() write to the screen via a package which looks like the "curses"
Xlibrary, but isn't.
XIt is actually much simpler.
XMost curses operations are implemented as macros which copy characters
Xinto a large I/O buffer, which is then written with a single large
Xwrite() call as part of the refresh() operation.
X.PP
X(Note: Under MS-DOS, the pseudo-curses macros check to see whether you're
Xusing the pcbios interface.  If you are, then the macros call functions
Xin "pc.c" to implement screen updates.)
X.PP
XThe low-level functions which modify text (namely add(), delete(), and change())
Xsupply redraw() with clues to help redraw() decide which parts of the
Xscreen must be redrawn.
XThe clues are given via a function called \fBredrawrange()\fR.
X.PP
XMost EX commands use the pseudo-curses package to perform their output,
Xlike redraw().
X.PP
XThere is also a function called \fBmsg()\fR which uses the same syntax as printf().
XIn EX mode, msg() writes message to the screen and automatically adds a
Xnewline.
XIn VI mode, msg() writes the message on the bottom line of the screen
Xwith the "standout" character attribute turned on.
X.NH 2
XOptions
X.PP
XFor each option available through the ":set" command,
X\*E contains a character array variable, named "o_\fIoption\fR".
XFor example, the "lines" option uses a variable called "o_lines".
X.PP
XFor boolean options, the array has a dimension of 1.
XThe first (and only) character of the array will be NUL if the
Xvariable's value is FALSE, and some other value if it is TRUE.
XTo check the value, just by dereference the array name,
Xas in "if (*o_autoindent)".
X.PP
XFor number options, the array has a dimension of 3.
XThe array is treated as three unsigned one-byte integers.
XThe first byte is the current value of the option.
XThe second and third bytes are the lower and upper bounds of that
Xoption.
X.PP
XFor string options, the array usually has a dimension of about 60
Xbut this may vary.
XThe option's value is stored as a normal NUL-terminated string.
X.PP
XAll of the options are declared in "opts.c".
XMost are initialized to their default values;
Xthe \fBinitopts()\fR function is used to perform any environment-specific
Xinitialization.
X.NH 2
XPortability
X.PP
XTo improve portability, \*E collects as many of the system-dependent
Xdefinitions as possible into the "config.h" file.
XThis file begins with some preprocessor instructions which attempt to
Xdetermine which compiler and operating system you have.
XAfter that, it conditionally defines some macros and constants for your system.
X.PP
XOne of the more significant macros is \fBttyread()\fR.
XThis macro is used to read raw characters from the keyboard, possibly
Xwith timeout.
XFor UNIX systems, this basically reads bytes from stdin.
XFor MSDOS, TOS, and OS9, ttyread() is a function defined in curses.c.
XThere is also a \fBttywrite()\fR macro.
X.PP
XThe \fBtread()\fR and \fBtwrite()\fR macros are versions of read() and write() that are
Xused for text files.
XOn UNIX systems, these are equivelent to read() and write().
XOn MS-DOS, these are also equivelent to read() and write(),
Xsince DOS libraries are generally clever enough to convert newline characters
Xautomatically.
XFor Atari TOS, though, the MWC library is too stupid to do this,
Xso we had to do the conversion explicitly.
X.PP
XOther macros may substitute index() for strchr(), or bcopy() for memcpy(),
Xor map the "void" data type to "int", or whatever.
X.PP
XThe file "tinytcap.c" contains a set of functions that emulate the termcap
Xlibrary for a small set of terminal types.
XThe terminal-specific info is hard-coded into this file.
XIt is only used for systems that don't support real termcap.
XAnother alternative for screen control can be seen in
Xthe "curses.h" and "pc.c" files.
XHere, macros named VOIDBIOS and CHECKBIOS are used to indirectly call
Xfunctions which perform low-level screen manipulation via BIOS calls.
X.PP
XThe stat() function must be able to come up with UNIX-style major/minor/inode
Xnumbers that uniquely identify a file or directory.
X.PP
XPlease try to keep you changes localized,
Xand wrap them in #if/#endif pairs,
Xso that \*E can still be compiled on other systems.
XAnd PLEASE let me know about it, so I can incorporate your changes into
Xmy latest-and-greatest version of \*E.
/
echo x - intro.ms
sed '/^X/s///' > intro.ms << '/'
X.Go 1 "INTRODUCTION"
X.PP
X\*E is a clone of vi/ex, the standard UNIX editor.
X\*E supports nearly all of the vi/ex commands,
Xin both visual mode and colon mode.
X.PP
XLike vi/ex, \*E stores most of the text in a temporary file, instead of RAM.
XThis allows it to edit files that are too large to fit
Xin a single process' data space.
XAlso, the edit buffer can survive a power failure or crash.
X.PP
X\*E runs under BSD UNIX, AT&T SysV UNIX, Minix, MS-DOS, Atari TOS,
XCoherent, OS9/68000, VMS and AmigaDos.
XThe next version is also expected to add MS-Windows, OS/2 and MacOS.
XContact me before you start porting it to some other OS,
Xbecause somebody else may have already done it for you.
X.PP
X\*E is freely redistributable, in either source form or executable form.
XThere are no restrictions on how you may use it.
X.NH 2
XCompiling
X.PP
XSee the "Versions" section of this manual for instructions on how to compile
X\*E.
X.PP
XIf you want to port \*E to another O.S. or compiler, then
Xyou should start be reading the "Portability" part of the "Internal" section.
X.NH 2
XOverview of \*E
X.PP
XThe user interface of \*E/vi/ex is weird.
XThere are two major command modes in \*E, and a few text input modes as well.
XEach command mode has a command which allows you to switch to the other mode.
X.PP
XYou will probably use the \fIvisual command mode\fR
Xmost of the time.
XThis is the mode that \*E normally starts up in.
X.PP
XIn visual command mode, the entire screen is filled with lines of text
Xfrom your file.
XEach keystroke is interpretted as part of a visual command.
XIf you start typing text, it will \fInot\fR be inserted,
Xit will be treated as part of a command.
XTo insert text, you must first give an "insert text" command.
XThis will take some getting used to.
X(An alternative exists.
XLookup the "inputmode" option.)
X.PP
XThe \fIcolon mode\fR is quite different.
X\*E displays a ":" character on the bottom line of the screen, as a prompt.
XYou are then expected to type in a command line and hit the <Return> key.
XThe set of commands recognized in the colon mode is different
Xfrom visual mode's.
/
echo x - options.ms
sed '/^X/s///' > options.ms << '/'
X.Go 5 "OPTIONS"
X.PP
XOptions may be set or examined via the colon command "set".
XThe values of options will affect the operation of later commands.
X.PP
XFor convenience, options have both a long descriptive name and a short name
Xwhich is easy to type.
XYou may use either name interchangably.
XI like the short names, myself.
X.PP
XThere are three types of options: Boolean, string, and numeric.
XBoolean options are made TRUE by giving the name of the option as an
Xargument to the "set" command;
Xthey are made FALSE by prefixing the name with "no".
XFor example, "set autoindent" makes the autoindent option TRUE,
Xand "set noautoindent" makes it FALSE.
X\*E also allows boolean options to be toggled by prefixing the name with "neg".
XSo, ":map g :set neglist^M" will cause the <g> key to alternately toggle the
X"list" option on and off.
X(The "neg" prefix is an extension; the real vi doesn't support it.)
X.PP
XTo change the value of a string or numeric option, pass the "set" command
Xthe name of the option, followed by an "=" sign and the option's new value.
XFor example, "set tabstop=8" will give the tabstop option a value of 8.
XFor string options, you may enclose the new value in quotes.
X.LD
X.ta 1.9i 2.4i 3.8i
X.ps +2
X\fBNAMES	TYPE	DEFAULT	MEANING\fP
X.ps
Xautoindent, ai	Bool	noai	auto-indent during input
Xautoprint, ap	Bool	ap	in EX, print the current line
Xautotab, at	Bool	at	auto-indent allowed to use tabs?
Xautowrite, aw	Bool	noaw	auto-write when switching files
Xbeautify,  bf	Bool	nobf	strip control chars from file?
Xcharattr, ca	Bool	noca	interpret \\fX sequences?
Xcc, cc	Str	cc="cc -c"	name of the C compiler
Xcolumns, co	Num	co=80	width of the screen
Xdigraph, dig	Bool	nodig	recognize digraphs?
Xdirectory, dir	Str	dir="/usr/tmp"	where tmp files are kept
Xedcompatible, ed	Bool	noed	remember ":s//" options
Xequalprg, ep	Bool	ep="fmt"	program to run for = operator
Xerrorbells, eb	Bool	eb	ring bell on error
Xexrc, exrc	Bool	noexrc	read "./.exrc" file?
Xexrefresh, er	Bool	er	write lines indiviually in EX
Xflash, vbell	Bool	flash	use visible alternative to bell
Xflipcase, fc	Str	fc=""	non-ASCII chars flipped by ~
Xhideformat, hf	Bool	hf	hide text formatter commands
Xignorecase, ic	Bool	noic	upper/lowercase match in search
Xinputmode, im	Bool	noim	start vi in insert mode?
Xkeytime, kt	Num	kt=2	timeout for mapped key entry
Xkeywordprg, kp	Str	kp="ref"	full pathname of shift-K prog
Xlines, ln	Num	ln=25	number of lines on the screen
Xlist, li	Bool	noli	display lines in "list" mode
Xmagic, ma	Bool	ma	use regular expression in search
Xmake, mk	Str	mk="make"	name of the "make" program
Xmesg, ms	Bool	ms	allow messages from other users?
Xmodelines, ml	Bool	noml	are modelines processed?
Xmore, more	Bool	more	pause between messages?
Xnovice, nov	Bool	nonovice	set options for ease of use
Xparagraphs, para	Str	para="PPppIPLPQP"	names of "paragraph" nroff cmd
Xprompt, pr	Bool	pr	show ':' prompt in \fIex\fR mode
Xreadonly, ro	Bool	noro	prevent overwriting of orig file
Xremap, rem	Bool	remap	allow key maps to call key maps
Xreport, re	Num	re=5	report when 5 or more changes
Xruler, ru	Bool	noru	display line/column numbers
Xscroll, sc	Num	sc=12	scroll amount for ^U and ^D
Xsections, sect	Str	sect="NHSHSSSEse"	names of "section" nroff cmd
Xshell, sh	Str	sh="/bin/sh"	full pathname of the shell
Xshowmatch, sm	Bool	nosm	show matching ()[]{}
Xshowmode, smd	Bool	nosmd	say when we're in input mode
Xshiftwidth, sw	Num	sw=8	shift amount for < and >
Xsidescroll, ss	Num	ss=8	amount of sideways scrolling
Xsync, sy	Bool	nosy	call sync() often
Xtabstop, ts	Num	ts=8	width of tab characters
Xtaglength, tl	Num	tl=0	significant chars in tag name
Xterm, te	Str	te="$TERM"	name of the termcap entry
Xterse, tr	Bool	notr	give shorter error messages
Xtimeout, to	Bool	to	distinguish <esc> from <arrow>?
Xwarn, wa	Bool	wa	warn for ! if file modified
Xwindow, wi	Num	wi=24	lines to redraw after long move
Xwrapmargin, wm	Num	wm=0	wrap long lines in input mode
Xwrapscan, ws	Bool	ws	at EOF, searches wrap to line 1
Xwriteany, wr	Bool	nowr	allow :w to clobber files
X.DE
X.TA
X.ne 6
X.IP "autoindent, ai"
XDuring input mode, the autoindent option will cause each added line
Xto begin with the same amount of leading whitespace as the line above it.
XWithout autoindent, added lines are initially empty.
X.IP "autoprint, ap"
XThis option only affects EX mode.
XIf the autoprint option on,
Xand either the cursor has moved to a different line
Xor the previous command modified the file,
Xthen \*E will print the current line.
X.IP "autotab, at"
XThis option affects the behaviour of the autoindent mode.
XIf autoindent is turned off, then autotab has no effect.
X.IP
XWhen autotab is turned on, elvis will use a mixture of spaces and tabs
Xto create the proper amount of indentation.
XThis is the default.
X.IP
XWhen autotab is turned off, elvis will only use spaces for auto-indent.
X\*E will still insert a real tab character when you hit the <Tab> key, though;
Xthe autotab option only affects \fIautomatic\fR indentation.
X.IP "autowrite, aw"
XWhen you're editing one file and decide to switch to another
X\- via the :tag command, or :next command, perhaps \-
Xif your current file has been modified,
Xthen \*E will normally print an erro