ile man page

[Bob Pendleton]

#! /bin/sh
# This is a shell archive, meaning:
# 1.  Remove everything above the #! /bin/sh line.
# 2.  Save the resulting test in a file
# 3.  Execute the file with /bin/sh (not csh) to create the files:
#
#ile.l
#
# Created by bpendlet (Bob Pendleton) on Thu Jul  7 14:15:44 MDT 1988
#
if test -f 'ile.l'
then
    echo shar: will not over-write existing file "ile.l"
else
echo extracting "ile.l"
sed 's/^X//' >ile.l <<'SHAR_EOF'
X.de EX		\"Begin example
X.ne 5
X.if n .sp 1
X.if t .sp .5
X.nf
X.in +.5i
X..
X.de EE
X.fi
X.in -.5i
X.if n .sp 1
X.if t .sp .5
X..
X.TH ILE 1 "5 May 1988" 
X.SH NAME
X.PP
Xile - An input line editor for UNIX (Input Line Editor)
X.PP
X.SH SYNTAX
X.PP
X\fBile\fP [-file/name\fP] \fP[prog arg1 arg2 ... argn\fP]
X.PP
X.SH DESCRIPTION
X.PP
XThe \fIile\fP program is an input line editor that provides an easier
Xto use history mechanism than the shell.
X.PP
XThe \fIile\fP program can be run as a simple shell around any program. It gives
Xany program an input line editing and a history mechanism. It can also be
Xrun around your favorite shell. When run around the shell \fIile\fP records the
Xinput to programs as well as input to the shell in its history buffer.
X
X\fIile\fP takes two optional command line arguments. The first argument is
Xthe name of an initialization file containing user defined key and
Xdelimiter bindings. The second argument is the name of a program to execute
Xand the command line arguments for that program. 
X.PP
XIf no initialization file
Xis given on the command line \fIile\fP first looks in \fI./.ilerc\fP and
Xthen in \fI$HOME/.ilerc\fP. If no initialization file is found \fIile\fP
Xprovides default values for delimiter and key bindings.
X.PP
XIf no program name is given on the command line \fIile\fP executes \fIcsh\fp.
X.PP
X.SH DEFAULT BINDINGS
X.PP
XNot everyone wants to have to figure out yet another initialization
Xfile format so \fIile\fP provides a complete set of default bindings for
Xall its operations.
X.PP
X.SH Delimiters
X.PP
XDelimiters are used in \fIile\fP to mark the beginnings and ends of words
Xfor the \fBforward_word\fP, \fBbackward_word\fP, and \fBdelete_word\fP
Xactions. The
Xdefault delimiters are ' ' (blank), '/' (slash), '.' (period), 
Xand '-' (dash). These were chosen because the author decided they were
X"natural" stopping characters in a UNIX environment.
X.PP
X.SH Keys
X.PP
XThe following table shows the default bindings of keys and key sequences
Xprovided by \fIile\fP. These are based on the emacs key bindings for
Xsimilar operations.
X.EX 0
X^A      - start_of_line
X^B      - backward_char
X^E      - end_of_line
X^F      - forward_char
X^K      - erase_to_end_of_line
X^L      - retype_line
X^N      - forward_history
X^P      - backward_history
X^V      - quote
X^T      - transpose_chars
Xdel     - delete_char
X^M      - add_to_history
X^J      - add_to_history
X^U      - erase_line
X^X      - delete_char_under
X
X^C      - pass
X^D      - pass
X^Q      - pass
X^S      - pass
X^Z      - pass
X
Xesc b   - backward_word
Xesc f   - forward_word
Xesc del - delete_word
Xesc esc - complete_file
Xesc s   - complete_file_full
Xesc d   - show_files
Xesc u   - upper_word
Xesc l   - lower_word
Xesc c   - capitalize_word
X
Xesc [ A - backward_history (up arrow)
Xesc [ B - forward_history  (down arrow)
Xesc [ C - forward_char     (right arrow)
Xesc [ D - backward_char    (left arrow)
X.EE
X
X.SH INITIALIZATION FILE
X.PP
XThe \fIile\fP initialization file has two parts. The first part is also the
Xfirst line of the file. This line contains the delimiter characters that
Xwill be used by the \fBforward_word\fP, \fBbackward_word\fP, 
Xand \fBdelete_word\fP actions.
XEach character on the line becomes a delimiter character.
X
XThe second part of the file is a list of table numbers, characters, and
Xactions or strings. \fIile\fP has 4 action tables. Each action 
Xtable contains an action or string
Xfor each possible character. \fIile\fP decides what to do with a character
Xby looking it up in the table and executing the action associated with the
Xcharacter or by passing the string one character at a time into \fIile\fP
Xas if it had been typed by the user. Normally only table 0 is used. But, the
X\fBescape\fP actions cause
Xthe next character to be looked up in a different table. The \fBescape\fP
Xactions make it possible to map multiple character sequences to actions.
X
XBy default, all entries in table 0 are bound to the \fBinsert\fP action, and
Xall entries in the other tables are bound to the \fBbell\fP action. User 
Xspecified bindings override these defaults. The following example is an 
Xinitialization file that sets up the same key and delimiter bindings as the
X\fIile\fP default bindings.
X.PP
X.SH Example \fI.ilerc\fP file
X.EX 0
X /.-
X
X0^A=start_of_line
X0^B=backward_char
X0^E=end_of_line
X0^F=forward_char
X0^K=erase_to_end_of_line
X0^L=retype_line
X0^N=forward_history
X0^P=backward_history
X0^V=quote
X0^T=transpose_chars
X0\\177=delete_char
X0^[=escape_1
X0^M=add_to_history
X0^J=add_to_history
X0^U=erase_line
X0^X=delete_char_under
X
X0^C=pass
X0^D=pass
X0^Q=pass
X0^S=pass
X0^Z=pass
X
X1b=backward_word
X1f=forward_word
X1\\177=delete_word
X1[=escape_2
X1^[=complete_file
X1s=complete_file_full
X1d=show_files
X1u=upper_word
X1l=lower_word
X1c=capitalize_word
X
X2A=backward_history
X2B=forward_history
X2C=forward_char
X2D=backward_char
X.EE
X.PP
XThe first character on each key binding line is the index of the table
Xto place the key binding in. Valid values for the index are 0, 1, 2, and 3.
X.PP
XThe second character on the line is either the character to bind or
Xan indicator that tells how to find out what character to bind. If the 
Xsecond character is any character besides '^' or '\\' then the action is
Xbound to that character.
X.PP
XIf the second character on the line is '^' then the next character is taken
Xas the name of a control character. So ^H is backspace and ^[ is escape.
X.PP
XIf the second character on the line is a '\\' and the next character is
Xa digit between 0 and 7 the the following characters
Xare interpreted as an octal number that indicates which character to bind
Xthe action to. If the character immediately after the '\\' is not an
Xoctal digit then the action is bound to that character. For example,
Xto get the '^' character you would use '\\^'.
X.PP
XThe next character on the line is always '='. Following the equal sign is
Xthe name of an action or a string. The actions are defined in the following 
Xtable.
X.PP
X.SH Actions
X
X.IP "\fBbell\fP" 20
X 
XSend a bell (^G) character to the terminal. Hopefully the bell will ring.
XThis action is a nice way to tell the user that an invalid sequence of
Xkeys has been typed.
X
X.IP "\fBpass\fP" 20
X 
XPass the character to the program running under \fIile\fP. Do not echo
Xthe character, do not insert it into the edit buffer. Just pass it along.
XThis is useful for characters like ^C, ^Z, ^Q, and ^S that have special
Xmeaning and shouldn't be held up in the edit buffer waiting to be sent.
X
X.IP "\fBinsert\fP" 20
X 
XInsert the character into the edit buffer. If there are already 256 
Xcharacters in the buffer \fIile\fP will beep and refuse to put the character
Xin the buffer.
X
X.IP "\fBtranspose_chars\fP" 20
X
XSwap the character under the cursor with the character to the left of
Xthe cursor and move the cursor one character to the right. This is handy
Xfor correcting letter transposition errors.
X 
X.IP "\fBdelete_char\fP" 20
X 
XDelete the character directly to the left of the cursor from the edit buffer.
X
X.IP "\fBdelete_char_under\fP" 20
X 
XDelete the character under the cursor from the edit buffer.
X
X.IP "\fBquote\fP" 20
X 
XThe next character to come into \fIile\fP will be inserted into the edit
Xbuffer. This allows you to put characters into the edit buffer
Xthat are bound to an action other than insert.
X
X.IP "\fBescape_1\fP" 20
X 
XLook up the next character in action table 1 instead of action table 0.
X
X.IP "\fBescape_2\fP" 20
X 
XLook up the next character in action table 2 instead of action table 0.
X
X.IP "\fBescape_3\fP" 20
X 
XLook up the next character in action table 3 instead of action table 0.
X
X.IP "\fBdelete_word\fP" 20
X 
XDelete the word directly to the left of the cursor. A word is a sequence
Xof characters surrounded by delimiter characters.
X
X.IP "\fBforward_word\fP" 20
X 
XMove the cursor to the right past the next word. A word is a sequence of
Xcharacters surrounded by delimiter characters.
X
X.IP "\fBbackward_word\fP" 20
X 
XMove the cursor to the left past the next word. A word is a sequence of
Xcharacters surrounded by delimiter characters.
X
X.IP "\fBupper_word\fP" 20
X
XStarting with the character under the cursor, convert the word to the 
Xright of the cursor to upper case.
X
X.IP "\fBlower_word\fP" 20
X
XStarting with the character under the cursor, convert the word to the
Xright of the cursor to lower case.
X
X.IP "\fBcapitalize_word\fP" 20
X
XConvert the character under the cursor to upper case. Convert the word to
Xthe right of the cursor to lower case.
X
X.IP "\fBstart_of_line\fP" 20
X 
XMove the cursor to the left most character in the edit buffer.
X
X.IP "\fBbackward_char\fP" 20
X 
XMove the cursor to the left one character.
X
X.IP "\fBend_of_line\fP" 20
X 
XMove the cursor past the last character in the edit buffer.
X
X.IP "\fBforward_char\fP" 20
X 
XMove the cursor to the right one character.
X
X.IP "\fBadd_to_history\fP" 20
X 
XAdd the contents of the edit buffer to the history buffer and pass the line
Xalong to the program running under \fIile\fP.
X
X.IP "\fBerase_line\fP" 20
X 
XClear the line. Erase all characters on the line.
X
X.IP "\fBerase_to_end_of_line\fP" 20
X 
XDelete the character under the cursor and all character to the left
Xof the cursor from the edit buffer.
X
X.IP "\fBretype_line\fP" 20
X 
XRetype the contents of the current edit buffer. This is handy when system
Xmessages or other asynchronous output has garbled the input line.
X
X.IP "\fBforward_history\fP" 20
X 
XDisplay the next entry in the history buffer. If you are already at the
Xmost recent entry display a blank line. If you try to go forward past
Xthe blank line this command will beep at you.
X
X.IP "\fBbackward_history\fP" 20
X 
XDisplay the previous entry in the history buffer. If there are no older
Xentries in the buffer, beep.
X
X.IP "\fBcomplete_file\fP" 20
X
XTake the word currently under, or immediately to the left of the cursor and
Xtreat it as a partial file name and path name. If there is only one file in the
Xdirectory that starts with the partial file name then fill in the rest of
Xthe file name in the input line. If more than one file starts with the
Xpartial file name fill in the longest common starting string of those file
Xnames.
X 
XIf the path is specified as "~/" then look in the directory named
Xby $HOME. 
X
XIf the path is specified as "~name", where name is a user login name or
Xa partial user login name, then look in the users login directory. If
Xmore than one match is found for a partial user name then \fIile\fP
Xwill beep. When completing a file name, a partial user name will be
Xcompleted at the same time the file name is being completed.
X
XIf you don't use one of the abbreviated path names, you must provide and
Xabsolute path. \fIile\fP is not the shell and does not know the path to
Xthe current directory. This means that \fIile\fP cannot do file name
Xcompletion on relative paths like "dir/file", "./file", and "../file".
X
X.IP "\fBcomplete_file_full\fP" 20
X
XLike \fBcomplete_file\fP but abbreviations like "~/" are replaced by
Xthe full path that they stand for. This is handy when you want to
Xuse abbreviated path names but the program you are talking to doesn't
Xunderstand the abbreviations.
X
XRead the discussion of file name completion under \fBcomplete_file\fP
Xfor more information.
X
X.IP "\fBshow_files\fP" 20
X 
XTake the word currently under, or immediately to the left of, the cursor and 
Xtreat it as a partial file name and path name. List all the files that start
Xwith the partial file name in the directory specified by the path name.
X
XRead the discussion of file name completion under \fBcomplete_file\fP
Xfor more information.
X
X.PP
X.SH Strings
X
XIn addition to being able to bind a character sequence to an action \fIile\fP
Xallows characters sequences to be bound to strings of characters. When a string
Xis invoked the characters in the string are treated as if they were typed
Xby the user. For example, if the line:
X.EX 0
X0^G=ring^Ma^Mbell^M
X.EE
Xwas in your \fI.ilerc\fP file, typing control G would cause three
Xlines to be typed as if the user typed them. Using the default bindings,
Xunless there is a ^J or ^M in the string the string will be inserted
Xin the current line but not sent along until the the user actually
Xpresses return.
X
X.PP
X.SH Error Messages
X.PP
XWhen \fIile\fP encounters errors it prints a message and terminates.
X\fIile\fP can print several standard error message. It can also print
Xa few messages that are specific to \fIile\fP.
X
X.IP "\fBile: unable to allocate pty/tty pair\fP" 20
X
XThere are no free pty devices in the system. You can either try again later,
Xand hope someone has freed a pty for you to use, or you can grab your
Xsystem manager and try to get more pty devices configured.
X
X.IP "\fBile: '=' missing on line #\fP" 20
X
XIn a character binding line you left out the '=' character. Or, you did 
Xsomething that confused the initialization file reader into thinking there
Xshould be an '=' where you didn't think there should be one.
X
X.IP "\fBile: error in initialization file on line #\fP" 20
X
XThis means that the first character of a character binding line wasn't
Xa newline or a '0', '1', '2', or '3'. It could also mean that the 
Xinitialization file reader is confused.
X
X.IP "\fBile: can't find terminal\fP" 20
X
X\fIile\fP could not find a termcap entry for the terminal named by the TERM
Xenvironment variable. Since it can't find it \fIile\fP can't figure out
Xhow to use it.
X
X.IP "\fBile: can't run on terminal\fP" 20
X
XThe terminal named in your TERM environment variable doesn't support
Xthe capabilities \fIile\fP needs to run. So \fIile\fP doesn't even try.
X
X.PP
X.SH BUGS
X.PP
X\fIile\fP changes the input mode on the controlling terminal to RAW. This
Xconfuses xterm. It is a good idea to include the line:
X.EX 0
Xstty cooked -nl echo tabs crt decctlq -litout
X.EE
Xin your .cshrc file when using xterm. Otherwise your new xterm windows
Xcome up in an unusable state.
X.PP
X\fIile\fP requires a terminal that supports the termcap le, ce, bl, 
Xnl, and cr capabilities. If your terminal doesn't provide these,
X\fIile\fP will refuse to run on your terminal.
X.PP
XA misspelled action name in an \fIilerc\fP will be treated as a string.
XThis means that typing the sequence of characters that should
Xinvoke the action will actually cause the misspelled name to be inserted
Xin the input line. 
X.PP
X.SH FILES
X.PP
X $HOME/.ilerc
X ./.ilerc
X.PP 
X.SH SEE ALSO
X.PP
Xstty(1), xterm(1), csh(1), termcap(5)
X
X.SH COPYRIGHT
X.ce 4
XCOPYRIGHT 1988
XEvans & Sutherland Computer Corporation
XSalt Lake City, Utah
XAll Rights Reserved.
X.LP
XTHE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE AND
XSHOULD NOT BE CONSTRUED AS A COMMITMENT BY EVANS & SUTHERLAND.
XEVANS & SUTHERLAND  MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY
XOF THIS SOFTWARE FOR
XANY PURPOSE.  IT IS SUPPLIED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
X.LP
XIF THE SOFTWARE IS MODIFIED IN A MANNER CREATING DERIVATIVE COPYRIGHT RIGHTS,
XAPPROPRIATE LEGENDS MAY BE PLACED ON THE DERIVATIVE WORK IN ADDITION TO THAT
XSET FORTH ABOVE.
X.LP
XPermission to use, copy, modify, and distribute this software and its
Xdocumentation for any purpose and without fee is hereby granted, provided
Xthat the above copyright notice appear in all copies and that both the
Xcopyright notice and this permission notice appear in supporting documentation,
Xand that the name of Evans & Sutherland not be used in advertising
Xor publicity pertaining to distribution of the software without specific, 
Xwritten prior permission.
X.SH AUTHOR
XRobert C. Pendleton
XEvans & Sutherland, Interactive Systems Division, Salt Lake City, Utah.
X.LP
X
SHAR_EOF
if test 15428 -ne "`wc -c < ile.l`"
then
    echo shar: error transmitting "ile.l" '(should have been 15428 characters)'
fi
fi
# end of shell archive
exit 0
-- 
Bob Pendleton @ Evans & Sutherland
UUCP Address:  {decvax,ucbvax,allegra}!decwrl!esunix!bpendlet
Alternate:     utah-cs!utah-gr!uplherc!esunix!bpendlet
        I am solely responsible for what I say.