Ed is the only editor we have on the mud. Unfortunately, I don't use
it very much, so I know little about it. Please report any errors to
me, or feel free to write a better document! - Plarry.

                       Ed User's Guide
                          by Plarry
                          April 1993

Ed is a `line-oriented' editor, as opposed to `screen' editor. This
means your operations affect whole lines in the file, and you move
around in the file by line number. Ed is a simple version of the Unix
editor ed.

Ed has two modes, command mode and insert mode. The command mode
prompt is `:'; the insert mode prompt is `*'. Insert mode is exited by
typing a single `.' at the beginning of a new line.

Most commands in ed have the following syntax:

	X,Y<cmd>

or

	X<cmd>

where X and Y are line numbers in the file (or `.'  and `$', which refer
to the current and last lines, respectively), and <cmd> is some ed
command.

For example:
	1,10p
will print lines 1 through 10.
	1,5d
will delete lines 1 through 5.
	8p
will print line 8.

A `.' is the ``current line''. The current line is the last line
referenced. To print the current line and 10 more, use:
	.,.+10p

Commands that use a line range are (if no line is given, the current
line is printed):

p	 Print line(s).
l	 Print line(s) with control characters.
z	 Display 20 lines, possible arguments are `.' and `-'.
Z	 Display 40 lines, possible arguments are `.' and `-'.
a	 Start insert mode after specified line.  Exit with `.'<return>
c	 Start insert mode, changing the specified line. Exit with `.'<return>
i	 Start insert mode before specified line. Exit with `.'<return>
A	 Like the `a' command, but uses inverse auto-indent mode.
d	 Delete line(s).
j	 Join (merge) lines together, removing new lines.
k	 Mark one line with a character, for later reference as '<char>.
m	 Move line(s) to the line specified.
r file	 Read in a file after the line specified.
s	 Substitute patterns. See below.
t	 Copy line(s) after the specified line

Commands used without a line specification (arguments in brackets are
optional):

H        Print out a list of available commands.
h<cmd>   Print out help on the command <cmd>.
e file   Replace this file with another file.
E file   Same as `e' but works if the file has been modified.
f [file] Display or set the current file name (set if file is present).
g        Search and execute commands on all matching lines (cf. `v').
I        Indent (and check) your entire file of code.
n        Toggle line numbering.
q        Quit. Won't work if the file is changed.
Q        Quit and discard all changes if not saved.
v        Search and execute commands on all non-matching lines (cf. `g').
set      Configure and query various options to customize ed for yourself.
w [file] Write the file out.
W [file] like the 'w' command but appends instead.
x        Save file and quit in one swoop.
/        Search forward for a pattern.
?        Search backward for a pattern.
=        Show the current line number.
!<cmd>   Execute the mud command <cmd>, as if you were not in ed.

`$' is last line of a file (similar to `.' mentioned above).  Thus
`1,$p' will always print all the file. `=' shows the current line
number.

Note in particular the `H' and `h' commands. `H' gives you a list of
all available commands, and `h<cmd>' gives you help on that particular
command, e.g., `hset' tells you about `set'.

SEARCHING

The search commands are `/' and `?'. `/' searches forward through the
file from the current line and `?' searches backward; otherwise they
are identical. These commands work by you supplying the text you want
to search for after the `/' or `?'; ed will scan through the file,
stopping at the first line which matches. It prints this line out and
it becomes the current line. `//' or `??' will repeat the search.

Important things about searching are that searches are
case-sensitive, i.e., `/book' will not find `Book', and if a search
fails you will get the message ``Unrecognized or failed command.''
Also, you can terminate your search string with `/' if you want, i.e.,
/book and /book/ do the same thing.

Searches can involve more complicated entities than just literal
expressions, i.e., an exact sequence of characters. The term for the
argument to the search command is ``regular expression.'' With regular
expressions, you can search for patterns in a file. Doing this
involves having some characters be special, meaning they do not stand
for the literal character they are. The characters are known as
``meta-characters''. The meta-characters in ed are `.', `*', `[', `]',
`(', `)', and `\'.

What these characters mean is given below (r means any regular
expression):

.	Match any single character (except a newline).
r*      Match any number (0 or more) of the regular expression
             r immediately preceding the *, e.g., T* matches T, TT,
             TTT, and nothing, too.
[...]	Match any one of the characters inside the brackets. [abc]
        matches `a', `b', or `c'. The hyphen `-' can be used to denote
        a range, e.g., [a-z] matches any lowercase letter, [0-9] 
        matches any digit.
(r)     Group the regular expression r. In this way you can apply
        some of the other meta-characters to r, e.g., ([abc])* will
        match a, aa, ab, abc, ababc, etc.
\       This is the ``escape character''. \x will match any character
        'x' where 'x' can be anything. For example, to search for
        the string "create_room(" you can't do /create_room(/, because
        `(' is a meta-character. So you have to do /create_room\(/.
        In particular, `\\` and `\/` search for `\' and `/', resp.

As an example, suppose you have a file consisting of the following:

1	I care not for these ladies that must be wooed and prayed
2	Give me kind Amaryllis, the wanton country maid.
3	Nature Art disdaineth; her beauty is her own.
4	Who when we court and kiss, she cries: ``Forsooth, let go!''
5	But when we come where comfort is, she never will say no.

/court/ will find line 4.
/A.*/   will find line 2 (Amaryllis). Repeating the search will find
        line 3 (Art).
/c[aou]*.*t/ will find line 2 because the string matches the `count' of
        country. /c[aou]*.*t / will find line 4. What this matches is
        actually quite interesting. It does not match `court ', as you
        might think, but `court and kiss she cries: ``Forsooth, let '.
        See the discussion below for further explanation.

REPLACING TEXT

Not only can you search for text, but you can replace strings with
other strings. This is done using the `s' command. The first part
of the `s' command is just like the search command above. The second
part contains the replacement text.

First a simple example:

	s/elf/dwarf/

This will substitute the first occurrence of elf in the current line
to dwarf.  If a `p' is appended, you will also immediately see the
result.

	1,$s/elf/dwarf/

This is the same, but the substitution will occur throughout all lines
in the file. However, only the FIRST occurrence of elf in each line
will be changed. To change all occurrences, append a `g' to the
command.

Any character can used instead of '/':
	s!elf!dwarf!g
substitutes dwarf for elf throughout the line.

The pattern to be replaced can be a regular expression, in the format
discussed above under SEARCHING. To use this effectively, there is one
additional thing about regular expression matching you need to
understand: when ed matches a regular expression on a line it matches
the LONGEST possible substring fitting the regular expression.

To see what this means, consider line 4 from the above example:

4	Who when we court and kiss, she cries: ``Forsooth, let go!''

Suppose we want to replace `court' with `hug' using a regexp. We might
think that
	4s/c.*t/hug/p 
would work fine. But executing it results in:
4	Who when we hug go!''  
because we told ed to search for the longest sequence of characters
that started with a `c' and ended with a `t'. This happens to be the
substring `court and kiss, she cries: ``Forsooth, let'. So be aware
when you do regular expression search and replacement, or you will get
unexpected results.


MISCELLANEOUS INFORMATION

1. How do I copy from a standard file?

Enter ed. Then do `r <file>'. Now you have something in the buffer.
Change it into what you want, then `w <newfile>'. This method also
copies file which are too large for the cp command.

2. How do I move and copy blocks of lines around?

To move a line (or several lines) use the `m' command. To copy a line
or several lines, use the `t' command. Do `hm' and `ht' from inside ed
to get the correct syntax of the commands.

3. I went link-dead while I was editing :-(. Did I lose my changes?

Probably not all of them, if any. In the directory where you were
editing <file> look for another file named dead_ed_<file>. It will
contain what could be saved of your changes.

4. Can I configure ed with settings I like?

Yes, to some extent. Use the set command. Do `hset' from within ed for
more information. Two settings the author likes are `set number' and
`set print'.

5. How do I better indent my code in ed?

You can use the `I' command to indent all the lines in your program,
or you can use the `set autoindent' option to preserve indentation
when you are entering text. Outside of ed, the indent command will
indent files, as well.

6. Why do I sometimes get 'No error' when I type just 'ed' ?

One nice feature in ed is that if you have edited a file under your home
directory, try to clone it or load it and an error occurs, you can type
'ed' without argument, and ed will be set up for the file where the error
happened plus it will write the first error found in that file.
