This file is an attempt at a truly USABLE Teco manual.  -*-Text-*-

File: TECO	Node: Top	Up: (DIR)	Next: Intro

This is an INFO-ized User's Manual for TECO, the Text Editor and
Corrector.

WARNING: This INFO file is organized, for the most part, as a full
two-dimensional system. Next and Previous (N and P) are used to change
topic, and Menus (M) are used to move "deeper", to more complicated,
less used, commands, complemented by Up (U), which moves to simpler
levels. This was done in an attempt to make this manual into a really
usable tutorial system without sacrificing ease of use as a reference
work. If you have any comments on this technique, either good or bad,
feel free to send them to JKESS @ MIT-MC.

* Menu:

* Intro::        An introduction to TECO.


Index by topic:

* Conventions:: The conventions used in representing TECO commands in
		this file.
* Arguments::   How to pass arguments to TECO commands.
* Usage::       Using TECO interactively.

Topics not yet implemented:

 File::        Operations involving the file system (Reading from and
		WRITING to files, Directory operations, and the like).
 Flow::        Loops, Branching, Conditionals and similar commands.
 Insert::      Inserting text into the buffer.
 Math::        Mathematical operations.
 Pointer::     How to move around the buffer. Searching.
 Data::        The various kinds of data structures: Q-registers,
		Q-vectors, Buffers, Flags.
 TTY::         Input from, and output to, the terminal.
 Deletion::    Erasing text from the buffer.
 Valret::      Passing commands to the outside world.
 Real-Time::   EMACS, INFO, and RMAIL-like systems.
 Flags::       How to change TECO's behavior, and how to get at
		all kinds of additional data.
 Obscure::     If you can't find what you want anywhere else, ask
		at this counter. We probably have it.
 Macros::      How to write programs in TECO.

File: TECO, Node: Intro, Previous: Top, Up: Top, Next: Conventions

Welcome to the TECO manual! TECO is both a text editor, and a
programming language designed for text handling.

TECO is one of the few text editors to be really usable on both video
and hard-copy terminals. On a display terminal, TECO becomes a
"display editor", in that the text being edited is visible on the
screen and is updated automatically as you type your commands.  For
the times when high-speed updating of the display is unavailable, or
when the user is on a printing terminal, TECO offers a simple,
powerful set of commands allowing the user to monitor progress without
wasting time and paper printing more than necessary.

Teco is considered an "advanced" editor because it provides facilities
that go beyond simple insertion and deletion: filling of text; dealing
in terms of characters, words, lines, and LISP expressions, sorting
operations, and much more.

TECO permits the user to define "macros", or programmed sequences of
actions, at any time. These can either be executed immediately, or
stored and used repeatedly as needed. In fact, experienced TECO users
usually work in terms of groups of actions rather than single
commands. The step from writing a command to replace all occurrences
of FOO with BAR to writing a real program is a remarkably short one.

Teco also has provision built in for becoming a "real-time" editor, in
which the display is updated very frequently, usually after each
character or pair of characters you type.  This minimizes the amount
of information you must keep in your head as you edit. A simple system
of this sort is built in, but this can be expanded and redefined virtually
without limit. EMACS is based upon this feature. Other examples of TECO
programs you may be familiar with are RMAIL and INFO. (You're probably
using INFO to read this file right now!)

As a programming language, TECO shares many of the advantages and
disadvantages of APL and LISP. Because, like APL, it was originally
designed for interactive use in solving a specific kind of problem
(text manipulation), its commands are very short, easy to type, and,
with a bit of practice, easily memorizable due to their mnemonic
nature (well, MOST of them). This leads to programs being incredibly
compact. However, when combined with TECO's lack of program format
requirements, this very conciseness can make programs hard to follow
unless very thoroughly commented. Also, like APL, a single misplaced
character can make a huge difference.

Like LISP, TECO's program and data formats are identical. This means
that a TECO program can construct new programs, invoke them, and
modify them under software control.

So, whether you are reading this because you're not satisfied with
EMACS on a printing terminal, because you want to modify or add an
EMACS command, because you need a language that allows detailed
operation on text, or simply out of curiosity, welcome! You may have
just found what you were looking for.

File: TECO, Node: Conventions, Previous: Intro, Up: Top, Next: Arguments

Before we start discussing how to use TECO, we had best agree on
a few conventions regarding how we will represent the commands in
this manual.

1)	In this file, we'll be using the convention developed in BNF
	that any quantity enclosed in angle-brackets denotes a
	CONCEPTUAL quantity, replaced in actual use by whatever data
	of that type is relevant. For example, <number>C means a
	number followed immediately by the character "C" (Examples:
	4C, 18423C, -27C).  Since numeric values are used so often in
	this way, we'll usually use just <n> or <m> to represent a
	number.  In any case, the angle brackets are NOT typed!

	There will be a few exceptions to the above rule (TECO has a
	few commands that use angle brackets), but these will be
	clearly marked.

2)	The notation ^<character> (caret followed by a character)
	means a control-character. Thus, ^A means control-A. A control
	character is typed by holding the CONTROL key on your terminal
	while typing the indicated character.

3)	All "$" characters in this manual represent <Altmode> unless
	otherwise specified. The <Altmode> key is the key marked ESC,
	SEL, or ALT, usually somewhere on the far left of your
	keyboard, toward the top. If your keyboard has no <Altmode>
	key, you should type control-right-bracket (^]). If it has
	both <Altmode> and <Escape> keys, use ONLY the Altmode key --
	ESCAPE on these terminals does something totally different and
	unrelated to Teco.

File: TECO, Node: Arguments, Previous: Conventions, Up: Top, Next: Usage

Most Teco commands can be given arguments (additional data controlling
their actions). Indeed, many commands require such data to do anything
useful. There are three basic types of argument: numeric, string, and
modifier.

NUMERIC ARGUMENTS can be either a number, or a command that returns a
numeric value. Numbers in Teco must always be integers, either
positive, negative, or zero. Normally, they default to base-10,
but can be identified as base-8 by following them with a "." (thus
12. and 10 both represent the value "ten" in Teco).

Up to two numeric arguments may be given to a Teco command, separated
by a comma. Either or both of these is often omitted. Most commands
will do different things, depending on the number and position with
respect to the comma of the arguments they are given. The syntax for
these arguments is:

	<command>		No arguments.
	<arg><command>		Single (postcomma) arg.
	<arg>,<command>		Single (precomma) arg.
	<arg>,<arg><command>	both pre- and post-comma args.

Note that you don't have to type a comma if the argument is supposed
to be of the "postcomma" variety. For this reason, most commands that
take a single argument use this type -- if we say "single argument",
we'll mean this unless explicitly stated otherwise.

Warning: Since TECO ignores spaces and carriage returns outside of
string arguments, the only way to prevent a numeric value returned by
one command from being passed to the next is to either explicitly give
that next command another numeric argument, or to separate the two
commands with an <Altmode> or a "W" command. Happily, this is not
usually a problem, since few commands returning a value are used for
other purposes.


While numeric arguments usually precede the command they are being
passed to, STRING (TEXT) ARGUMENTS are usually written immediately
after the command, and terminated with an Altmode:

	<command><text>$	Command with text argument.

Text strings can be any sequence of characters. For example, the Teco
command to insert additional text into the editing buffer is "I", so
the command "IThis is a test$" would insert "This is a test" into the
buffer. There are a few characters which are not normally permitted in
text strings; see *note quoting: quoting, for ways to bypass this.

Note that many characters use BOTH string and numeric arguments:
"3Snest$" causes TECO to search for the third occurance of "nest".


The third class of arguments is MODIFIERS. These are the characters
":" and "@". They act on the other commands, changing their meanings
in various ways. Unfortunately, their action varies widely (and
wildly), depending on which command they are applied to, so we can do
no more than mention them here.

File: TECO, Node: Usage, Previous: Arguments, Up: Top, Next: Usage

This section is a basic introduction to the TECO environment, and how
it differs on printing and display terminals.

------------------------------------------------------------------------
ON A PRINTING TERMINAL: The first thing you see when you enter TECO is
the prompt character "&", indicating that TECO is waiting for a
command. This prompt will reappear after each command string is
executed (see below). In order to save paper (and typing time on slow
terminals), TECO insists that you explicitly request ALL printing --
so you'll want to pay especial attention to the "T" command in the TTY
node of this manual. (T types out a section of the editing buffer.)
------------------------------------------------------------------------
ON A DISPLAY TERMINAL: Teco divides the display into two sections. The
upper one (about 5/6 of the screen) is used to display the text
currently being edited. The remaining zone, known as the "echo area",
is used to echo the user's commands. If you have a slow display, you
may want to pretend that you are a printing terminal ... although I'm
not currently sure how to do that. (**) The current position of the
pointer (see later nodes) is indicated with "/\" on most terminals.
This automatic display is actually part of a T command extending to
the end of the editing buffer -- you'll often notice a "--MORE--" at
the bottom of the text area, meaning that the file extends past the
currently visible "page"; if you type a space at this point, printout
of the buffer will continue.  No prompt character is supplied on
displays; you can get some feedback by watching the "--MORE--" become
"--FLUSHED--" when you type the first non-space character of the
command, and "--MORE--" again when the command finishes.
------------------------------------------------------------------------

Teco commands are not executed until you type two Altmodes in
succession.  (Note that "$<some character><Rubout>$" is NOT recognized
as end-of-commands; you would have to type another ALT to go with the
last one in that command string!) This allows the user to type a
series of commands, then hit "$$", and have the whole set executed as
a block. A single ALT is a no-op except when being used to terminate a
string argument to a command; as a beginner, you may want to separate
almost ALL your commands by ALTs, to help guard against typing errors.

Feel free to include spaces and carriage returns in your command
strings.  Carriage return as a command performs no action, but will
accept (and throw away) any numeric arguments you give it. Space is a
no-op normally; see the MATH node for its other use. These are
particularly useful when writing macros, where clarity is essential,
but can also be helpful in normal command entry.

Typing errors in TECO can be particularly nasty. TECO uses nearly the
full ASCII character set as commands, so almost any collection of junk
will do SOMETHING. If you make mistakes in typing commands, RUBOUT
works, but there is no "redisplay" command to allow you to perform a
final check on what TECO is actually going to read. Thus, if you make
a LOT of errors in a line, you may want to just take it from the top.

The ^G character is used whenever you want to abort something TECO
is doing. It will cancel a partially typed-in command string,
interrupt any currently-running command, cancel remaining output to
printing terminals, and generally put you back at the command-reading
level.

TECO treats lower- and upper-case letters identically when used as
commands; inside text strings, TECO does differentiate between the
two, however.
