path: root/usr.bin/mg/mgprog.doc

This documentation covers mg 2a.

I do want feedback from other mg developers on what they think of my
changes, documentation, and what needs to be done to make mg better.
This document is not complete, it mainly covers the areas I have
recently changed.

Possible future changes:

Rearange file contents along more rational lines.  Further split the
monolithic def.h file.

Changing the echo line stuff to use a minibuffer keymap.

Making the kill buffer a linked list of lines.

Variables.

Allow for backspace, ^s, etc. to be changed in some reasonable manner.
(Probably using variables or a simulation thereof.)  I do not think an
input keymap is the correct solution, even if it is frequently used in
Gnu emacs.  (Besides the extra overhead, keynames come out wrong.)

Make long lines wrap like they do in GNU emacs.

Fix known (and unknown :-) bugs.

Have the keymaps and associated tables generated by a program.


Known bugs/limitations:

Binding a key in a named keymap may or may not change the binding of
other keys pointing to the same keymap.	 (i.e. if ^H and ^_ are bound
to help, rebinding ^Hb may not (or may) change ^_b.  This can be cured
by rebinding ^_ to help.)

Overwrite mode does not work in macros.	 (Characters are inserted
rather than overwriting.)

Dired mode has some problems:  Rename does not update the buffer.
Doing a dired again will update the buffer (whether it needs it or
not) and will lose any marks for deletion.  .. and . are not
recognized as special cases.



New implementation oddities:

insert and define-key are new commands corresponding to the mocklisp
functions in Gnu Emacs.	 (Mg does not have non-command functions.)
(Mg's insert will only insert one string.)

The display wrap code does not work at all like that of GNU emacs.



Adding command functions to mg:

Command functions take two integer aguments and return an integer.
The first argument, f, is a set of flags.  (f&FFARG) is non-zero if a
numeric arguement was passed to the function.  (There are bits
indicating how the agument was specified, but they are not fully
impleminted.)  (f&FFRAND) is non-zero if the function is being called
by another function and that possibly slightly different action should
be taken.  (No error checking, supress output, etc.)  The second
argument, n, is the numeric agument passed or one if there was no
numeric arugment.  The fuction should return TRUE if it executes
correctly, FALSE if it could not, and ABORT if the user typed the
keyboard quit character at a prompt.

The function must be added to the functnames table in keymap.c.	 This
table must be kept in assending ascii sequence.



Key maps:

Key maps are structures containing information on what action should
be taken corresponding to an individual keypress.  That action could
be an indication that this is a prefix key and the next kepress should
be looked up in another keymap.

	Example keymap:

	static	struct	KEYMAPE(6+IMAPEXT)	cXmap = {
		6,
		6+IMAPEXT,
		rescan,
		{
			{CCHR('B'),CCHR('G'),	cXcB,	(KEYMAP *)NULL},
			{CCHR('L'),CCHR('X'),	cXcL,	(KEYMAP *)NULL},
			{'(',	')',		cXlp,	(KEYMAP *)NULL},
			{'0',	'4',		cX0,	(KEYMAP *)&cX4map},
			{'=',	'=',		cXeq,	(KEYMAP *)NULL},
			{'^',	's',		cXcar,	(KEYMAP *)NULL},
		}
	};

(Note: this example is a simplified example of a real keymap in keymap.c.)

Since C does not directly support structures containing undementioned
arrays, the macro KEYMAPE is used to create a structure with an array
of the proper size.  6 is the current size of the array, and IMAPEXT
is the number of extra elements left for future groth (by rebinding
keys) before the map must be reallocated.  rescan is the function to
be executed if a specific entry for the key is not found.  (rescan is
a special function that searches for something else to do -- first by
trying lowercasing the last character in the keymap, then by trying
the other modes in effect.)

The array elements must be in order by the keys they define.  Each
covers a range of characters.  Numeric values should not be used for
characters, they make porting mg to some other systems harder.	The
CCHR macro may be used to specify control characters, including DEL
(CCHR('?')).  cXcB, cXcL, etc. are arrays of pointers to functions
returning int.	One of these fuction pointers per element may be to
the pseuto-function prefix.  cX4map is the keymap coresponding to the
prefix function bound to '4' in this keymap.  Having several keys in
an element bound to the default function is better than increasing the
number of elements.



Modes:

Modes are named key maps that are scanned for key bindings before the
global keymap is.  There are functions in modes.c to toggle modes on
or off for individual buffers.  Note that the "major"/"minor" mode
distiction is different than in Gnu Emacs.  Dired is currently the
only major mode available, buffers are put into dired mode on creation
by the dired code.  (The distiction in mg is the major mode replaces
the default keymap instead of being an overlay.) Some modes (overwrite
and no-tab) also trigger per-buffer flags that should be convered to
per-buffer variables when we add variables.  Keymaps for the modes are
kept in keymap.c with the other keymaps.



System dependent files:

Fileio.c:
	Contains file i/o routines:
		ffputbuf(BUFFER *):
Write all lines of buffer to the file.	The last line of the buffer does
NOT have the normally implied newline.	(One may be added if
nessisary, but don't write out the last line if it is zero characters
long.)

		ffgetline(char *buf, int nbuf, int *nbytes):
Read a line from the file up to the length specified by the second
argument in to the buffer pointed to by the first.  If a newline is
not found after reading nbuf characters, return FIOLONG and on the
next call to ffgetline return the remaining portion (or nbuf more
characters and return FIOLONG).	 If a newline is found, set *nbytes to
the number of characters read and return FIOSUC.  If the end of file
is descovered, set *nbytes and return FIOEOF.  (If the file ends in a
newline, the call returning FIOEOF will set *nbytes to 0.)  If any
other error occurs, return FIOERR.

		char *adjustname(char *fname)
Standardize filename.  On mono-case systems, lowercase the file name.
If NO_DIR is not defined, make fully qualified.	 (not relitive to the
current directory, which may change.)

		fncmp(char *fna, char *fnb) 
Return 0 if both arguments refer to the same file or buffer.  #define
it to be strcmp on mono-case or case sensitive systems, use a non-case
sensitive compareison otherwise.  (Borrow it from the osk fileio.c)
Both arguments have been through adjustname already. 

	routines needed for dired:

		rename(char *fromname, char *toname)
rename file.  BSD systems have this as a system call.  return -1 on
error.

		copy(char *fromname, char *toname)
copy file.  return -1 on error.

		unlinkdir(char *name)
Delete directory.  return -1 on error.  (possibly including non-empty
directory.)

		BUFFER *dired_(char *name)
Create dired buffer for named directory.  See example from osk or bsd.

		d_makename(LINE *l, char *fname)
Concatinate directory name associated with the current dired BUFFER
with file name in line.  Return ABORT if no file name on line, FALSE
if it is an ordinary file, or TRUE if there is a directory.  Name made
should be the same as if it were run through adjustname. 


Converting system & terminal dependent files from mg1b:

All command functions will have to be rewritten to use the new two
argument calling sequence.  (Some compilers will let you get away
without doing this for testing purposes.  Problems, if any, will show
up at run-time.)

Key binding is completly different.  See extend.c if your code needs
to do rebinding.

I have attempted make mg less dependant on ascii character values.
Keymap.c depends on ascii sorting order.  Cinfo.c depends on character
values and contains a function to convert from a character value
to a key name.  Several modules assume 3 octal digits are enough for
any character value.

Names of most compile time options have changed.  Whatever is most
GNU-emacs like is now the default.

sysdef.h:
	The type KEY should not be defined.  The type KCHAR should be defined.
	All posible key inputs must be positive in type KCHAR.	short is
	recomended.

spawn.c:
	Update to the new function calling conventions.

Makefile:
	Needs complete rewrite.	 You can probably figure out the dependencies
	from the bsd or osk one.  Compile time options have changed.

Fileio.c:
	Remove function ffputline.  Add function ffputbuf (described above).
	Rewrite ffgetline to conform to the new way of doing things.  (see
	above.)  These routines can probably be borrowed intact from the
	OSK system dependant fileio.c for unix systems.
	Replace adjustcase with adjustname.  Add fncmp either here or
	as a #define in sysdef.h.  Add functions needed by dired.




Compile time options:

extentions not directly in gnu emacs

BSMAP		input mapping exchanging ^H and DEL.
		1 for defaulting to this, 0 for normal default.
NOTAB		for systems that don't like tabs
CVMVAS		arguments to ^V in screens not lines
PREFIXREGION	prefix region
PREVWIND	previous window
GOSREC		Gossling style recenter
STARTUPFILE	(unix & OSK) system-wide startup file
XKEYS		(Termcap) Put kepad in alternate mode, use
		terminal-dependent startup file.

Features removeable to save space

NO_HELP		help, descibe-bindings, describe-key-briefly, apropos
NO_MACRO	keyboard macros.  If defined, NO_STARTUP must be also.
NO_STARTUP	startup files, load, etc.
NO_BACKUP	backup files when writing
NO_DPROMPT	Delayed prompt on multi-key sequences
NO_DIR		Dir change functions.  If defined, NO_DIRED must be also.
NO_DIRED	Dired mode
REGEX		Regular expressions.  Not default, since the code is rather
		unportable and has the GNU copywrite on it.

System dependant garbage (avoid where practical)

VMS		VMS
AMIGA		AMIGA


Things that may be defined in system dependant code:

XCHAR		XCHAR and XSHORT	(char and short for space savings)
BDC2		more special characters for filenames
BDC3		dito.
METABIT		Bit of KCHAR set on meta keys
OFFSET		macro to calculate offset of member from start of structure
NBLOCK		line growth amount
KBLOCK		kill buffer growth amount
MALLOCROUND	macro to predict malloc allocations stratagy
SYSINIT		system dependant initialization
NO_VOID_TYPE	compiler dosen't have type void
ZEROARRAY	zero length arrays are allowed
BINDKEY		include bindkey routine for use by system & terminal
		dependent code.

Terminal dependant

DO_METAKEY	meta key
METABIT		Which bit in a KCHAR is used by the meta key (default 0x80)
STANDOUT_GLITCH standout (may) take character position(s)
GOSLING		optimize redisplay
MEMMAP		memory mapped display
MOVE_STANDOUT	cursor addressing may be done in standout mode
FKEYS		function keys do not fit in type char.
		Not for use where function keys send multiple characters.