   (C) Copyright 1988, Software by Sagredo, "est Omnibus"
  
  	this product may be freely used, duplicated and distributed
  	provided that no charge is made for this code, and that this
  	copyright notice is preserved in all copies and derivative works.
  

full-screen editor	V1.13		Software by Sagredo "est omnibus"

general:

	this is an in-core full screen editor, capable of handling files 
	of a limited but specifiable size.  

	the available functions are fixed, but the input sequences to
	initiate them are configurable.

	the screen handling is also configurable - based on the capabilities
	of the terminal being used.

program sources:
	fsed.txt		this file
	fsed.ver		history of fsed versions
	
	makefile.mak		dos makefile to build editor

	ed_defs.h		definitions of structures and default parms
	ed_state.h		declarations for editor state variables
	ed_rtns.h		declarations of all external routines in editor

	ed_vers.c		contains version and copyright strings
	ed_main.c		main routine and argument processing
	ed_conf.c		command configuration
	ed_lex.c		input lexer

	ed_misc.c		editor arena allocation and utilities
	ed_move.c		cursor motion
	ed_cmd.c		text manipulation commands
	ed_text.c		in-core text manipulation routines

	ed_fio.c		routines to handle file input/output
	ed_out.c		routines to handle full screen updates
	ed_tio.c		routines to handle terminal input/output

	ed_dbg.c		optional development debugging routines


command line parameters:

	a file name will be taken as the name of a file to be read
	in (durring initialization) and to be written out (if the
	user exits with writeout).

	flags can be prefixed with either a unix "-" or a DOS "/"

	    flags to set basic parameters:
		-w#	set screen width  	- default  80
		-h#	set screen height 	- default  24
		-l#	set max file length	- default 100
		-t#	set tab width		- default   4
		-m#	set word-wrap margin	- default   1

	    flags to describe options and terminal output capabilities:
		-b#	base for rows/cols	- default   1
		-aa[0/1] ansi (vs wwiv) attrs	- default   *
		-ac[0/1] automatic cursor wrap	- default   1
		-as[0/1] automatic scroll	- default   1
		-ai[0/1] autoindent on wordwrap - default   1
		-ob[0/1] backwrap to last word  - default   1
		-x	 extended key defs	- default   0

	    flags to initiate dual-mode editing:
		-d	start in command mode	- default  no
		-r	start in auto-replace	- default  no
		-i	start in auto-insert 	- default  no

	    flags to enable other special processing
		-c	terminal is the console - default  no
		-P#	COM port number		- default  *
		-T#	input timeout interval	- default  *

		if a -c argument is specified, all screen updates will
		be performed with display bios calls rather than through
		the use of the configured output strings.

		if a -P argument is specified, and no input is being
		received, the modem status register on that port will
		be checked, and if CD drops, the edit will be aborted.

		if a -T argument is specified, the user will be given
		that many seconds to enter input - after which it will
		be assumed that he has hung up.

	when it starts up, fsed looks in its environment for the value of
	"BBS".  If that variable has a value of the form "WWIV v#.##", fsed
	will set most of its defaults to be appropriate to the level of
	BBS code that is being run:

		4.00 and above - WWIV-style attributes
				soft cr indications are put in the file
				no modem status or timeout checks are performed

		pre 4.00      - ansi-attributes on
				hard cr indications are put in the file
				input timeout interval 90 seconds
				check modem status on first port with CD up

		no bbs string - ansi-attributes on
				no hard or soft cr indications in file
				no modem status or timeout checks are performed

	a file name preceded with a "+" will be taken as the name of
	a parameter file to be read in.  Any parm that can be specified
	in the parameter file can be specified on the command line and
	vice versa.  The only difference being that in the parameter file
	there is no leading "-" or "/".  As many parameter files as desired
	can be specified.  I have found it convenient to separate input
	string and output capability specifications into separate cfg files.
	This makes sense since the former are dependent upon the tastes
	of the user, whereas the latter are dependent upon the capabilities
	of the terminal being used.

	The default input sequences are set up to be word-star like, but
	also support the PC keyboard cursor keys.  

	The default output sequences are set up for DOS ansi.sys - which is 
	pretty minimal, but should work for most emulated terminals.  
	

	To run the command from the console you need only use the command

		fsed -c filename

	If you have ansi.sys and you want to use it (rather than direct
	BIOS screen updating) you can leave off the -c flag and use the
	command:

		fsed -h25 filename

	The "-h25" is necessary on the console because the default screen
	height is 24 lines, but the ansi.sys console screen is actually 25
	lines high - and for scrolling to work properly, the program must
	know which line is the last one.

	If you are not using the console keyboard, you will want to specify 
	an input configuration file.  If your terminal is more capable than 
	ansi.sys, you will want to specify an output configuration file.  The 
	combination that I favor is

		fsed +vi.cfg +vt100.cfg filename

	which gives me a VI like interface and takes advantage of the vt100
	capabilities of my PROCOMM terminal emulation.


parameter files:
	
	console.cfg		first cut at a PC console options file,
				taking advantage of PC kbd function keys
	
	wordstar.cfg		first cut at an options file for word-star
				style commands (using ws sequences)

	vi.cfg			first cut at an options file for for VI
				style commands (dual modes)


	dosansi.cfg		output configuration for ansi.sys emulation
				(these values are the output defaults)

	vt100.cfg		output configuration file for vt100 emulation


	the default input configuration combines wordstar.cfg with the console
	keypad keys from console.cfg


capabilities and options:

	-aa[0/1] ansi (vs wwiv) attrs	- default   *

		ANSI attributes (such as blinking and colors) are sent 
		out to the terminal with an SGR type command (configured 
		in the output strings).  WWIV attributes are sen't out as
		a 0x03 followed by an attribute-code.

	-ac[0/1] automatic cursor wrap	- default   1

		If moving the cursor right from the right-most column causes
		it to wrap back to the left margin again, this option should
		be set to one.

	-as[0/1] automatic scroll	- default   1

		If moving the cursor right from the bottom right-most position
		on the screen causes the screen to scroll, this option should
		be set to one.
		
	-ai[0/1] autoindent on wordwrap - default   1

		If you want word-wrapped lines to start with the same indent
		as the line from which they wrapped, set this option to one.
		If you want them to always start at the left edge of the 
		screen, set it to zero.

	-ob[0/1] backwrap to end of word - default 1

		If you do a backspace or cursor left at the first column of 
		a line, the cursor will wrap back to the end of the previous
		line.  This parameter controls whether the cursor goes to the
		last column of the previous line (zero) or to the first space
		after the last word on the previous line (one).

	-x	extended key sequences - default 0

		normally extended key definitions (input sequences for which
		a key name has been specified) only work if the -c flag has
		been specified (indicating you are on the console and using
		scan-code expansion).  If the -x flag is specified, the
		extended key sequences can be used whether you are on the
		console keyboard or not.

command sequences:

	up to 50 input command sequences can be defined, and associated with
	any of the available editing functions.  Up to sixteen output
	sequences can be defined, to describe how to make the terminal perform
	all of the standard screen upates.  Input sequences should be
	unambiguous (i.e. don't use ^V to mean one thing and ^VA to mean
	another).  The format of a command sequence definition is:

		<type> <code#> <delimiter> <sequence> <delimiter> <keyname>

	where

		<type> is "C" for most commands, or "S" for the special
			escape sequences for color changes and special
			characters.  For output control sequences, the
			type is "O".

		<code#> is the code number of the editing or output action 
			that should be associated with this string.

		<delimiter> is any non-blank character that will not appear
			in the <sequence>.  I typically use double-quote (").

		<keyname> is an optional sequence of non-blank characters
			that provide a name for the key that generates the
			command sequence.  This is very useful for things
			like the console keyboard.  Noone is likely to realize
			that the left arrow key generates ESC [ D, so telling
			the user that ESC [ D is his cursor left command is
			not doing him a favor.  If a <keyname> is specified,
			the help listing will list the <keyname> rather than
			the actual command sequence.

		<sequence> the input character sequence that is to trigger
			   the desired editing action.  Most characters are
			   literal but there are two special escape conventions.
				
				^ <letter> means insert the control code for
					   the specified letter.  For example,
					   "^C" would be a code of 0x03.

				\ <octal code> means insert the specified
					   three-digit octal code.  For example,
					   "\177" would mean DEL.

				the escape characters can be used to escape
				themselves, so "^^" would include a carret
				into the string, and "\\" would include a 
				backslash in the string.
				two special characters:

			    In output sequences the character "#" can be
			    used to indicate an optional replication factor
			    (if your terminal supports them).  As with the
			    other escapes, "##" will include a "#" in the 
			    string.

			    All codes in the sequence should be 7-bits, since
			    the lexer strips off the high order bits before
			    processing all input.


	For example - to set the exit-without-writing sequence to be ^K^K
		      you would use a command like

			C 26 "^K^K"

		     to set the delete character sequence to DEL you would use

			C 16 "\177"

		     to set the cursor left function to the console left
		     arrow key, you would say something like

			C 1 "\033[D" LEFT-ARROW

		     to set the character delete sequence for the terminal
		     to the ansi standard <CSI> [ <optional count> P, you
		     would use

		       O 14 "\033[#P"

		     to indicate that your terminal did not support character
		     deletion, you would use

		       O 14 ""

Editing actions:

	the following is a list of the supported editing actions and the
	associated command codes:

		 1 - cursor left one column
		 2 - cursor right one column
		 3 - cursor up one column
		 4 - cursor down one column
		 5 - cursor to first line of file
		 6 - cursor to last line of file
		 7 - cursor to start of next line
		 8 - cursor to start of this line
		 9 - cursor right one tab stop
		10 - cursor left one tab stop
		11 - cursor back one word
		12 - cursor fwd one word	
		13 - cursor back one screen
		14 - cursor fwd one screen
		15 - toggle insert mode	
		16 - delete (and suck back) one character
		17 - insert line in front of the current one
		18 - delete the current line
		19 - delete current word (to the right only)
		20 - delete previous word (to the left only)
		21 - break the current line at the cursor position line	
		22 - join this line with the following one
		23 - enter auto-insert mode
		24 - enter auto-replace mode
		25 - exit auto-insert/replace mode
		26 - abort the editor and leave without saving the file
		27 - write out the file and exit
		28 - redraw screen	
		29 - help text, describes all the current control sequences
		30 - change color 
		31 - octal/control escape to include special characters in file
		32 - replace the last line deleted
		33 - clear to end of line
		34 - position cursor to last character on line
		35 - destructive backspace
		36 - find string
		37 - replace found string with something else
		38 - globally perform replacement throughout file
		39 - refill file (only affects word-wrapped lines)
		40 - cursor to top row of screen
		41 - cursor to bottom row of screen
		42 - enter the debugger (if it is available)
		43 - center this line

		
Output control actions:

		 0 - initialize terminal for editing
		 1 - ANSI standard position character to row and column
		 2 - position character to first column in specified row
		 3 - position character to specified column in current row
		 4 - move cursor up one (or more) row(s)
		 5 - move cursor down one (or more) row(s)
		 6 - move cursor right one (or more) column(s)
		 7 - move cursor left one (or more) column(s)
		 8 - home cursor and clear screen
		 9 - clear from cursor position to end of current line
		10 - open one (or more) line(s) in front of current line
		11 - close one (or more) line(s) starting with current line
		12 - enable insert mode
		13 - disable insert mode 
		14 - delete one (or more) character(s) and suck line left
		15 - insert one character at current position
		16 - clean up terminal before exiting
		17 - index up (and scroll down if appropriate)
		18 - index down (and scroll up if appropriate)
		19 - set scrolling region from line # to bottom of screen

	In order to be usable, a terminal must support either (1) or
	(2) and (3).  All other functions are optional, but the editor
	will run much faster if the other functions are supported.  

    CAUTION
	If the terminal does not support (11) it is very important that the
	screen height parameter be properly set.  If this function is not
	available, the editor accomplishes "full-screen-scroll-up-one" by
	positioning the cursor to the last line and sending a newline.  If
	the editor does not know which line is the REAL last one, this trick
	will not work.


Auto insert/replace mode

	Normally, all input is scanned to see if it is a command of some
	sort.  In this model, the editor acts like a function-key WYSIWYG
	editor.  If you don't have function keys and your users are afraid
	of control sequences the program can also act as a dual-mode (edit/
	command) editor.

	In edit mode, all graphic input is treated as text to be put into
	the file.  You exit edit mode with a (configurable) control sequence.
	This puts you into command mode.  In command mode, all input is treated
	as commands - until you give the command to go back into edit mode.

	One major difference between the normal modes and auto-insert/replace
	mode is whether the tab and newline character insert text or only move
	the cursor.  In either auto-mode, a tab generates the approriate 
	number of blanks.  In auto-insert mode a newline breaks a a line, and
	in auto-replace mode a newline deletes the remaining character on the
	line.

	You can enter edit mode with one of two commands:

		enter auto-insert mode
		enter auto-replace mode

	You can exit edit mode with the command

		exit auto-insert/replace mode

	The use of dual modes must be enabled by the r (replace), i (insert),
	or c (command) options - specified in the parameter file or on the 
	command line.  For instance:

		edit /r yourfile

	would start the editor up in auto-replace mode.


Using the PC Keyboard

	If the -c flag is specified, all screen updates will be done using
	BIOS video services.  It also enables scan-code conversion of 
	all keyboard input.  All of the normal ascii keys continue to 
	produce the obvious values.  The scan-code mapping causes the
	non-standard and ALT-ed keys to produce multi-character sequences.
	
	If you want to take advantage of all of these keys, you can prepare
	a new input configuration file.  The sequences produced by the
	non-standard keys are summarized below.  Keys with obvious ANSI
	meanings tend to produce the corresponding ANSI sequences.  The 
	remaining keys try to produce that are (in some sense) intuitive
	or easy to remember.


	KEY		Sequence		Notes

	NULL		000			ANSI null
	HOME		ESC [ H			ANSI home
	UP		ESC [ A			ANSI cursor up
	PGUP		ESC [ U			ANSI page up
	LEFT		ESC [ D			ANSI cursor left
	RIGHT		ESC [ C			ANSI cursor right
	END		ESC [ K			ANSI delete to end of line
	DOWN		ESC [ B			ANSI cursor down
	PGDN		ESC [ V			ANSI page down
	INS		ESC [ L			ANSI insert line
	DEL		127			ANSI DEL
	SHIFT-TAB	ESC [ Z			ANSI backtab

	F1		ESC [ 1			ESC [ number
	F2		ESC [ 2		
	       . . .
	F10		ESC [ 0		

	ALT-#					same as function keys

	ALT-A		ESC [ a			ESC [ letter
	ALT-B		ESC [ b
	       . . .
	ALT-Z		ESC [ z

	SHIFT-F1	ESC [ !			shifted version of F keys
	SHIFT-F2	ESC [ @
	       . . .
	SHIFT-F10	ESC [ )

	CTL-HOME	ESC [ .			arbitrary illegal sequences
	CTL-END		ESC [ ?
	CTL-LEFT	ESC [ <
	CTL-RIGHT	ESC [ >
	CTL-PGUP	ESC [ |
	CTL-PGDN	ESC [ /

	CTL-F#		^A-^J			I ran out of escape sequences
	ALT-F#		^K-^S			so I thought this would help

	If you are grossly offended by this mapping, you can change it.
	The table that implements it is called "scanmap" and is located
	near the end of ed_tio.c.

