\input texinfotimes   @c -*-texinfo-*-
@setfilename ne.info
@settitle @code{ne}'s manual

@iftex
@afourpaper
@end iftex


@ignore

This file, besides being a normal Texinfo file, allows to generate on-line help
for ne. The program genhelp (a *very* dirty hack) does this. It is essential
that genhelp is applied to the text generated by the Amiga version of makeinfo
when applied to this file with the --no-headers and --amiga options. The GNU
original version outputs a bad looking file when called with --no-headers.

@end ignore

@ifinfo
This file documents ne, a text editor for UN*X.

Copyright (C) 1993 Sebastiano Vigna.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.
@end ifinfo

@setchapternewpage odd
@finalout

@titlepage
@title ne
@subtitle A nice editor
@subtitle Beta version 0.97
@author by Sebastiano Vigna

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1993 Sebastiano Vigna.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Free Software Foundation.

@end titlepage

@defindex co

@ifinfo

@node Top
@top

This file describes @code{ne}, a free text editor which runs under (hopefully
almost) any UN*X machine. @code{ne} is easy to use for the beginner, but
powerful and fully configurable for the wizard, and most sparing in its
resource usage.

@noindent Copyright (C) 1993 Sebastiano Vigna

@menu
* Introduction::
* Basics::
* Reference::
* Commands::
* Configuration::
* Hints and Tricks::
* Motivations and Design::
* Portability Problems::
* Acknowledgments::
* Concept Index::
* Command Index::
@end menu

@end ifinfo

@node Introduction
@chapter Introduction
@cindex LITHP
@cindex TurboText
@cindex Features

@code{ne} is a full screen text editor for @sc{un*x} (or, more precisely, for
@sc{posix}: @pxref{Motivations and Design}). I came to the decision of writing
such an editor after getting completely sick of @code{vi}, both from a feature
and user interface point of view. I needed an editor that I could use through a
telnet connection or a phone line, and that wouldn't fire off a full-blown
@sc{lithp}@footnote{This otherwise unremarkable language is distinguished by
the absence of an @samp{s} in its character set; users must substitute
@samp{th}.  @sc{lithp} is said to be useful in protheththing lithtth.}
operating system just to do some editing.

The main inspiration for this work came from Martin Taillefer's
@code{TurboText} for the Amiga, which is the best editor I ever saw, on any
computer.

The design goal of @code{ne} was to write an editor easy to use at first sight,
powerful, and completely configurable. Running on any terminal that @code{vi}
could handle was also a basic issue, because there is no use in getting
accustomed to a new tool if you cannot use it when you @emph{really} need it.
Finally, sparing resource usage was considered essential. @code{ne} currently
runs only on @sc{un*x} terminals, but a future release will provide an X
interface.

A concise overview of the main features follows:

@itemize @bullet{}

@item three user interfaces: control keystrokes, command line, and menus;
keystrokes and menus are completely configurable;

@item
the number of documents and clips, the dimensions of the display, and
the file/line lengths are limited only by the integer size of the machine;

@item
simple scripting language where scripts can be generated @i{via} an
idiotproof learn/play method;

@item
unlimited undo/redo capability (can be disabled with a command);

@item
automatic preferences system based on the extension of the file name being
edited;

@item
a file requester for easy file retrieval;

@item
extended regular expression search and replace a la @code{emacs} and
@code{vi};

@item
editing of binary files.

@end itemize

@node Basics
@chapter Basics

@noindent @i{Simple things should be simple, and complex things should be possible.} (Alan Kay)

@code{ne}'s user interface is essentially a compromise between the limits of
character driven terminals, and the power of GUIs. While I would
@emph{never} deny that @emph{real} editing is done without ever touching a
mouse, it is also true that it should be doable without ever touching a
manual. This two conflicting goals can be easily accomodated in a single
program if we can offer a series of interfaces which allow for a
differentiated usage.

In other words, it is unlikely that a @code{ne} wizard will ever have to
activate a menu, but in order to become an expert user you just have to use
the menus enough to learn by heart the most important keystrokes. A good
manual is always invaluable when one comes to configuration and esotheric
features, but not all users will ever need to change @code{ne}'s menus or
key bindings.

Another important thing is that powerful features should always be
accessible, at least in part, to every user. Putting a macro capability that
depends on learning @sc{lithp} is undoubtly a strange design choice. The average
user should be able to record his actions, replay them, and save them in a
humanly readable format for further usage and editing.

In the following sections we will make a quick tour of @code{ne}'s features.

@menu
* Starting::
* Loading and Saving::
* Editing::
* Basic Preferences::
* Basic Macros::
@end menu

@node Starting
@section Starting
@cindex Keyboard usage
@cindex Menu usage
@cindex Shortcuts

In order to start @code{ne}, just type @samp{ne} and press @key{Return}. If you
want to edit some specific file(s), you can put their name(s) on the command
line just after the command name, as for any @sc{un*x} command. Immediately
(hopefully), the screen of your terminal will be cleared (or filled with
the contents of the first file you specified).

At the bottom of the screen, you will see a line containing some numbers and
letters. It is named the @dfn{status bar}, because it reports to you part of
the internal state of the editor.

Writing text is pretty straightforward: if you terminal is properly
configured, every key will (should) do what you expect. Alphabetic
characters insert text, cursor keys move the cursor, and so on. You can use
the @key{Delete} and @key{Backspace} key in order to perform corrections. If
your keyboard has an @key{Insert} key, you can use it in order to toggle
insert mode. In general, @code{ne} tries to squeeze everything from your
keyboard---functions keys and special movement keys should work flawlessly
if your terminal is properly configured. If not, complain with your system
administrator.

At startup, the status bar has the following form:

@example
L:     1  C:     1  i      pvu t
@end example

@noindent (the numbers could be different, and a filename could be shown as
last item). You probably already guessed that the numbers after @samp{L:}
and @samp{C:} are the line and column numbers, respectively. The small
letters represent instead user flags that you can turn on and off. In
particular, the @samp{i} letter tells you that insert mode is on, while
@samp{p} indicates that the automatic preferences system is activated. For a
thorough explanation of the meaning of the flags on the status line, see
@ref{The Status Bar}.

Once you are accustomed with cursor movement and line editing, it is time to
press the @key{f1} (the first function key), or in case your keyboard does not
have such a key, @key{Escape}. Immediately, the @dfn{menu bar} will appear,
and the first menu will be drawn. You can now move around menus and menu items
by pressing the cursor keys. Moreover, a lower case alphabetic key will move to
the first item whose name starts with that letter, and an upper case alphabetic
key will move to the first menu whose name starts with that letter.

Moving around the menus should give you an idea of the capabilities of
@code{ne}. If you want to save your work, you should use the @samp{Save As...}
item from the @samp{Project} menu. Menus are fully discussed in @ref{Menus}.
When you want to exit from the menu system, press @key{f1} (or @key{Escape})
again. If you instead prefer to choose a command and execute it, move over the
respective menu item and press @key{Return}.

At the end of several menu items you will find strange symbols like @kbd{^A} or
@key{f1}. They represent @dfn{shortcuts} for the respective menu items. In
other words, instead of activating, selecting and executing a menu item, which
can take seconds, you can simply press a couple of keys. The symbol @samp{^} in
front of a character denotes the shortcut produced by the @key{Control} key
plus that character (I suppose here you are perfectly aware of the usage of the
@key{Control} key: it is just as if you had to type a capital letter with
@key{Shift}). The descriptions of the form @key{f}@var{n} represent instead
function keys. Note that under certain conditions (for instance, while using
@code{ne} through a @code{telnet} connection) some of the shortcuts could
not work, because they are trapped by the operating system for other purposes
(@pxref{Hints and Tricks}).

Finally, we have the third and last interface to @code{ne}'s features: the
command line. If you press @kbd{@key{Control}-K}, or @key{Escape} followed by
@samp{:} (a la @code{vi}), you will be requested some command to execute. Just
press @key{Return} for the time being.

In what follows, when explaining how to use a command, we will usually
describe the corresponding menu item. The corresponding shortcut and command
can be found, respectively, on the menu item itself, and in @ref{Menus}.

@node Loading and Saving
@section Loading and Saving
@cindex Loading a file
@cindex Quitting
@cindex Exiting
@cindex Closing a document
@cindex Opening a file
@cindex Saving a file
@cindex Writing a file
@cindex File requester

The first thing to learn about an editor is how to exit. @code{ne} has a
@code{Close} command which can be activated by pressing @kbd{@key{Control}-Q},
by choosing the @samp{Close} item of the @samp{Document} menu, or by activating
the command line with @kbd{@key{Control}-K}, writing @samp{cd} and pressing
@key{Return}. Its effect is to close the current document without saving any
modification (you will be requested to confirm your choice in case the
current document has been modified since the last save).

There is also a command @code{Quit}, which leaves the editor without saving any
modification, and an @code{Exit} command which saves the modified documents
before quitting.

This choice of shortcuts could surprise you---wouldn't the @code{Quit} be a
much better candidate for @kbd{@key{Control}-Q}? Well, experience shows that
the most common operation is closing a document, rather than quitting the
editor. If there is just one document, the two operations coincide (this is
typical, for instance, when you use @code{ne} for writing electronic mail), and
if there are many documents, it is far more common to close a single document
than all the existing documents.

If you want to load a file, you have to use the @code{Open} command, which can
be activated by pressing @kbd{@key{Control}-O}, by choosing the @samp{Open...}
item of the @samp{Project} menu, or by typing it on the command line (as in the
previous case). You will be prompted with the list of files and directories in
the current working directory (you can tell the directory names because they
end with a slash). You can move on any of them by using the cursor keys, or any
other movement key. Pressing an alphabetic key will move the cursor on the
first entry after the cursor starting with the given letter. When the cursor is
positioned over the file you want to open, just press @key{Return}, and the
file will be opened. If instead you move on a directory name, pressing
@key{Return} will display the contents of that directory.

You can also escape with @key{f1} or @key{Escape}, and type manually the file
name on the command line (or escape again, and abort the loading operation).

When you want to save a file, just use the command @code{Save}
(@kbd{@key{Control}-S}). It will use the current document name (and will
ask for one if none is available). @code{SaveAs}, on the contrary, will always
ask for a new name before saving the file.

If @code{ne} is interrupted by an external signal (for instance, if your
terminal crashes), it will try to save your work on some emergency files.
@xref{Emergency Save}.

@node Editing
@section Editing
@cindex Deleting characters
@cindex Deleting lines
@cindex Undeleting lines
@cindex Block operations
@cindex Clip usage
@cindex Multiple documents

An editor is presumably used for editing. If not, you could decide to not use
@code{ne}, because it just does that---it edits. It does not play
@code{Tetris}. It does not evaluate recursive functions. It does not solve your
love problems. It just allows you to edit.

The design of @code{ne} makes editing extremely natural and straightforward.
There is no special thing to do in order to start---I assume that if you
start an editor, you want to edit, and @emph{not} to give commands. Thus,
just press the keys of your keyboard, and see what happens.

@code{ne} provides two ways of deleting characters, bound to the
@key{Backspace} (or @kbd{@key{Control}-H}, if you have no such key) and to
the @key{Delete} key respectively. In the former case you delete the
character at the left of the cursor, while in the latter you delete the
character just under the cursor. This is in contrast with many @sc{un*x} editors,
which for unknown reasons decide to cripple your way of destroying
things---something notoriously much funnier than creating. (see also
@ref{DeleteChar}, and @pxref{Backspace}).

If you want to delete a line, you can use the @code{DeleteLine} command, or
@kbd{@key{Control}-Y}. A very nice feature of @code{ne} is that each time a
nonempty line is deleted, it is stored in a temporary buffer from which it can
be undeleted via the @code{UndelLine} command, or @kbd{@key{Control}-U} (see
also @ref{DeleteLine}, and @pxref{UndelLine}).

If you want to copy, cut, paste or erase a block of text, you have to set a
mark. This is done via the @code{Mark} command, activated by choosing the
@samp{Mark Block} item of the @samp{Edit} menu, or by pressing
@kbd{@key{Control}-B} (=block). This command toggles the mark (puts it in
the current cursors position, or remove it). Whenever the mark is set, the
zone between the mark and the cursor can be cut, copied or erased. Note that
by using @kbd{@key{Control}-@@} you can set a @emph{vertical} mark instead,
that allows to cut exactly rectangles of text. Whenever a mark has been set,
an @samp{M} appears on the command line; a @samp{V} appears instead if the
mark is vertical. If you forget where the mark is currently, you can use the
@samp{Goto Mark} menu item of the @samp{Search} menu in order to move to
cursor over it.

When you cut or copy a block, you can save it with the @samp{Save Clip...} menu
item of the @samp{Edit} menu. You can also load in memory a file with
@samp{Open Clip...}, and paste it anywhere. All such operation act on the
@dfn{current clip}, which is by default the clip 0. You can change the current
clip number with the @code{ClipNumber} command. @xref{ClipNumber}.

One of the most noteworthy features of @code{ne} is its @dfn{unlimited
undo/redo} capability. Each editing action is recorded, and can be played forth
and back as much as you like. Undo and redo are bound to the function keys
@key{f5} and @key{f6}.

Another interesting feature is the possibility of loading an unlimited number
of documents. If you activate the @code{NewDoc} command (using the
@samp{Document} menu, @kbd{@key{Control}-D} or the command line), a new, empty
document will be created. You can switch between the existing documents in
memory with @key{f2} and @key{f3}, which are bound to the @code{PrevDoc} and
@code{NextDoc} commands. If you have a lot of documents, the @samp{Select...}
menu item prompts you with the list of names of currently loaded documents, and
allows you to choose directly what to edit.

@node Basic Preferences
@section Basic Preferences
@cindex Preferences
@cindex Flags
@cindex Insert mode
@cindex Automatic preferences

@code{ne} has a number of @dfn{flags} which specify alternative behaviours, the
most prototypical example being the @dfn{insert} flag, which specifies if the
text you type in is inserted in the existing text, or overwrites it. You can
toggle this flag with the @samp{Insert} menu item of the @samp{Prefs} menu, or
with the @key{Insert} key of your keyboard (@dfn{toggle} means to change the
value of a flag from true to false, or from false to true; also @pxref{Insert}).

Another important flag is the @dfn{free form} flag, which specifies if the
cursor can be moved anywhere, or only on existing text (a la @code{vi}).
Programmers usually prefer non free form editing; text writers prefer free
form. @xref{FreeForm}, for some elaboration. The free form flag can be set
with the @samp{Free Form} menu item of the @samp{Prefs} menu

At this point, I suggest you to explore by trial and error the other flags
of the @samp{Prefs} menu. Instead, it is worth spending a couple of words
about @dfn{automatic preferences}, or, in short, @dfn{autoprefs}.

Having many flags ensures a high degree of flexibility, but can turn editing
into a nightmare if for each different kind of file loaded one has to turn
on and off dozens of options. The solution is having the program handling
all the details, depending on some characteristic of the file.

The solution chosen in @code{ne} is to look at the @dfn{extension} of the
name of a file, i.e., the last group of letters after a dot. For instance,
the extension of @file{ne.texinfo} is @samp{texinfo}, while the extension
of @file{source.c} is @samp{c}.

Whenever you select the @samp{Save AutoPrefs} menu item, @code{ne} saves in
a directory named @file{.ne} (in your home directory) a file with the same
name as the extension of the current document (postfixed with @samp{#ap}),
containing all the commands which will rebuild the current settings.
Whenever you will open a file with the same extension in its name, @code{ne}
will reload automagically the same set of preferences (there is a flag which
inhibits the process; @pxref{AutoPrefs}).

Finally, when you select the @samp{Save Def Prefs} menu item, a special
preferences file named @file{.default} is saved that is loaded whenever
@code{ne} is run, before loading any file. Here is the place to put in the
preferences you always want to be set.

Note also that a preferences file is just a macro (as described in the
following section). Thus, they can be edited manually if necessary.

@node Basic Macros
@section Basic Macros
@cindex Macro definition
@cindex Recording a macro
@cindex Saving a macro
@cindex Interrupting a macro
@cindex Interrupt character
@cindex Caching a macro
@cindex Unloading macros
@cindex Executing a macro

Very often, the programmer or the text writer has to repeat some complex
editing action over a series of similar blocks of text. Unless you are an
@code{awk} wizard, this is where @dfn{macros} come in.

Macros allows you to record complex actions and play them many times. They can
be saved on disk for further usage, edited, loaded, or bound to any key. This
allows to reconfigure each key of your keyboard with a complex action, if you
want so.

Recording a macro is very simple. The keystroke @kbd{@key{Control}-T} starts
and stop a macro recording (you can see you are actually recording if an
@samp{R} appears on the status bar). Whatever you do is registered, and when
you stop (again with @kbd{@key{Control}-T}) the recording process, you can play
the macro with the @samp{Play Once} item of the @samp{Macros} menu, or with the
@key{f9} key. If you want to repeat the action many times, the @code{Play}
command allows you to specify a number of times to repeat the macro. You
can always interrupt the execution with @kbd{@key{Control}-\}.

After recording a macro, you can save it with the @samp{Save Macro...} menu
item. Any macro file can be played (without modifying the current macro)
with the @samp{Macro...} menu item. Useful macros can be permanently bound
to a keystroke, as explained in @ref{Key Bindings}. Moreover, whenever
a command line does not specify an ``internal'' command, it is assumed
to specify the name of a macro to execute. Thus, you can execute macros
just by typing their complete file name.

In order to make this mechanism even more transparent, if the first attempt to
open a macro fails @code{ne} checks for a macro with the given name in the
@file{.ne} subdirectory of your home directory. This allows you to program
simple extensions to @code{ne}'s language. For instance, all automatic
preferences macros can be executed just by typing their names---if you have an
automatic preference for the @samp{doc} extension, by typing the command
@code{doc#ap} you will set @code{ne}'s flags exactly as if you loaded a file
ending with @samp{.doc}. In general, it is a good idea to save frequently used
macros in @code{$HOME/.ne}, so that you can invoke them just by name (of course,
you cannot recall in this way macros with the same name as a command).

Since loading a macro each time it is invoked would be a rather slow and
expensive process, once a macro has been executed it is cached internally.
The next invocations of the macro will used the cached version.

@noindent @strong{Warning:} the macro names are @emph{not} case sensitive or
path sensitive. @code{ne} caches internally only the file name of a macro, not
the path name, and uses a case insensitive comparison. That is, if you call
@samp{~/foobar/macro}, a subsequent call for @samp{/usr/MACRO} will use the
cached version. You can delete the cache by using the @code{UnloadMacros}
command. @xref{UnloadMacros}.


@node Reference
@chapter Reference

In this chapter we will methodically overview each part of @code{ne}. It
is a required reading for becoming an expert user, because some commands
and features are not available through menus.

@menu
* Arguments::
* The Status Bar::
* The Input Line::
* The Command Line::
* The Requester::
* Menus::
* Regular Expressions::
* Automatic Preferences::
* Emergency Save::
@end menu

@node Arguments
@section Arguments
@cindex Arguments
@cindex Startup macro
@cindex Skipping configuration files

The main argument you can give to @code{ne} is a list of files you want to
edit. They will be loaded within separate documents.

The @code{--noconfig} option allows to skip the reading of the key bindings and
menu configuration files (@pxref{Configuration}). This is essential if you are
experimenting some new configuration, and you make mistakes in it.

The @code{--macro @var{filename}} option allows to specify the name of a
macro that will be started just after all documents have been loaded. A
typical macro would move the cursor on a certain line.


@node The Status Bar
@section The Status Bar
@cindex Status bar
@cindex Line and column numbers
@cindex Fast GUI

The last line of the screen, the @dfn{status bar}, is reserved by @code{ne}
in order to display some information about its internal state. Note that on
most terminals is physically impossible to write a character on the last
column of this line, so that we are not really stealing precious space to
editing.

The status bar looks more or less like that:

@example
L:   31  C:   25  iabcwfpvurBMR* /foo/bar
@end example

Some of the letters may be missing---their presence is related to the value
of a series of flags, as we will see later.

The numbers after @samp{L:} and @samp{C:} represent the line and column of
the cursor position. The first line and the first column are numbered by 1.
They change while the cursor is moving, and this fact can really slow down
the cursor movement if you are using @code{ne} through a slow connection. In this
case, it is a good idea to turn off the status bar using the @samp{Status Bar}
menu item of hte @samp{Prefs} menu, or the @code{StatusBar} command.
@xref{StatusBar}. Note that if you really need it, it is anyway a good idea
to turn on the fast GUI mode using the @samp{Fast GUI} menu item of the
@samp{Prefs} menu, or the @code{FastGUI} command (@pxref{StatusBar}),
because in this case the status bar is not draw in reverse, and some
additional optimization can be done when refreshing it.

The letters after the line and column number represent the status of the flags
associated to a series of command. In detail:

@table @samp

@item i
appears if the insert flag is true. @xref{Insert}.

@item a
appears if the auto indent flag is true. @xref{AutoIndent}.

@item b
appears if the back search flag is true. @xref{SearchBack}.

@item c
appears if the case sensitive search flag is true. @xref{CaseSearch}.

@item w
appears if the word wrap flag is true. @xref{WordWrap}.

@item f
appears if the free form flag is true. @xref{FreeForm}.

@item p
appears if the automatic preferences flag is true. @xref{AutoPrefs}.

@item v
appears if the verbose macros flag is true. @xref{VerboseMacros}.

@item u
appears if the undo flag is true. @xref{DoUndo}.

@item r
appears if the read only flag is true. @xref{ReadOnly}.

@item t
appears if the turbo parameter is nonzero. @xref{Turbo}.

@item B
appears if the binary flag is true. @xref{Binary}.

@item M
appears if you are currently marking a block. @xref{Mark}.

@item V
can appear in place of @samp{M} if you are currently marking a vertical
block. @xref{MarkVert}.

@item R
appears if you are currently recording a macro. @xref{Record}.

@item *
appears if the document has been modified since the last save.

@end table

The file name appearing after this group of letters is the file name of
the current document. Very long file names may end off screen. Of course,
@code{ne} is keeping track internally of the complete file name, which
is used by the @code{Save} command, and as default input by the
@code{SaveAs} command. @xref{Save}, and @ref{SaveAs}.

Note that sometimes @code{ne} needs to communicate you some message. The
message is then usually written over the status bar, where it stays
until you do something (any such message ends with a full stop). Any action
(moving the cursor, inserting a character @i{et cetera}) will restore the
normal look of the status bar.


@node The Input Line
@section The Input Line
@cindex Input line
@cindex Escaping an input
@cindex Immediate input
@cindex Long input

The last line of the screen is usually occupied by the status bar (@pxref{The
Status Bar}); however, whenever you have to interact with @code{ne}, for
instance providing some input to a command which requires it, the last line
becomes the @dfn{input line}. You can see this because a @dfn{prompt} is displayed
at the start of the line, suggesting what kind of input is required. The
prompt always ends with a colon, so it is impossible to exchange it for an
error message.

There are two essentially different ways in which input can be done:
whenever @code{ne} just needs to know a simple decision which can be
expressed by one character, you can type it and @code{ne} will immediately
accept and use your input: it is called a @dfn{immediate} input. This is the
case, for instance, of the prompt which asks you if you really want to quit
a modified document. If, instead, a whole string is required, you can type
several characters, perform some editing actions, and end your input with
the @key{Return} key: it is called a @dfn{long input}. You can easily
distinguish between this two modes because in immediate mode the cursor is
not on the input line.

When doing a immediate input, there is usually a character appearing
just after the prompt. It is the default value, which is used if you
just press the @key{Return} key. Note that case is not significant in immediate
inputs. Moreover, if a yes/no choice is requested, @emph{anything} else than
@samp{y} will be taken as meaning a negative answer.

When doing a long input, there are a number of editing features available.
As anywhere else in @code{ne}, @emph{knowledge reuse} is the basic goal.

Essentially, you can edit the input line @emph{exactly as a line of text}.
All key bindings related to line editing work on the command line exactly as
in a document. This is true even of custom key bindings. Thus, no particular
explanation is needed here---just edit as you are used to. Moreover, the
contents of the input line can be replaced by the first line of the current
clip using the keystroke which is bound to the @code{Paste} command, usually
@kbd{@key{Control}-V}.

Note that if you type a line which is longer then the screen width, it is
scrolled away. This allows to input very long lines even on small monitors.
There is a limit of 1024 characters, but I do not really think you are going to
feel it as a crippling.

There is a useful feature of long inputs: you are often offered with a default
input value (for instance, if you change the @sc{tab} size, the old @sc{tab}
width). If you type immediately an alphabetic character, the default value is
completely erased. If instead you use any non alphabetical character (for
instance, you move the cursor or delete the first character), the default input
can be further edited. A simple way of keeping the default value without really
doing anything is to press the @key{Backspace} key (or any key which is bound to
the @code{Backspace} command). No character can be deleted, but being the first
key non alphabetical, the default input value will be retained.

You can always cancel a long input using @key{f1}, @key{Escape}, or in general
any key which is bound to the @code{Escape} command. The effect will vary
depending on what your were requested to input, but in general the execution
of the command requiring the input is stopped.


@node The Command Line
@section The Command Line
@cindex Command line

The command line is a typical (topical) way of controlling an editor on character
driven systems. It has some advantages in term of access speed, but it is a
complete failure from a user interface point of view. @code{ne} has a command
line which should be used whenever strange features have to be accessed, or
whenever you are enough accustomed to know by heart the commands you want to
use, and which are not bound to any key.

In order to access the command line, you have two possibilities: either
activating menu mode and typing a colon (@samp{:}), or typing
@kbd{@key{Control}-K} (or any key which is bound to the @code{Exec} command;
@pxref{Exec}). The first method will work regardless of any key binding
configuration if you activate the menus with the @key{Escape} key, since it is
not possible to reconfigure it.

Once you activate the command line, the status bar will turn into an input
line (@pxref{The Input Line}) with prompt @samp{Command:}, waiting for you
doing a long input. In other words, you can now type any command (possibly
with arguments), and when you press @key{Return} the command will be
executed.

If the command you specify does not appear in @code{ne}'s internal tables,
it is considered to be a macro name. @xref{Basic Macros}, for details.

@node The Requester
@section The Requester
@cindex Requester
@cindex File requester
@cindex Interrupting directory scanning
@cindex Help requester

In various situations, @code{ne} needs to ask you to choose one of several
strings (where ``several'' can mean a lot, even hundreds). For this kind of
event, the @dfn{requester} is issued. The requester displays the strings in
as many columns as possible, and let you move with the cursor from one
string to another. The strings can fill many screens, which are handled as
consecutive pages. Always in the spirit of knowledge reuse, all the
navigation keys work exactly as in normal editing. This is true even of
custom key bindings. Thus, for instance, you can move to the top or bottom
of the list with @kbd{@key{Control}-^} (in the standard keyboard
configuration).

As with the input line (@pxref{The Input Line}), you can confirm your input
with @key{Return} or escape the requester with @key{f1} (or the @key{Escape}
key, or whatever has been bound to the @code{Escape} command).

A special feature is bound to alphabetic characters: they move you on the next
entry starting with the letter you typed. The search is case insensitive, and
continues on the first string after having passed the last one.

An example of requester is the file requester that @code{ne} issues whenever a
file operation is going to take place. In this case, pressing @key{Return}
while on a directory name will enter the directory. Note also that, should the
requester take too long to appear, you can interrupt the directory scanning
with @kbd{@key{Control}-\}. However, the listing will likely be incomplete.

Another example of requester is the list of commands appearing when you use the
@code{Help} command. (Note that even the help text appearing on the screen is
handled by the requester---your ``choice'' of a line in the text is of course
discarded, but the flexibility of the requester allows to gain in code size,
since no separate code is necessary in order to display the on-line help.)

@node Menus
@section Menus
@cindex Menus

@code{ne}'s menus are extremely straightforward. The suggested way of
learning their use is by trial and error, with a peek here and there
at this manual when some doubts arise.

Each menu item of @code{ne}'s standard menu correspond exactly to a single
command. Thus, in explaining what each menu item allows you to do, you will
be simply referred to the section which explains the command relative to the
menu item.

If you plan to change @code{ne}'s menu (@pxref{Changing Menus}), you should
take a look at the file @file{default.menus} which comes with @code{ne}'s
distribution. It contains a complete menu configuration which clones the standard
one.

@menu
* Project::
* Documents::
* Edit::
* Search::
* Macros::
* Extras::
* Navigation::
* Prefs::
@end menu

@node Project
@subsection Project

The Project menu contains standard items which allow to load and save files.
Quitting or exiting (with save) @code{ne} is also possible.

@table @samp

@item Open
@xref{Open}.

@item Save
@xref{Save}.

@item Save As@dots{}
@xref{SaveAs}.

@item Clear
@xref{Clear}.

@item Quit
@xref{Quit}.

@item Exit
@xref{Exit}.

@item About
@xref{About}.

@end table

@node Documents
@subsection Documents

The Documents menu contains commands which create new documents, destroy
them, and browse through them.

@table @samp

@item New
@xref{NewDoc}.

@item Close
@xref{CloseDoc}.

@item Next
@xref{NextDoc}.

@item Prev
@xref{PrevDoc}.

@item Select...
@xref{SelectDoc}.

@end table

@node Edit
@subsection Edit

The Edit menu contains the commands related to cutting and pasting text.

@table @samp

@item Mark Block
@xref{Mark}.

@item Cut
@xref{Cut}.

@item Copy
@xref{Copy}.

@item Paste
@xref{Paste}.

@item Erase
@xref{Erase}.

@item Delete Line
@xref{DeleteLine}.

@item Mark Vert
@xref{MarkVert}.

@item Paste Vert
@xref{PasteVert}.

@item Open Clip...
@xref{OpenClip}.

@item Save Clip...
@xref{SaveClip}.

@end table

@node Search
@subsection Search

@table @samp

@item Find...
@xref{Find}.

@item Find RegExp...
@xref{FindRegExp}.

@item Replace...
@xref{Replace}.

@item Replace Once...
@xref{ReplaceOnce}.

@item Replace All...
@xref{ReplaceAll}.

@item Repeat Last
@xref{RepeatLast}.

@item Goto Line...
@xref{GotoLine}.

@item Goto Col...
@xref{GotoColumn}.

@item Goto Mark...
@xref{GotoMark}.

@item Match Bracket
@xref{MatchBracket}.

@end table

@node Macros
@subsection Macros

@table @samp

@item Record
@xref{Record}.

@item Stop
@xref{Record}.

@item Replace...
@xref{Replace}.

@item Play Once
@xref{Play}.

@item Play Many...
@xref{Play}.

@item Play Macro...
@xref{Macro}.

@item Open Macro...
@xref{OpenMacro}.

@item Save Macro...
@xref{SaveMacro}.

@end table

@node Extras
@subsection Extras

This menu contains a couple of special items.

@table @samp

@item Exec...
@xref{Exec}.

@item Help...
@xref{Help}.

@item Refresh
@xref{Refresh}.

@item Undo
@xref{Undo}.

@item Redo
@xref{Redo}.

@item Undel Line
@xref{UndelLine}.

@item Center
@xref{Center}.

@item Paragraph
@xref{Paragraph}.

@item ToUpper
@xref{ToUpper}.

@item ToLower
@xref{ToLower}.

@item Capitalize
@xref{Capitalize}.

@end table


@node Navigation
@subsection Navigation

@table @samp

@item Move Left
@xref{MoveLeft}.

@item Move Right
@xref{MoveRight}.

@item Line Up
@xref{LineUp}.

@item Line Down
@xref{LineDown}.

@item Prev Page
@xref{PrevPage}.

@item NextPage
@xref{NextPage}.

@item Top/Bottom
@xref{ToggleSEOF}.

@item Beg Of Line
@xref{MoveSOL}.

@item End Of Line
@xref{MoveEOL}.

@item Prev Word
@xref{PrevWord}.

@item Next Word
@xref{NextWord}.

@end table

@node Prefs
@subsection Prefs

@table @samp

@item Tab Size...
@xref{TabSize}.

@item Insert/Over
@xref{Insert}.

@item Free Form
@xref{FreeForm}.

@item Status Bar
@xref{StatusBar}.

@item Fast GUI
@xref{FastGUI}.

@item Word Wrap
@xref{WordWrap}.

@item Right Margin
@xref{RightMargin}.

@item Auto Indent
@xref{AutoIndent}.

@item Load Prefs...
@xref{LoadPrefs}.

@item Save Prefs...
@xref{SavePrefs}.

@item Load AutoPrefs
@xref{LoadAutoPrefs}.

@item Save AutoPrefs
@xref{SaveAutoPrefs}.

@item Save Def Prefs
@xref{SaveDefPrefs}.

@end table

@node Regular Expressions
@section Regular Expressions
@cindex Regular Expressions

Regular expressions are a powerful way of specifying complex search
and replace operations.

@subsection Syntax

The following section is taken (with minor modifications) from the GNU regular
expression library documentation, and is Copyright @copyright{} Free Software
Foundation.

A regular expression describes a set of strings.  The simplest case is one
that describes a particular string; for example, the string @samp{foo} when
regarded as a regular expression matches @samp{foo} and nothing else.
Nontrivial regular expressions use certain special constructs so that they
can match more than one string.  For example, the regular expression
@samp{foo|bar} matches either the string @samp{foo} or the string
@samp{bar}; the regular expression @samp{c[ad]*r} matches any of the strings
@samp{cr}, @samp{car}, @samp{cdr}, @samp{caar}, @samp{cadddar} and all other
such strings with any number of @samp{a}'s and @samp{d}'s.

Regular expressions have a syntax in which a few characters are special
constructs and the rest are @dfn{ordinary}.  An ordinary character is a
simple regular expression which matches that character and nothing else. The
special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*}, @samp{+},
@samp{?}, @samp{[}, @samp{]} , @samp{(}, @samp{)} and @samp{\}.  Any other
character appearing in a regular expression is ordinary, unless a @samp{\}
precedes it.@refill

For example, @samp{f} is not a special character, so it is ordinary,
and therefore @samp{f} is a regular expression that matches the string @samp{f}
and no other string.  (It does @emph{not} match the string @samp{ff}.)  Likewise,
@samp{o} is a regular expression that matches only @samp{o}.

Any two regular expressions @var{a} and @var{b} can be concatenated.
The result is a regular expression which matches a string if @var{a}
matches some amount of the beginning of that string and @var{b}
matches the rest of the string.

As a simple example, we can concatenate the regular expressions
@samp{f} and @samp{o} to get the regular expression @samp{fo},
which matches only the string @samp{fo}.  Still trivial.

Note: special characters are treated as ordinary ones if they are in
contexts where their special meanings make no sense.  For example,
@samp{*foo} treats @samp{*} as ordinary since there is no preceding
expression on which the @samp{*} can act. It is poor practice to depend on
this behavior; better to quote the special character anyway, regardless of
where is appears.

The following are the characters and character sequences which have special
meaning within regular expressions. Any character not mentioned here is not
special; it stands for exactly itself for the purposes of searching and
matching.

@table @samp
@item .
is a special character that matches anything except a newline. Using
concatenation, we can make regular expressions like @samp{a.b} which matches
any three-character string which begins with @samp{a} and ends with
@samp{b}.

@item *
is not a construct by itself; it is a suffix, which means the preceding
regular expression is to be repeated as many times as possible.  In
@samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matches
@samp{f} followed by any number of @samp{o}'s.

The case of zero @samp{o}'s is allowed: @samp{fo*} does match
@samp{f}.

@samp{*} always applies to the @emph{smallest} possible preceding
expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
@samp{fo}.

@item +
@samp{+} is like @samp{*} except that at least one match for the preceding
pattern is required for @samp{+}.  Thus, @samp{c[ad]+r} does not match
@samp{cr} but does match anything else that @samp{c[ad]*r} would match.

@item ?
@samp{?} is like @samp{*} except that it allows either zero or one match for
the preceding pattern.  Thus, @samp{c[ad]?r} matches @samp{cr} or @samp{car}
or @samp{cdr}, and nothing else.

@item [ @dots{} ]
@samp{[} begins a @dfn{character set}, which is terminated by a @samp{]}.
In the simplest case, the characters between the two form the set.
Thus, @samp{[ad]} matches either @samp{a} or @samp{d},
and @samp{[ad]*} matches any string of @samp{a}'s and @samp{d}'s
(including the empty string), from which it follows that
@samp{c[ad]*r} matches @samp{car}, @i{et cetera}.

Character ranges can also be included in a character set, by writing two
characters with a @samp{-} between them.  Thus, @samp{[a-z]} matches any
lower-case letter.  Ranges may be intermixed freely with individual
characters, as in @samp{[a-z$%.]}, which matches any lower case letter or
@samp{$}, @samp{%} or period.

Note that the usual special characters are not special any more inside a
character set.  A completely different set of special characters exists
inside character sets: @samp{]}, @samp{-} and @samp{^}.

To include a @samp{]} in a character set, you must make it
the first character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.
To include a @samp{-}, you must use it in a context where it cannot possibly
indicate a range: that is, as the first character, or immediately
after a range.

@item [^ @dots{} ]
@samp{[^} begins a @dfn{complement character set}, which matches any
character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches all
characters @emph{except} letters and digits.@refill

@samp{^} is not special in a character set unless it is the first character.
The character following the @samp{^} is treated as if it were first (it may
be a @samp{-} or a @samp{]}).

@item ^
is a special character that matches the empty string -- but only if at the
beginning of a line in the text being matched.  Otherwise it fails to match
anything.  Thus, @samp{^foo} matches a @samp{foo} which occurs at the
beginning of a line.

@item $
is similar to @samp{^} but matches only at the end of a line. Thus,
@samp{xx*$} matches a string of one or more @samp{x}'s at the end of a
line.

@item \
has two functions: it quotes the above special characters (including
@samp{\}), and it introduces additional special constructs.@refill

Because @samp{\} quotes special characters, @samp{\$} is a regular
expression which matches only @samp{$}, and @samp{\[} is a regular
expression which matches only @samp{[}, and so on.

For the most part, @samp{\} followed by any character matches only that
character.  However, there are several exceptions: characters which, when
preceded by @samp{\}, are special constructs.  Such characters are always
ordinary when encountered on their own.

@item |
specifies an alternative. Two regular expressions @var{a} and @var{b} with
@samp{|} in between form an expression that matches anything that either
@var{a} or @var{b} will match.

Thus, @samp{foo|bar} matches either @samp{foo} or @samp{bar} but no other
string.

@samp{|} applies to the largest possible surrounding expressions.  Only a
surrounding @samp{( @dots{} )} grouping can limit the grouping power of
@samp{|}.

@item ( @dots{} )
is a grouping construct that serves three purposes:

@enumerate
@item
To enclose a set of @samp{|} alternatives for other operations.
Thus, @samp{(foo|bar)x} matches either @samp{foox} or @samp{barx}.

@item
To enclose a complicated expression for the postfix @samp{*} to operate on.
Thus, @samp{ba(na)*} matches @samp{bananana}, etc., with any (zero or
more) number of @samp{na}'s.

@item
To mark a matched substring for future reference.

@end enumerate

This last application is not a consequence of the idea of a parenthetical
grouping; it is a separate feature which happens to be assigned as a second
meaning to the same @samp{( @dots{} )} construct because there is no
conflict in practice between the two meanings.  Here is an explanation of
this feature:

@item \@var{digit}
After the end of a @samp{( @dots{} )} construct, the matcher remembers the
beginning and end of the text matched by that construct.  Then, later on in
the regular expression, you can use @samp{\} followed by @var{digit} to mean
``match the same text matched the @var{digit}'th time by the @samp{(
@dots{} )} construct.''  The @samp{( @dots{} )} constructs are numbered
in order of commencement in the regexp.

The strings matching the first nine @samp{( @dots{} )} constructs appearing
in a regular expression are assigned numbers 1 through 9 in order of their
beginnings.
@samp{\1} through @samp{\9} may be used to refer to the text matched by
the corresponding @samp{( @dots{} )} construct.

For example, @samp{(.+)\1} matches any non empty string that is composed of
two identical halves.  The @samp{(.+)} matches the first half, which may be
anything non empty, but the @samp{\1} that follows must match the same exact
text.

@item \b
matches the empty string, but only if it is at the beginning or
end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
@samp{foo} as a separate word.  @samp{\bball(s|)\b} matches
@samp{ball} or @samp{balls} as a separate word.

@item \B
matches the empty string, provided it is @emph{not} at the beginning or end
of a word.

@item \<
matches the empty string, but only if it is at the beginning
of a word.

@item \>
matches the empty string, but only if it is at the end of a word.

@item \w
matches any word-constituent character.

@item \W
matches any character that is not a word-constituent.
@end table

@subsection Replacing regular expressions

Also the replacement string has some special feature when doing a regular
expression search and replace. Exactly as during the search, @samp{\} followed
by @var{digit} stands for ``the text matched the @var{digit}'th time by the
@samp{( @dots{} )} construct in the search expression''. Moreover, @samp{\0}
represent the whole string matched by the regular expression. Thus, for
instance, the replace string @samp{\0\0} has the effect of doubling any string
matched.

Another example: if you search for @samp{(a+)(b+)}, substituting with
@samp{\2x\1}, you will match any string composed by a series of @samp{a}'s
followed by a series of @samp{b}'s, and you will substitute for it the
string obtained by moving the @samp{a} in front of the @samp{b}'s, adding
moreover @samp{x} inbetween. For instance, @samp{aaaab} will be matched and
substitued by @samp{bxaaaa}.

Note that the backslash character can escape itself. Thus, in order to put a
baskslash in the replacement string, you have to use @samp{\\}.


@node Automatic Preferences
@section Automatic Preferences
@cindex Automatic preferences

Automatic preferences let you set up a custom configuration that will be
automatically loaded whenever you open a file with a given extension. For
instance, you could like a @sc{tab} size of three while editing C sources, but
eight could be more palatable while writing electronic mail.

The use of the feature is definitely straightforward: you simply use the
@samp{Save AutoPrefs} menu item (or the @code{SaveAutoPrefs} command;
@pxref{SaveAutoPrefs}) when the current document has the given extension, and
the current configuration suits your tastes. The internal status of a series of
options is then recorded as a macro, containing commands which reproduce the
current configuration. The macro is then saved in the @file{$HOME/.ne}
directory (which is created, if necessary) with the name given by the
extension, postfixed with @samp{#ap}. Thus, the C sources automatic
preferences file will be named @samp{c#ap}, the one of @TeX{} files @samp{tex#ap},
and so on.

The macros are generated with short or long command names depending on the
status of the verbose macros flag. @xref{VerboseMacros}.

Automatic preferences file are loaded and executed whenever a file with a known
extension is opened. Note that you can edit manually such files, and even
insert commands, but any command which does something else than setting a flag
will be rejected, and an error message will be issued.


@node Emergency Save
@section Emergency Save
@cindex Emergency Save

Sometimes it can happen that @code{ne} is interrupted by an abnormal event
(for instance, the crash of your terminal). In this cases, it will try, if
it is given the possibility, to save all unsaved documents in its current
directory. Named documents will have their name prefixed with a @samp{#}.
Unnamed documents will be named using hexadecimal numbers obtained by
some addresses in memory which will make them unique.

@node Commands
@chapter Commands
@cindex Commands

Everything @code{ne} can do is specified through a command. Commands can be
manually typed on a command line, bound to a key, to a menu item, or grouped
into macros for easier manipulation. If you want to fully exploit the power of
@code{ne}, you will be faced sooner or later with using directly commands.

@menu
* Generals::
* File Commands::
* Document Commands::
* Clip Commands::
* Search Commands::
* Macros Commands::
* Undo Commands::
* Formatting Commands::
* Preferences Commands::
* Navigation Commands::
* Editing Commands::
* Support Commands::
@end menu

@node Generals
@section Generals
@cindex Long names
@cindex Short names
@cindex Command arguments
@cindex Flags
@cindex Repeating actions
@cindex Escape conventions
@cindex Quoting conventions

Every command of @code{ne} has a long and a short name. Except in a very few
cases, the short name is given by two or three letters which are the initials
of the words which form the long name. Thus, for instance, @code{SearchBack}
has short name @code{SB}. However, most used commands such as @code{Exit} have
one-letter short names (@code{X}), and @code{StatusBar}'s short name is
@code{ST} in order to avoid clashes with @code{SearchBack}'s.

A command has always at most an argument. This is a chosen limitation, which
allows @code{ne}'s parsing of command and macros to be very fast (a hash table
with no conflicts decodes the command name). Moreover, it almost cancel
all problems related to delimitators, escape characters, @i{et cetera}.
The unique argument can be a number, a string, or a flag modifier. You can
easily distinguish these three cases even without this manual by looking at
what the @code{Help} command says about the given command.

Strings are general purpose parameters. Numbers are used to modify internal
parameters, such as the size of a @sc{tab}. Flag modifiers are an optional
number which is interpreted as follows:

@itemize @bullet{}

@item
0 means clearing the flag;

@item
1 (or any positive number) means setting the flag;

@item
no number means toggling the flag.

@end itemize

Thus, @code{StatusBar 1} will activate that status bar, while @code{I} will
toggle insert/overstrike. This design choice is due to the fact that, most of
the time, during interactive editing one is faced with @emph{changing} a
flag; for instance, one is in insert mode and wants to overstrike, or
viceversa. Absolute settings (i.e., with a number) are useful essentially
for macros. It is reasonable to keep the fastest approach for the most
frequent interactive event.

When a number represent the times @code{ne} should repeat an action, it is
always understood that the command will terminate anyway when the condition
for applying it are not longer true. For instance, the @code{Paragraph} commands
accepts the number of paragraphs to format. But if not enough paragraphs
exists in the text, only the available ones will be formatted.

This allows to easily perform operation on the whole text by specifying
preposterously huge numbers as arguments. @code{ToUpper 2000000000} will
(hopefully) upper the case of all the words in the document. Note that
this is much faster than recording a macro with a command and playing
it many times, because the command has to be parsed just one time.

In any case, if a macro or a repeated operation takes to long, you can stop
it using the interrupt key (@kbd{@key{Control}-\}).

In order to handle situations such as an argument string starting with a
space, @code{ne} implements the following simple mechanism: an argument
string can be included in quotes, provided that the closing quote is the
last character of the command line.

The main advantage of this approach is that no escape convention is
necessary when putting quotes inside a quoted string, since @code{ne} can
use contextual information in order to tell the real delimitator. The only
case needing a special treatment is the case of an argument string starting
and ending with a quote: unless it is again enclosed in quotes, @code{ne}
will believe the quotes are delimitators, and act accordingly.

@ignore

It is essential that, in the following sections, all cross references
explaining the text of a command point only to another command, unless they are
inside an @ifclear autohelp / @endif pair. This way, the text can be
automagically extracted for the on-line help with the Amiga version of makeinfo.

@end ignore

@node File Commands
@section File Commands

These commands allow to open and save files.

@menu
* Clear::
* Open::
* Save::
* SaveAs::
@end menu

@node Clear
@subsection Clear
@coindex Clear

@noindent Syntax: @code{Clear}@*
@noindent Abbreviation: @code{CL}

@noindent destroys the contents of the current document and of its undo
buffer. Moreover, the document becomes unnamed. If the current document is
marked as modified, you have to confirm the action.

@node Open
@subsection Open
@coindex Open

@noindent Syntax: @code{Open [@var{filename}]}@*
@noindent Abbreviation: @code{O}

@noindent loads the file specified by the @var{filename} string into the
current document.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line, the default being the current document name, if available.

If at the time the command is issued the current document is marked as
modified, you have to confirm the action.


@node Save
@subsection Save
@coindex Save

@noindent Syntax: @code{Save}@*
@noindent Abbreviation: @code{S}

@noindent saves the current document using its default file name.

If the current document is unnamed, the file requester is opened, and you
are prompted to select a file (you can inhibit the file requester opening by
using the @code{NoFileReq} command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line.


@node SaveAs
@subsection SaveAs
@coindex SaveAs

@noindent Syntax: @code{SaveAs [@var{filename}]}@*
@noindent Abbreviation: @code{SA}

@noindent saves the current document using the specified string as file name.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can enter the file name on the
input line, the default being the current document name, if available.

@node Document Commands
@section Document Commands

@menu
* Quit::
* Exit::
* NewDoc::
* CloseDoc::
* NextDoc::
* PrevDoc::
* SelectDoc::
@end menu

@node Quit
@subsection Quit
@coindex Quit

@noindent Syntax: @code{Quit}@*
@noindent Abbreviation: @code{Q}

@noindent closes all documents and exits. If some document is modified, you
have to confirm the action.


@node Exit
@subsection Exit
@coindex Exit

@noindent Syntax: @code{Exit}@*
@noindent Abbreviation: @code{X}

@noindent saves all modified documents, closes them and exits. If
some document cannot be saved, the action is suspended and an error message
is printed.


@node NewDoc
@subsection NewDoc
@coindex NewDoc

@noindent Syntax: @code{NewDoc}@*
@noindent Abbreviation: @code{N}

@noindent creates a new, empty, unnamed document which becomes the current document.
The position of the document in the document list is just after the current
document. The preferences of the new document are obtained by cloning the
preferences of the current document.

@node CloseDoc
@subsection CloseDoc
@coindex CloseDoc

@noindent Syntax: @code{CloseDoc}@*
@noindent Abbreviation: @code{CD}

@noindent closes the current document. The document is removed from
@code{ne}'s list and, in case it is the only existing document, @code{ne}
exits. If the document was modified from the last save, you have to
confirm your choice.

@node NextDoc
@subsection NextDoc
@coindex NextDoc

@noindent Syntax: @code{NextDoc}@*
@noindent Abbreviation: @code{ND}

@noindent sets as current document the next document in the document list.


@node PrevDoc
@subsection PrevDoc
@coindex PrevDoc

@noindent Syntax: @code{PrevDoc}@*
@noindent Abbreviation: @code{PD}

@noindent sets as current document the previous document in the document list.

@node SelectDoc
@subsection SelectDoc
@coindex SelectDoc

@noindent Syntax: @code{SelectDoc}@*
@noindent Abbreviation: @code{SD}

@noindent opens a requester containing the names of all the
documents in memory. You can select the document you want to edit.

If you escape from the requester, you can enter the document name on the
input line, the default being the current document name, if available.

This command is really useful only if you have a large (say, more than 10)
number of documents loaded. Otherwise, @code{NextDoc} and @code{PrevDoc} should
be enough. @xref{NextDoc}, and @ref{PrevDoc}.


@node Clip Commands
@section Clip Commands

These commands control the clipping system.

@menu
* Mark::
* MarkVert::
* Copy::
* Cut::
* Paste::
* PasteVert::
* Erase::
* OpenClip::
* SaveClip::
* ClipNumber::
@end menu

@node Mark
@subsection Mark
@coindex Mark

@noindent Syntax: @code{Mark [0|1]}@*
@noindent Abbreviation: @code{M}

@noindent sets the mark at the current position or cancels the previous mark.
The mark can then be used in order to perform clip operations. The clip
commands act on the characters laying between the mark and the cursor.

If you call this command with no arguments, it will toggle the mark. If you
specify 0 or 1, the mark will be canceled or set to the current position,
respectively.  A capital @samp{M} appears on the status bar, if the mark is
active.

@xref{Record}, for the reason why the mark is implemented as a flag.

@node MarkVert
@subsection MarkVert
@coindex MarkVert

@noindent Syntax: @code{MarkVert [0|1]}@*
@noindent Abbreviation: @code{MV}

@noindent is the same as @code{Mark}, but the mark is interpreted as vertical
by the clip handling commands. This means that the region manipulated by the
cut/paste commands is the rectangle having as vertices the cursor and the mark.
Moreover, a capital @samp{V}, rather than a capital @samp{M}, will appear on
the status bar. Vertical cut/paste operations are most useful for handling
structured program indentation.

@node Copy
@subsection Copy
@coindex Copy

@noindent Syntax: @code{Copy [@var{n}]}@*
@noindent Abbreviation: @code{C}

@noindent copies the contents of the characters laying between the cursor
and the mark into the clip specified by the optional numeric argument, the
default clip being the current clip, which can be set with the
@code{ClipNumber} command (@pxref{ClipNumber}). If the current mark was
vertical, the rectangle of characters defined by the cursor and the mark is
copied instead.


@node Cut
@subsection Cut
@coindex Cut

@noindent Syntax: @code{Cut [@var{n}]}@*
@noindent Abbreviation: @code{CU}

@noindent acts just like @code{Copy}, but also deletes the block being copied.


@node Paste
@subsection Paste
@coindex Paste

@noindent Syntax: @code{Paste [@var{n}]}@*
@noindent Abbreviation: @code{P}

@noindent pastes the contents of specified clip, the default being current
clip, which can be set with the @code{ClipNumber} command
(@pxref{ClipNumber}), at the cursor position.


@node PasteVert
@subsection PasteVert
@coindex PasteVert

@noindent Syntax: @code{PasteVert [@var{n}]}@*
@noindent Abbreviation: @code{PV}

@noindent pastes vertically the contents of the specified clip, the default
being the current clip. Each line of the clip is inserted on consecutive
lines at the horizontal cursor position.


@node Erase
@subsection Erase
@coindex Erase

@noindent Syntax: @code{Erase}@*
@noindent Abbreviation: @code{E}

@noindent acts like @code{Cut}, but the block is just deleted, and not
copied into any clip.


@node OpenClip
@subsection OpenClip
@coindex OpenClip

@noindent Syntax: @code{OpenClip [@var{filename}]}@*
@noindent Abbreviation: @code{OC}

@noindent loads the given file name as the current clip (just as if you
copied it; @pxref{Copy}).

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can enter the file name on the
input line.

@node SaveClip
@subsection SaveClip
@coindex SaveClip

@noindent Syntax: @code{SaveClip [@var{filename}]}@*
@noindent Abbreviation: @code{SC}

@noindent saves the current clip on the given file name.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can enter the file name on the
input line.

@node ClipNumber
@subsection ClipNumber
@coindex ClipNumber

@noindent Syntax: @code{ClipNumber [@var{n}]}@*
@noindent Abbreviation: @code{CN}

@noindent sets the current clip number. This number is used by
@code{OpenClip} and @code{SaveClip}, and by @code{Copy}, @code{Cut} and
@code{Paste} if they are called without any argument. Its default value is
zero. @var{n} is limited only by the integer size of the machine @code{ne}
is running on.

If the optional argument @var{n} is not specified, you can enter it on the
input line, the default being the current clip number.

@node Search Commands
@section Search Commands

These commands control the search system.

@menu
* Find::
* FindRegExp::
* Replace::
* ReplaceOnce::
* ReplaceAll::
* RepeatLast::
* MatchBracket::
* SearchBack::
* CaseSearch::
@end menu

@node Find
@subsection Find
@coindex Find

@noindent Syntax: @code{Find [@var{pattern}]}@*
@noindent Abbreviation: @code{F}

@noindent searches for the given pattern. The cursor is positioned on the
first occurrence of the pattern, or an error message is given. The direction
and the case sensitivity of the search are established by the value of the
@code{SearchBack} and @code{CaseSearch} flags. See @ref{SearchBack} and
@ref{CaseSearch}.

If the optional argument @var{pattern} is not specified, you can enter it on
the input line, the default being the last pattern used.


@node FindRegExp
@subsection FindRegExp
@coindex FindRegExp

@noindent Syntax: @code{FindRegExp [@var{pattern}]}@*
@noindent Abbreviation: @code{FX}

@noindent searches the buffer for the given extended regular expression
@ifclear autohelp
(@pxref{Regular Expressions})
@end ifclear
. The cursor is positioned on the first string
matching the expression. The direction and the kind of search are established
by the value of the @code{SearchBack} and @code{CaseSearch} flags. See
@ref{SearchBack} and @ref{CaseSearch}.

If the optional argument @var{pattern} is not specified, you can enter it on
the input line, the default being the last pattern used.

@node Replace
@subsection Replace
@coindex Replace

@noindent Syntax: @code{Replace [@var{string}]}@*
@noindent Abbreviation: @code{R}

@noindent moves on the first match of the most recent find string or regular
expression, and then asks you which action to perform. You can choose among
the following actions:

@itemize @bullet

@item
replacing the string found with the given string and moving to the next match
(@samp{Yes});

@item
moving to the next match (@samp{No});

@item
replacing the string found with the given string, and stop the search (@samp{Last});

@item
stopping immediately the search (@samp{Quit});

@item
replacing @emph{all} occurrences of the find string with the given string
(@samp{All});

@item
reverting the search direction (@samp{Backward} or @samp{Forward});
this choice will also modify the value of the @code{SearchBack} flag.
@xref{SearchBack}.

@end itemize

This command is mainly useful for interactive editing. @samp{ReplaceOnce}
and @samp{ReplaceAll} are more suited to macros.

If no find string was ever specified, you can enter it on the input line.
If the optional argument @var{string} is not specified, you can enter it on
the input line, the default being the last string used.

Note that normally a search starts just one character after the cursor.
However, when @code{Replace} is invoked, the search starts at the character
just @emph{under} the cursor, so that you can safely @code{Find} a pattern
and @code{Replace} it without having to move back.

If you want to speed up @code{ne} while replacing all occurrences, you
can set the turbo parameter. @xref{Turbo}.

@noindent @strong{Warning:} when recording a macro (@pxref{Record}), there
is no trace in the macro of your interaction with @code{ne} during the
replacement process. When the macro is played, you will have again to choose
which actions to perform. If you want to apply automatic replacement of
strings for a certain number of times, you should look at @ref{ReplaceOnce},
@ref{ReplaceAll} and @ref{RepeatLast}.

@node ReplaceOnce
@subsection ReplaceOnce
@coindex ReplaceOnce

@noindent Syntax: @code{ReplaceOnce [@var{string}]}@*
@noindent Abbreviation: @code{R1}

@noindent acts just like @code{Replace}, but without any interaction with
you (unless there is no find string). The first string matched by the last
@code{Find} pattern, if existing, is replaced by the given replacement
string.

If the optional argument @var{string} is not specified, you can enter it on
the input line, the default being the last string used.

@node ReplaceAll
@subsection ReplaceAll
@coindex ReplaceAll

@noindent Syntax: @code{ReplaceAll [@var{replacement string}]}@*
@noindent Abbreviation: @code{RA}

@noindent is similar to  @code{ReplaceOnce}, but replaces @emph{all}
occurrences of the last @code{Find} pattern with the given replacement
string.

If the optional argument @var{string} is not specified, you can enter it on
the input line, the default being the last string used.

If you want to speed up @code{ne} while replacing all occurrences, you
can set the turbo parameter. @xref{Turbo}.

@node RepeatLast
@subsection RepeatLast
@coindex RepeatLast

@noindent Syntax: @code{RepeatLast [@var{times}]}@*
@noindent Abbreviation: @code{RL}

@noindent repeats for the given number of times the last find or replace operation
(with replace we mean here a single replace, even if the last @code{Replace}
operation ended with a global substitution).

This command is mainly useful for researching a given number of times, or
replacing something a given number of times. The standard technique for
accomplishing this is:

@enumerate

@item
@code{Find} (or @code{FindRegExp}) the string you are interested in;

@item
if you want to repeat a replace operation, @code{ReplaceOnce} with
the replacement string you are interested in;

@item
now issue a @code{RepeatLast @var{n}-1} command, where @var{n} is the
number of occurrences you wanted to skip over, or replace.

@end enumerate

The important thing about this sequence of actions is that it will
work this way even in a macro. The @code{Replace} command cannot be used
in a macro unless you really want to interact with @code{ne} during the
macro execution. This is the only reason why the commands @code{Replace}
and @code{ReplaceOnce} are provided.


@node MatchBracket
@subsection MatchBracket
@coindex MatchBracket

@noindent Syntax: @code{MatchBracket}@*
@noindent Abbreviation: @code{MB}

@noindent moves the cursor over the bracket associated to the bracket the
cursor is on. If the cursor is not on a bracket, or there is no bracket
associated to the current one, an error message is issued. @samp{@{@}},
@samp{()}, @samp{[]} and @samp{<>} are recognized.

@node SearchBack
@subsection SearchBack
@coindex SearchBack

@noindent Syntax: @code{SearchBack [0|1]}@*
@noindent Abbreviation: @code{SB}

@noindent sets the back search flag. When this flag is true, every search or
replacement command is performed backwards.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{b} will appear on the status bar if the flag is true.

Note that this flag can be also set by the interaction happening during a
replace. @xref{Replace}.

@node CaseSearch
@subsection CaseSearch
@coindex CaseSearch

@noindent Syntax: @code{CaseSearch [0|1]}@*
@noindent Abbreviation: @code{CS}

@noindent sets the case sensitivity flag. When this flag is true, the search commands
distinguish between the upper case and lower case versions of a letter. By
default the flag is false, since this seems to be what most user want.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{c} will appear on the status bar if the flag is true.

@node Macros Commands
@section Macros Commands

The following commands control the macro system.

@menu
* Record::
* Play::
* Macro::
* OpenMacro::
* SaveMacro::
* UnloadMacros::
@end menu

@node Record
@subsection Record
@coindex Record

@noindent Syntax: @code{Record [0|1]}@*
@noindent Abbreviation: @code{Rec}

@noindent sets the recording state flag. When this flag becomes true, a
macro recording is initiated. When it becomes false, the macro recording is
stopped, and the macro can be played (@pxref{Play}).

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. An upper case
@samp{R} will appear on the status bar if the flag is true.

The reason for providing a flag instead of an explicit start/stop recording
command pair is that this way it is possible to bind to the same key the
start and stop recording command, whilst still being able to specifying
``absolute'' menu items (by using @code{Record 0} and @code{Record 1}). For
instance, the default key binding for @kbd{@key{Control}-T} is simply
@code{Record}, which means that this keystroke can be used both for
initiating and for terminating a macro recording.

@node Play
@subsection Play
@coindex Play

@noindent Syntax: @code{Play [@var{times}]}@*
@noindent Abbreviation: @code{PL}

@noindent plays the current macro for the given number of times. If the
optional argument @var{times} is not specified, you can enter it on the
input line.

During the playing of a macro, no updating of the screen is
done unless you are forced into an interaction with @code{ne} (for instance,
via the @code{Replace} command). A (possibly iterated) macro execution
terminates as soon as its stream of instructions is exhausted, or one of its
commands returns an error. This means that, for instance, you can perform
some complex operation on all the lines contaning a certain pattern by
recording a macro that searches for the pattern and performs the operation,
and then @code{Play}ing it a preposterously huge number of times.

@node Macro
@subsection Macro
@coindex Macro

@noindent Syntax: @code{Macro [@var{filename}]}@*
@noindent Abbreviation: @code{MA}

@noindent executes the given file name as a macro.

If the optional @var{filename} argument is not specified, the file requester is
opened, and you are prompted to select a file (you can inhibit the file
requester opening by using the @code{NoFileReq} command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line.

Note that macros whose name does not conflict with a command can be called
without using @code{Macro}. Whenever @code{ne} is required to perform a command
it cannot find in its internal tables, it will look for a macro named as the
command. If also this search fails, @code{ne} looks in @file{$HOME/.ne} for
a file named as the command.

@noindent @strong{Warning:} in order to (greatly) improve efficiency, the
first time a macro is executed it is cached into a hash table and is kept
@emph{forever} in memory (unless the @code{UnloadMacros} command is issued;
@pxref{UnloadMacros}). The next time a macro with the same file name is
invoked, the cached list is searched for it before accessing the file using a
case insensitive string comparison. That is, if you call @samp{~/foobar/macro}, a
subsequent call for @samp{/usr/MACRO} or just @samp{MaCrO} will use the cached
version. Note that the cache table is global to @code{ne}.


@node OpenMacro
@subsection OpenMacro
@coindex OpenMacro

@noindent Syntax: @code{OpenMacro [@var{filename}]}@*
@noindent Abbreviation: @code{OM}

@noindent loads the given file name as the current macro (just as if you
@code{Record}ed it; @pxref{Record}).

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line.

@node SaveMacro
@subsection SaveMacro
@coindex SaveMacro

@noindent Syntax: @code{SaveMacro [@var{filename}]}@*
@noindent Abbreviation: @code{SM}

@noindent saves the current macro on the given file name.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line.

This command is of course most useful for saving macros you just
@code{Record}ed. The macros can then be loaded as normal text files for
further editing, if necessary.


@node UnloadMacros
@subsection UnloadMacros
@coindex UnloadMacros

@noindent Syntax: @code{UnloadMacros}@*
@noindent Abbreviation: @code{UM}

@noindent frees the macro cache list. After this command, the @code{Macro}
command will be forced to search for the file containing the macro it has to
play.

This command is really useful only if you are experimenting with a macro
bound to some keystroke, and you are interactively modifying it and playing
it. @code{UnloadMacros} forces @code{ne} to always look for the newer
version available.


@node Undo Commands
@section Undo Commands

The following commands control the undo system.

@menu
* Undo::
* Redo::
* UndelLine::
* DoUndo::
@end menu

@node Undo
@subsection Undo
@coindex Undo

@noindent Syntax: @code{Undo [@var{n}]}@*
@noindent Abbreviation: @code{U}

@noindent undos the last @var{n} actions. If @var{n} is not specified, it is
assumed to be one. Once you undo a number of actions, you can @code{Redo}
them (or part of them; @pxref{Redo}).


@node Redo
@subsection Redo
@coindex Redo

@noindent Syntax: @code{Redo [@var{n}]}@*
@noindent Abbreviation: @code{RE}

@noindent redos the last @var{n} actions. If @var{n} is not specified, it is assumed
to be one. You can only @code{Redo} actions which have been @code{Undo}ne.
@xref{Undo}.

@node UndelLine
@subsection UndelLine
@coindex UndelLine

@noindent Syntax: @code{UndelLine [@var{n}]}@*
@noindent Abbreviation: @code{UL}

@noindent inserts at the cursor position for @var{n} times the last non-empty line
which was deleted with the @code{DeleteLine} command. If @var{n} is not
specified, it is assumed to be one.

This command is most useful in that it allows a very fast way of moving
one line around. Just delete it, and undelete it somewhere else. It is
also an easy way to replicate a line without getting involved with clips.

Note that this command works independently of the status of the
@code{DoUndo} flag. @xref{DoUndo}.

@node DoUndo
@subsection DoUndo
@coindex DoUndo

@noindent Syntax: @code{DoUndo [0|1]}@*
@noindent Abbreviation: @code{DU}

@noindent sets the flag which enables or disables the undo system. When you turn
the undo system off, all the recorded actions are discarded, and the undo
buffers are reset.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{u} will appear on the status bar if the flag is true.

The usefulness of this option relies in the fact the undo system is a major
memory eater. If you plan to do massive editing (say, @code{Cut}s and
@code{Paste}s of megabytes of text) it is a good idea to disable the undo
system, both for improving (doubling) performance and for using less (half)
memory. Except for this, on a virtual memory system I see no reason to not
keep @code{DoUndo} always true, and this is indeed the default.


@node Formatting Commands
@section Formatting Commands

The following commands allow simple formatting operations on the text.

@menu
* Center::
* Paragraph::
* ToUpper::
* ToLower::
* Capitalize::
* RightMargin::
* WordWrap::
* AutoIndent::
@end menu

@node Center
@subsection Center
@coindex Center

@noindent Syntax: @code{Center [@var{n}]}@*
@noindent Abbreviation: @code{CE}

@noindent centers @var{n} lines from the cursor position onwards. If @var{n}
is not specified, it is assumed to be one. The lines are centered with
spaces, relatively to the value of the right margin as set by the
@code{RightMargin} command. @xref{RightMargin}.

@node Paragraph
@subsection Paragraph
@coindex Paragraph

@noindent Syntax: @code{Paragraph [@var{n}]}@*
@noindent Abbreviation: @code{PA}

@noindent reformats @var{n} paragraphs from the cursor position onwards. If
@var{n} is not specified, it is assumed to be one. The paragraph are
formatted relatively to the value of the right margin as set by the
@code{RightMargin} command. @xref{RightMargin}.

Do not ever ask me to implement justified paragraphing. I @emph{hate}
non-proportional justified text.

If you think paragraphing should insert ``smart'' spaces after full stops
and colons, and do other such ``smart'' things, you should consider using a
text formatter. @TeX{} is usually the best choice.


@node ToUpper
@subsection ToUpper
@coindex ToUpper

@noindent Syntax: @code{ToUpper [@var{n}]}@*
@noindent Abbreviation: @code{TU}

@noindent uppers the case of the letters from the cursor position up to the
end of a word, and moves to the fist letter of next word for @var{n} times.

The description of the command may seem a little bit cryptic. What is really
happening is that there are situations where you want to upper case only the
last part of a word. In this case, you just have to position the cursor in
the first character you want to upper case, and use this command with no
argument.

If you apply @code{ToUpper} on the first character of a word, it will
just upper case @var{n} words.

@node ToLower
@subsection ToLower
@coindex ToLower

@noindent Syntax: @code{ToLower [@var{n}]}@*
@noindent Abbreviation: @code{TL}

@noindent acts exactly like @code{ToUpper}, but lowers the case. @xref{ToUpper}.

@node Capitalize
@subsection Capitalize
@coindex Capitalize

@noindent Syntax: @code{Capitalize [@var{n}]}@*
@noindent Abbreviation: @code{CA}

@noindent acts exactly like @code{ToUpper}, but capitalizes, i.e., makes the first
letter upper case and the other ones lower case. @xref{ToUpper}.

@node RightMargin
@subsection RightMargin
@coindex RightMargin

@noindent Syntax: @code{RightMargin [@var{n}]}@*
@noindent Abbreviation: @code{RM}

@noindent sets the right margin for all formatting operations, and for @code{WordWrap}
(@pxref{WordWrap}).

If the optional argument @var{n} is not specified, you can enter it on the
input line, the default being the current clip number.

A value of 0 for @var{n} will force @code{ne} to use (what it thinks it is)
the current screen width as right margin.


@node WordWrap
@subsection WordWrap
@coindex WordWrap

@noindent Syntax: @code{WordWrap [0|1]}@*
@noindent Abbreviation: @code{WW}

@noindent sets the word wrap flag. When this flag is true, @code{ne} will automatically
break lines of text longer than the current right margin (@pxref{RightMargin})
while you type them.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{w} will appear on the status bar if the flag is true.


@node AutoIndent
@subsection AutoIndent
@coindex AutoIndent

@noindent Syntax: @code{AutoIndent [0|1]}@*
@noindent Abbreviation: @code{AI}

@noindent sets the auto indent flag. When this flag is true, @code{ne} will
automatically insert tabs and spaces on a new line (created by an
@code{InsertLine} command, or by automatic word wrapping) in such a way to
replicate the initial spaces of the previous line. Most useful for indenting
programs.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{a} will appear on the status bar if the flag is true.

@code{AutoIndent} features a nice interaction with @code{Undo}. Whenever a
new line is created, the insertion of spaces is recorded as a separate
action in the undo buffer (with respect to the line creation). If you are
not satisfied with the indentation, just give the @code{Undo} command and
the indentation will disappear (but the new line will remain in place, since
its creation has been recorded as a separate action). @xref{Undo}.


@node Preferences Commands
@section Preferences Commands

These commands allows you to set your preferences.

@menu
* AutoPrefs::
* Binary::
* Insert::
* FastGUI::
* FreeForm::
* NoFileReq::
* StatusBar::
* ReadOnly::
* TabSize::
* Turbo::
* VerboseMacros::
* LoadPrefs::
* SavePrefs::
* LoadAutoPrefs::
* SaveAutoPrefs::
* SaveDefPrefs::
@end menu

@node AutoPrefs
@subsection AutoPrefs
@coindex AutoPrefs

@noindent Syntax: @code{AutoPrefs [0|1]}@*
@noindent Abbreviation: @code{AP}

@noindent sets the automatic preferences flag. If this flag is true, each
time an @code{Open} command is executed and a file is loaded, @code{ne} will
look for an automatic preferences file in the @file{$HOME/.ne} directory.
The preferences file name is given by the extension of the file loaded,
postfixed with @samp{#ap}. Thus, for instance, C sources have an associated
@file{c#ap} file.
@ifclear autohelp
@xref{Automatic Preferences}.
@end ifclear

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{p} will appear on the status bar if the flag is true.

@node Binary
@subsection Binary
@coindex Binary

@noindent Syntax: @code{Binary [0|1]}@*
@noindent Abbreviation: @code{B}

@noindent sets the binary flag. When this flag is true, loading and saving a
document is performed in a different way. On loading, only nulls are
considered newlines; on saving, nulls are saved instead of newlines. This
allows you to edit a binary file, fix some text in it, and save it without
modifying anything else. Normally, linefeeds, carriage returns and nulls are
considered newlines, so that what you load will have all nulls and carriage
returns substituted by newlines when saved.

Note that since usually binary files contain a great number of nulls, and every
null will be considered a line terminator, the memory necessary for loading a
binary file can be several times bigger than the length of the file. Thus,
binary editing within @code{ne} should be considered not a normal, but rather
an exceptional activity.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. An upper
case @samp{B} will appear on the status bar if the flag is true.

@node Insert
@subsection Insert
@coindex Insert

@noindent Syntax: @code{Insert [0|1]}@*
@noindent Abbreviation: @code{I}

@noindent sets the insert flag. If this flag is true, the text you type is
inserted, otherwise it overwrites the existing characters.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{i} will appear on the status bar if the flag is true.

@node FastGUI
@subsection FastGUI
@coindex FastGUI

@noindent Syntax: @code{FastGUI [0|1]}@*
@noindent Abbreviation: @code{FG}

@noindent sets the fast graphical user interface flag. When this flag is
true, @code{ne} tries to print as few as possible while displaying menus and
the status bar. In particular, menu items are highlighted by the cursor
only, and the status bar is not highlighted (which allows to print it with
less characters). This option is very useful if you are using @code{ne}
through a slow connection.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively.

@node FreeForm
@subsection FreeForm
@coindex FreeForm

@noindent Syntax: @code{FreeForm [0|1]}@*
@noindent Abbreviation: @code{FF}

@noindent sets the free form flag. When this flag is true, you can move with
the cursor anywhere on the screen, even where no text is present (however,
you cannot move inside the space expansion of a @sc{tab} character).

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{f} will appear on the status bar if the flag is true.

The issue free-form-versus-non-free-form is a major religious war that is
engaging hackers, lusers and programmers from day one. The due of the
implementor is to allow both choices, and to set as default the correct one
(in his humble opinion). In this case, non-free-form.

@node NoFileReq
@subsection NoFileReq
@coindex NoFileReq

@noindent Syntax: @code{NoFileReq [0|1]}@*
@noindent Abbreviation: @code{NFR}

@noindent sets the file requester flag. When this flag is true,
the file requester is never opened, under any circumstances.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively.

@node StatusBar
@subsection StatusBar
@coindex StatusBar

@noindent Syntax: @code{StatusBar [0|1]}@*
@noindent Abbreviation: @code{ST}

@noindent sets the status bar flag. When this flag is true, the status bar is
displayed at the bottom of the screen. There are only two reasons to
turn off the status bar I am aware of:

@itemize @bullet{}

@item
if you are using @code{ne} through a slow connection, updating the
lines/columns indicators can really slow down editing;

@item
scrolling caused by cursor movement on terminals which do not allow to set a
scrolling region can give annoying flashes at the bottom of the screen.

@end itemize

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively.

@node ReadOnly
@subsection ReadOnly
@coindex ReadOnly

@noindent Syntax: @code{ReadOnly [0|1]}@*
@noindent Abbreviation: @code{RO}

@noindent sets the read only flag. When this flag is true, no editing can be
performed on the document (any such attempt produces an error message). This
flag is automatically set whenever you @code{Open} a file which you cannot
write to. @xref{Open}.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{r} will appear on the status bar if the flag is true.

@node TabSize
@subsection TabSize
@coindex TabSize

@noindent Syntax: @code{TabSize [@var{size}]}@*
@noindent Abbreviation: @code{TS}

@noindent sets the number of spaces @code{ne} will use when expanding a
@sc{tab} character.

If the optional argument @var{size} is not specified, you can enter it on the
input line, the default being the current @sc{tab} size. Allowed values are
strictly between 0 and half the width of the screen.

@node Turbo
@subsection Turbo
@coindex Turbo

@noindent Syntax: @code{Turbo [@var{steps}]}@*
@noindent Abbreviation: @code{T}

@noindent sets the turbo parameter. When it is nonzero, iterated actions and
global replaces will update at most @var{steps} line of the screen; then,
update will be delayed to the end of the action.

This feature is most useful when massive operations (such as replacing
thousands of occurrences of a pattern) have to be performed. After having
updated @var{steps} lines, @code{ne} can proceed at maximum speed, because
no visual update has to be performed.

The value of the turbo parameter has to be adapted to the kind of terminal
you are using. Very high values (or zero, which completely disables the
delayed update) can be good on high-speed terminals, since the time required
for the visual updates is very small, and it is always safer to look at what
the editor is really doing. On slow terminals, however, a small values ensures
that operations such as paragraph formatting will not take too long.

You have to be careful about setting the turbo parameter too low. @code{ne}
keeps track internally of the part of the screen which needs refresh in a
very rough way. This means that a value of less than, say, 8 will force it
to do a lot of unnecessary refresh.

The default value of this parameter is given by twice the number of lines of
the screen, which for several reasons does seem to offer a good value.


@node VerboseMacros
@subsection VerboseMacros
@coindex VerboseMacros

@noindent Syntax: @code{VerboseMacros [0|1]}@*
@noindent Abbreviation: @code{VM}

@noindent sets the verbose macros flag. When this flag is true, all macros
generated by recording or by automatic preferences saving will contain
full names, instead of short names. This is highly desirable if you are
going to manually editing the macro, but it can slow down considerably the
parsing of the commands.

If you call this command with no arguments, it will toggle the flag. If you
specify 0 or 1, the flag will be set to false or true, respectively. A lower
case @samp{v} will appear on the status bar if the flag is true.

The only reason to use this flag is when recording a macro that will be
played a great number of times. Automatic preferences files are too short to
be an issue with respect to execution timing.

@node LoadPrefs
@subsection LoadPrefs
@coindex LoadPrefs

@noindent Syntax: @code{LoadPrefs [@var{filename}]}@*
@noindent Abbreviation: @code{LP}

@noindent loads the given preference file, and sets the current preferences
accordingly.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line, the default being the current document name, if available.

Note that a preferences file is just a macro containing option modifiers
only. You can manually edit a preferences file for special purposes, such
filtering out specific settings.
@ifclear autohelp
@xref{Hints and Tricks}.
@end ifclear

@node SavePrefs
@subsection SavePrefs
@coindex SavePrefs

@noindent Syntax: @code{SavePrefs [@var{filename}]}@*
@noindent Abbreviation: @code{SP}

@noindent saves the current preferences on the given file.

If the optional @var{filename} argument is not specified, the
file requester is opened, and you are prompted to select a file (you
can inhibit the file requester opening by using the @code{NoFileReq}
command; @pxref{NoFileReq}).

If you escape from the file requester, you can input the file name on the
command line, the default being the current document name, if available.

@node LoadAutoPrefs
@subsection LoadAutoPrefs
@coindex LoadAutoPrefs

@noindent Syntax: @code{LoadAutoPrefs}@*
@noindent Abbreviation: @code{LAP}

@noindent loads the preferences file in @file{$HOME/.ne} relative to the
current document file name. If the current file name has no extension, the
default preferences are loaded.

@node SaveAutoPrefs
@subsection SaveAutoPrefs
@coindex SaveAutoPrefs

@noindent Syntax: @code{SaveAutoPrefs}@*
@noindent Abbreviation: @code{SAP}

@noindent saves the current preferences on the file in @file{$HOME/.ne}
relative to the current document file name. If the current file name has no
extension, an error message is issued.

@node SaveDefPrefs
@subsection SaveDefPrefs
@coindex SaveDefPrefs

@noindent Syntax: @code{SaveDefPrefs}@*
@noindent Abbreviation: @code{SDP}

@noindent saves the current preferences on the @file{$HOME/.ne/.default} file.
This file is always loaded by @code{ne} at startup.

@node Navigation Commands
@section Navigation Commands

These commands allows you to move in a document.

@menu
* MoveLeft::
* MoveRight::
* LineUp::
* LineDown::
* GotoLine::
* GotoColumn::
* GotoMark::
* PrevPage::
* NextPage::
* PrevWord::
* NextWord::
* MoveEOL::
* MoveSOL::
* MoveEOF::
* MoveSOF::
* MoveEOW::
* ToggleSEOF::
* ToggleSEOL::
* SetBookMark::
* GotoBookMark::
@end menu

@node MoveLeft
@subsection MoveLeft
@coindex MoveLeft

@noindent Syntax: @code{MoveLeft [@var{n}]}@*
@noindent Abbreviation: @code{ML}

@noindent moves the cursor on the left by one character @var{n} times. If
the optional @var{n} argument is not specified, it is assumed to be one.

@node MoveRight
@subsection MoveRight
@coindex MoveRight

@noindent Syntax: @code{MoveRight [@var{n}]}@*
@noindent Abbreviation: @code{MR}

@noindent moves the cursor on the right by one character @var{n} times. If
the optional @var{n} argument is not specified, it is assumed to be one.

@node LineUp
@subsection LineUp
@coindex LineUp

@noindent Syntax: @code{LineUp [@var{n}]}@*
@noindent Abbreviation: @code{LU}

@noindent moves the cursor up by one line @var{n} times. If the optional
@var{n} argument is not specified, it is assumed to be one.

@node LineDown
@subsection LineDown
@coindex LineDown

@noindent Syntax: @code{LineDown [@var{n}]}@*
@noindent Abbreviation: @code{LD}

@noindent moves the cursor down by one line @var{n} times. If the optional
@var{n} argument is not specified, it is assumed to be one.

@node GotoLine
@subsection GotoLine
@coindex GotoLine

@noindent Syntax: @code{GotoLine [@var{line}]}@*
@noindent Abbreviation: @code{GL}

@noindent moves the cursor on the @var{line}th line of the file. If @var{line}
is greater than the number of lines of the file, the cursor is moved on the
last line.

If the optional argument @var{line} is not specified, you can enter it on
the input line, the default input being the current line number.

@node GotoColumn
@subsection GotoColumn
@coindex GotoColumn

@noindent Syntax: @code{GotoColumn [@var{column}]}@*
@noindent Abbreviation: @code{GC}

@noindent moves the cursor on the @var{column}th column of the file.

If the optional argument @var{line} is not specified, you can enter it on
the input line, the default input being the current column number.

@node GotoMark
@subsection GotoMark
@coindex GotoMark

@noindent Syntax: @code{GotoMark}@*
@noindent Abbreviation: @code{GM}

@noindent moves the cursor to the current mark, if existing. @xref{Mark}.

This command is mainly useful if you forgot where you started marking.
If you want to record a position in a file and jump on it later, you
may want to use a bookmark. @xref{SetBookmark}.

@node PrevPage
@subsection PrevPage
@coindex PrevPage

@noindent Syntax: @code{PrevPage [@var{n}]}@*
@noindent Abbreviation: @code{PP}

@noindent moves the cursor @var{n} pages backward, if the cursor is on the
first line of the screen; otherwise moves the cursor on the first line of
the screen, and moves by @var{n}-1 pages. If the optional @var{n} argument
is not specified, it is assumed to be one.


@node NextPage
@subsection NextPage
@coindex NextPage

@noindent Syntax: @code{NextPage [@var{n}]}@*
@noindent Abbreviation: @code{NP}

@noindent moves the cursor @var{n} pages forward, if the cursor is on the
last line of the screen; otherwise moves the cursor on the last line of the
screen, and moves by @var{n}-1 pages. If the optional @var{n} argument is
not specified, it is assumed to be one.


@node PrevWord
@subsection PrevWord
@coindex PrevWord

@noindent Syntax: @code{PrevWord [@var{n}]}@*
@noindent Abbreviation: @code{PW}

@noindent moves the cursor on the previous word @var{n} times. If the
optional @var{n} argument is not specified, it is assumed to be one (in
which case, if the cursor is on a word the effect is just to move it on the
start of that word).

@node NextWord
@subsection NextWord
@coindex NextWord

@noindent Syntax: @code{NextWord [@var{n}]}@*
@noindent Abbreviation: @code{NW}

@noindent moves the cursor on the next word @var{n} tumes. If the optional
@var{n} argument is not specified, it is assumed to be one.

@node MoveEOL
@subsection MoveEOL
@coindex MoveEOL

@noindent Syntax: @code{MoveEOL}@*
@noindent Abbreviation: @code{EOL}

@noindent moves the cursor to the end of the current line.

@node MoveSOL
@subsection MoveSOL
@coindex MoveSOL

@noindent Syntax: @code{MoveSOL}@*
@noindent Abbreviation: @code{SOL}

@noindent moves the cursor to the start of the current line.

@node MoveEOF
@subsection MoveEOF
@coindex MoveEOF

@noindent Syntax: @code{MoveEOF}@*
@noindent Abbreviation: @code{EOF}

@noindent moves the cursor to the end of the document (@code{EOF} = end of
file).

@node MoveSOF
@subsection MoveSOF
@coindex MoveSOF

@noindent Syntax: @code{MoveSOF}@*
@noindent Abbreviation: @code{SOF}

@noindent moves the cursor to the start of the document (@code{SOF} = start
of file).

@node MoveEOW
@subsection MoveEOW
@coindex MoveEOW

@noindent Syntax: @code{MoveEOW}@*
@noindent Abbreviation: @code{EOW}

@noindent moves the cursor to the end of the word it is on.

This commands is extremely useful in macros, because it allows to copy
precisely the word the cursor is on.
@ifclear autohelp
@xref{Hints and Tricks}.
@end ifclear

@node ToggleSEOF
@subsection ToggleSEOF
@coindex ToggleSEOF

@noindent Syntax: @code{ToggleSEOF}@*
@noindent Abbreviation: @code{TSEOF}

@noindent moves the cursor to the start of document, if it is not already
there; otherwise, moves it to the end of the document.

This kind of toggling command (also @pxref{ToggleSEOL}) is very useful in
order to gain some keystroke on systems with very few keys. See also
@ref{MoveSOF}, and @ref{MoveEOF}.

@node ToggleSEOL
@subsection ToggleSEOL
@coindex ToggleSEOL

@noindent Syntax: @code{ToggleSEOL}@*
@noindent Abbreviation: @code{TSEOL}

@noindent moves the cursor to the start of the current line, if it is not
already there; otherwise, moves it to the end of the current line.

This kind of toggling command (also @pxref{ToggleSEOF}) is very useful in
order to gain some keystroke on systems with very few keys. See also
@ref{MoveSOL}, and @ref{MoveEOL}.

@node SetBookmark
@subsection SetBookmark
@coindex SetBookmark

@noindent Syntax: @code{SetBookmark [@var{n}]}@*
@noindent Abbreviation: @code{SBM}

@noindent sets the @var{n}th bookmark to the current cursor position. If the
optional @var{n} argument is not specified, it is assumed to be zero. There
are ten bookmarks, numbered from 0 to 9.


@node GotoBookMark
@subsection GotoBookmark
@coindex GotoBookmark

@noindent Syntax: @code{GotoBookmark [@var{n}]}@*
@noindent Abbreviation: @code{GBM}

@noindent moves the cursor to the @var{n}th bookmark. If the optional
@var{n} argument is not specified, it is assumed to be zero. There are ten
bookmarks, numbered from 0 to 9.

@node Editing Commands
@section Editing Commands

This commands allows to modify directly a document.

@menu
* InsertChar::
* DeleteChar::
* Backspace::
* InsertLine::
* DeleteLine::
* DeleteEOL::
@end menu

@node InsertChar
@subsection InsertChar
@coindex InsertChar

@noindent Syntax: @code{InsertChar @var{code}}@*
@noindent Abbreviation: @code{IC}

@noindent inserts a character whose @sc{ascii} code is @var{code} at the current
cursor position. @var{char code} has always to be different from 0. All the
currently active options (insert, word wrapping, auto indent, @i{et cetera})
are applied.

Note that inserting a line feed (10) is completely different from inserting
a line with @code{InsertLine}. @code{InsertChar 10} puts the control char
@kbd{@key{Control}-J} in the text at the current cursor position.
@xref{InsertLine}.

@node DeleteChar
@subsection DeleteChar
@coindex DeleteChar

@noindent Syntax: @code{DeleteChar [@var{n}]}@*
@noindent Abbreviation: @code{DC}

@noindent deletes @var{n} characters from the text. If the optional @var{n}
argument is not specified, it is assumed to be one. Deleting a character
when the cursor is just after the last char on a line will join a line with
the following one; in other word, the carriage return between the two lines
will be deleted.

@node Backspace
@subsection Backspace
@coindex Backspace

@noindent Syntax: @code{Backspace [@var{n}]}@*
@noindent Abbreviation: @code{BS}

@noindent acts like @code{DeleteChar}, but moves to the right the cursor before
deleting each character.

@node InsertLine
@subsection InsertLine
@coindex InsertLine

@noindent Syntax: @code{InsertLine [@var{n}]}@*
@noindent Abbreviation: @code{IL}

@noindent inserts @var{n} lines at the current cursor position, breaking the
current line. If the optional @var{n} argument is not specified, it is
assumed to be one.

@node DeleteLine
@subsection DeleteLine
@coindex DeleteLine

@noindent Syntax: @code{DeleteLine [@var{n}]}@*
@noindent Abbreviation: @code{DL}

@noindent deletes the line the cursor is on, putting it in the temporary buffer
from which it can be undeleted. @xref{UndelLine}. If the optional @var{n} argument
is not specified, it is assumed to be one. Note that this actions is in no
way inverse with respect to @code{InsertLine}.

@node DeleteEOL
@subsection DeleteEOL
@coindex DeleteEOL

@noindent Syntax: @code{DeleteEOL @var{n}}@*
@noindent Abbreviation: @code{DE}

@noindent deletes all characters from the current cursor position to the end
of the line.

This command could be easily implemented with a macro, but it is such a
common, basic editing feature that it seemed worth a separate implementation.


@node Support Commands
@section Support Commands

These commands perform several useful actions.

@menu
* About::
* Beep::
* Exec::
* Flash::
* Help::
* NOP::
* Refresh::
* System::
* Escape::
@end menu

@node About
@subsection About
@coindex About

@noindent Syntax: @code{About}@*
@noindent Abbreviation: @code{About}

@noindent displays a simple information line about @code{ne} on the status bar.

@node Beep
@subsection Beep
@coindex Beep

@noindent Syntax: @code{Beep}@*
@noindent Abbreviation: @code{BE}

@noindent beeps. If your terminal cannot beep, it flashes. If it cannot
flash, nothing happens (but you have a very bad terminal).

@node Exec
@subsection Exec
@coindex Exec

@noindent Syntax: @code{Exec}@*
@noindent Abbreviation: @code{EX}

@noindent prompts the user on the input line, asking for a command, and
executes it. It is never registered while recording a macro (but the command
you type is).

This command is mainly useful for key bindings, menu configurations, and in
manually programmed macros.

Note that if the command you specify does not appear in @code{ne}'s internal
tables, it is considered to be a macro name. @xref{Macro}.

@noindent @node Flash
@subsection Flash
@coindex Flash

@noindent Syntax: @code{Flash}@*
@noindent Abbreviation: @code{FL}

@noindent acts as @code{Beep}, but interchanging the words ``beep'' and ``flash''.
Same comments apply. @xref{Beep}.

@node Help
@subsection Help
@coindex Help

@noindent Syntax: @code{Help @var{name}}@*
@noindent Abbreviation: @code{H}

@noindent displays some help about the command @var{name} (both the short and
the long version are accepted). If no argument is given, a list of all existing
commands in long form is displayed, allowing you to choose one. You can browse
the help text with the standard navigation keys. If you press @key{Return}, the
command list will be displayed again. If you press @key{f1} or @key{Escape},
you will return to normal editing.

This command is never registered while recording a macro, so that you can
safely access the help system while recording. @xref{Record}.

@node NOP
@subsection NOP
@coindex NOP

@noindent Syntax: @code{NOP}@*
@noindent Abbreviation: @code{NOP}

@noindent does nothing. Mainly useful for inhibiting standard key bindings.

@node Refresh
@subsection Refresh
@coindex Refresh

@noindent Syntax: @code{Refresh}@*
@noindent Abbreviation: @code{REF}

@noindent refreshes the display. This command is very important, and should
preferably be bound to the @kbd{@key{Control}-L} sequence, for historical
reasons. It can always happen that a noisy phone line or a quirk in the
terminal corrupts the display. This command restores it from scratch.

@node System
@subsection System
@coindex System

@noindent Syntax: @code{System [@var{command}]}@*
@noindent Abbreviation: @code{SYS}

@noindent asks the shell to execute @var{command}. The terminal is
temporarily reset to the state it was in before @code{ne}'s activation, and
@var{command} is started. When the execution is finished, @code{ne} returns
in control.

@ignore

Before starting the execution, @code{ne} defines a series of environment
variables which can thus be used on the command line. The variables allow
to refer to parts of the internal state of @code{ne}.

@end ignore

@node Escape
@subsection Escape
@coindex Escape

@noindent Syntax: @code{Escape}@*
@noindent Abbreviation: @code{ESC}

@noindent toggles on and off the menus, or escapes from the input line. This
command is mainly useful for reprogramming the menu activator, and it is
never registered while recording a macro. @xref{Record}.

@node Configuration
@chapter Configuration

In this chapter we will see how the menus and the key bindings of
@code{ne} can be completely configured.

@menu
* Key Bindings::
* Changing Menus::
@end menu

@node Key Bindings
@section Key Bindings
@cindex Key bindings
@cindex Configuring the keyboard

@code{ne} allows you to associate to any keystroke any command. In order to
accomplish this task, you have to create a file named @file{$HOME/.ne/.keys}.

The format of the file is very simple: each line starting with the @samp{KEY}
sequence of capital characters is considered the description of a key binding.
All other lines are considered commments. The format of a key binding
description is

@example
KEY @var{hexcode} @var{command}
@end example

The @var{hexcode} value is the @sc{ascii} code of the keystroke. For special
keys such as @key{Insert} or function keys, you should take a look at
@code{ne}'s source file @file{keycodes.h}, which contains the codes for all
@code{terminfo}'s key capabilities. You can write just the hex
digits, nothing else is necessary (but a prefixing @samp{0x} is tolerated).
For instance,

@example
KEY 1 MOVESOL
@end example

@noindent binds to @kbd{@key{Control}-A} the action of moving to the start
of a line, while

@example
KEY 101 LINEUP
@end example

@noindent binds to the ``cursor-up'' key the action of moving the cursor
one line up.

The file @file{default.keys} which comes with @code{ne}'s distribution
contains a complete, commented definition of @code{ne}'s standard bindings.
You can modify this file with a trial-and-error approach. Remember the
existence of the @samp{--noconfig} argument (@pxref{Arguments}) if you
need to skip the parse of a broken key binding file.

@var{command} can be any @code{ne} command, including @code{Escape}
(which allows the reconfigure the menu activator) and @code{Macro}, which
allows to bind complex sequences of actions to a single keystroke. The binding
of a macro is very fast because on the first call the macro is cached in memory.
@xref{Macro}.

Note that you cannot @emph{ever} redefine @key{Return} and @key{Escape}. This
is a basic issue---however brain damaged is the current configuration, you will
always be able to exploit fully the menus and the command line.

The key binding file is parsed at startup. If something does not work,
@code{ne} exits displaying an error message. If you want to skip this phase
(for instance, in order to correct the broken file), just give @code{ne} the
@code{--noconfig} argument. @xref{Arguments}.

@node Changing Menus
@section Changing Menus
@cindex Configuring the menus

When @code{ne} is started, it looks at the file @file{$HOME/.ne/.menus};
if it exists, it is considered a menu configuration file.

Each line of a menu configuration file not starting with the @samp{MENU} or
@samp{ITEM} keywords is considered a comment. You should describe the menus
as in the following example:

@example
MENU "Project"
ITEM "Open...     ^O" Open
ITEM "Close         " Close
ITEM "DoIt          " Macro DoIt
@end example

Any number of menu can be accomodated, but you should consider that many
terminals are 80 column wide. There is a minor restriction on the
items---their width has to be constant throughout each menu. Note that the
text of an item, as the name of a menu, is between quotes. Whatever follows
the last quote is considered the command associated to the menu.

@noindent @strong{Warning:} the description of key bindings in menus
(@samp{^O} in the previous example) is very important for the beginner;
there is no relation inside @code{ne} about what you say in the menu and how
you configure the key bindings (@pxref{Key Bindings}). Please do not say
thing in the menus which are not true in the key binding file.

The menu configuration file is parsed at startup. If something does not
work, @code{ne} exits displaying an error message. If you want to skip this
phase (for instance, in order to correct the broken file), just give
@code{ne} the @code{--noconfig} argument. @xref{Arguments}.


@node Hints and Tricks
@chapter Hints and Tricks
@cindex Escape usage
@cindex Escape usage
@cindex Turbo adjustment
@cindex Shortcuts not working

@table @emph

@item Use @key{f1}, not @key{Escape}.
Due to the limitations of the techniques used when communicating with a terminal,
it is not possible to ``decide'' that the user pressed the @key{Escape} key before
about a second from the actual key press. This means that you will experiment
annoying delays when using menus. If you have no @key{f1} key, redefine a
keystroke assigning the command @code{Escape}, and you will be able to
use that keystroke instead of @key{Escape}.

@item Use turbo mode for lengthy operations.
Turbo mode (@pxref{Turbo}) allows to perform very complex operation without
updating the screen up to the end. This can be a major plus if you are editing
very long files, or if your terminal is slow. If the default value (twice the
number of lines of the screen) does not give you the best results, experiment
other values.

@item Regular expressions are powerful, and slow.
Regular expressions must be studied very carefully. If you spend a lot
of time doing editing, it is definitely reasonable to study even their most
esoteric features. Very complex editing actions can be performed by a single
find/replace using the @code{\@var{n}} convention. But remember always that
regular expressions are much slower than a normal search.

@item Use the right movement commands in a macro.
Many boring, repetitive editing actions can be performed in a breeze
by recording them the first time. Remember, however, that while recording
a complex macro you should always use a cursor movement that will apply
in a different context. For instance, if you are copying a word, you cannot
move with cursor keys, because that word at another application of the
macro could be of a different length. Rather, use the next/previous word
keys and the @code{MoveEOW} command, which guarantee a correct behaviour in
all situations.

@item Some preferences can be preserved even with automatic preferences.
When you save an autoprefs file, the file contains simply a macro which,
when executed, produces the current configuration. However, you could want,
for instance, to never change the insert/overwrite state. In this case, just
edit with @code{ne} the autoprefs files and delete the line containing the
command setting the insert flag. When the autoprefs will be loaded, the
insert flag will be left untouched. This trick is particularly useful with
the @code{StatusBar} and @code{FastGUI} commands.

@item If some keystrokes do not work, check for system-specific features.
Sometimes it can happen that a keystroke does not work---for instance,
@kbd{@key{Control}-O} does not open a file. This usually is due to the kernel
tracking that key for its purposes. For instance, along a @code{telnet}
connection with xon/xoff flow control, @kbd{@key{Control}-S} and
@kbd{@key{Control}-Q} would block and release the output
instead of saving and quitting.

In these cases, if you do not need the system
feature you should check how to disable it: for instance, some @sc{bsd}-like
systems feature a delayed suspend signal which is not in the @sc{posix}
standard, and thus cannot be disabled by @code{ne}. On @sc{hp-ux}, the command
@samp{stty dsusp ^-} would disable the signal, and would let the control
sequence previously assigned to it to run up to @code{ne}.

Another example is the @code{NCSA Telnet} software for the Macintrash. Unless
you modify your setting in such a way to disable @kbd{@key{Control}-S} and
@kbd{@key{Control}-Q} as flow controllers, you will not be able to use them
as keystrokes (even if @code{ne} is doing all it can in order to explain to
the software that it does @emph{not} need xon/xoff flow control@dots{}).

@end table

@node Motivations and Design
@chapter Motivations and Design
@cindex Mode
@cindex curses
@cindex POSIX
@cindex terminfo
@cindex Magic cookie terminals
@cindex Resource usage
@cindex Interrupt character

In this chapter I will try to outline the rationale behind @code{ne}'s
design choices. Moreover, some present, volutary limitations of the current
implementation will be described. The intended audience of such a
description is the programmer wanting to hack up @code{ne}'s sources, or the
informed user wanting to deepen its knowledge of the limitations.

@code{ne} has no concept of @emph{mode}. All shortcuts are defined by a
single key, possibly with a modifier (such as @key{Control} or @key{Meta}).
Modality is in my opinion a Bad Thing unless it has a very clear visual
feedback. As an example, menus are a form of modality. After entering the
menus, the alphabetic keys and the navigation keys have a different meaning.
But the modality is clearly reflected by a change in the graphical user
interface. The same can be said about the input line, because it is always
preceeded by a prompt ending with a colon (and possibly highlighted).

@code{ne} has no sophisticated visual updating system similar, for instance,
to the one of @code{curses}. All updating is done while manipulating the
text, and only if the turbo flag is set some iterated operations can delay
the update (in this case, @code{ne} keeps track in a very rough way
of the part of the screen which changed). Moreover, the output is not
preempted by additional input coming in, so that along a slow connection the
output could not keep up with the input. However, along fast connections,
the responsivity of the editor is greatly enhanced by the direct update.
Moreover, a great deal of memory and computational power is gained, because
it is not necessary to keep constantly updated two copies of the screen, and
to compare them whenever doing an update. As it is typical in @code{ne},
when such design tradeoffs arise preference is given to the solution which
is effective on a good part of the existing hardware, and will be very
effective on most future hardware.

@code{ne} uses a particular scheme for handling the text. There is a doubly
linked list of line descriptors which contain pointers to each line of text.
The lines themselves are kept in a list of pools, which is expanded and
reduced dynamically. The interesting thing is that for each pool @code{ne}
keeps track just of the first and of the last character used. A character is
free iff it containes a null, so there is no need for a list of free chunks.
The point is that the free characters laying between that first and the last
used characters (the @dfn{lost} characters) can only be allocated
@emph{locally}: whenever a line has to grow in length, @code{ne} first
checks if there are enough free characters around it. Otherwise, it remaps
the line elsewhere. Since editing is essentially a local activity, the
number of such lost characters remains very low. And the manipulation of a
line is extremely fast and independent of the size of the file, which can be
very huge. A mathematical analysis of the space/time tradeoff is rather
difficult, but empirical evidence suggests that the idea works.

@code{ne} takes the @sc{posix} standard as the basis for @sc{un*x}
compatibility. The fact that this standard has been designed by a worldwide
recognized and impartial organization such as @sc{ieee} makes it in my
opinion the most interesting effort in his league. No attempt is made of
supporting ten thousands different versions and releases by using
conditional compilation. Very few assumptions are made about the behaviour
of the system calls. This has obvious advantages in terms of code testing,
maintenance, and reliability. For the same reasons, the availability of an
@sc{ansi} C compiler is assumed.

There is however an exception to this assumption, which is the need for the
presence of a @code{terminfo} database, and for (part of) the relative functions
(which are usually contained in the library @file{libcurses.a}). The need for
a terminal capability database is clear, and the choice of @code{terminfo}
(with respect to @code{termcap}) is compulsory if you want to support a series
of features (such as more than ten function keys) which @code{termcap} lacks.
Some details about this can be found in @ref{Portability Problems}.

@code{ne} does not allow to redefine the @key{Escape} and @key{Return} keys,
and the interrupt character @kbd{@key{Control}-\}. This decision has been taken
mainly for two reasons. First of all, it is necessary to keep a user from
transforming @code{ne}'s bindings to such a point that another unaware user
cannot work with it. These two keys and the alphabetic keys allow to activate
any command without any further knowledge of the key bindings, so it seems to
me this is a good choice. As a second point, the @key{Escape} key usage should
generally be avoided. The reason is that most escape sequences that are
produced by special keys start exactly with the escape character. When
@key{Escape} is pressed, @code{ne} has to wait for one second, just to be sure
that it did not receive the first character of an escape sequence. This makes
the response of the key very slow, unless it is immediately followed by another
key such as @samp{:}.

Note that it was stated several times that the key bindings work also when
doing a long input, navigating through the menus or browsing the requester.
This is only partially true. In order to keep down the code size and
complexity, in these cases @code{ne} recognizes only direct bindings to
commands, and discards the arguments. Thus, for instance, if a key is bound
to the command line @samp{LineUp 2}, it will act like @samp{LineUp}, while a
binding to @samp{Macro MoveItUp} would produce no result. Of course full
binding capability is available while writing text. This limitations will
probably be lifted in a future version: presently they do not seem to
cripple seriously the configurability of @code{ne}.

@code{ne} has some restriction in its terminal handling. It does not support
highlighting on terminals which use a magic cookie. Supporting correctly such
terminals is a royal pain, and I did not have any means of testing the code
anyway. Moreover, they are rather obsolete. Another lack of support is for
the capability strings which specify a file to print or a program to launch
in order to initialize the terminal.

@code{ne} has been written with sparing resource usage as a basic goal.
Every possible effort has been made in order to reduce the use of @sc{cpu}
time and memory, and the number of system calls. For instance, command
parsing is done through hash techniques, and the escape sequence analysis
uses the order structure of strings for minimizing the number of
comparisons. The optimal cursor motion functions were directly copied from
@code{emacs}. No busy polling is allowed. Doubly headed, doubly linked lists
allows for very fast list operations without any special case whatsoever.
The search algorithm is a version of the Boyer-Moore algorithm which
provides high performance with a minimal setup time. An effort has been
taken to move to the text segment all data which do not change during the
program execution.

A word should be spent about lists. Clearly, handling the text as a single
block with an insertion gap (a la @code{emacs}) allows you to gain some
memory, since you do not have to allocate the list nodes, which require
usually 16 bytes per line. However, the management of the text as a linked
list requires much less @sc{cpu} time, and the tradeoff seems to be
particularly favorable on virtual memory systems, where moving the insertion
gap can require a lot of accesses to different pages.

Just to give a pratical example, on the @sc{hp-ux} systems where @code{ne}
was developed @code{vi} requires more memory than @code{ne}, unless the size
of the file to edit is rather big, in which case @code{ne} requires a data
segment about 20% bigger. (Of course, this does not take into account some
sophisticated features of @code{ne}, such as unlimited undo/redo, which can
cause a major memory consumption.)

@node Portability Problems
@chapter Portability Problems
@cindex Portability
@cindex POSIX
@cindex terminfo
@cindex Printable characters

This chapter is devoted to the description of the (hopefully very few) problems
that could arise when porting @code{ne} to another version of @sc{un*x}.

@ignore

Compability within the Amiga family of computers is complete, so there are no
problems in recompiling @code{ne} for a different processor or architecture in
this case.

@end ignore

The fact that only @sc{posix} calls have been used (@pxref{Motivations and
Design}) should guarantee that on @sc{posix}-compliant systems endowed with a
@code{terminfo} database and library a recompilation should suffice.
Unfortunately, @code{terminfo} has not been standardized by @sc{ieee}, so that
different calls could be available. The necessary calls are
@code{setupterm()}, @code{fixterm()}, @code{resetterm()}, @code{tparm()} and
@code{tputs()}. The other @code{terminfo} functions are never used. Note that
on @code{termcap}-only machines, it will be necessary to write an emulation
module that will map @code{terminfo} calls on @code{termcap} calls. This is the
only feasible solution---the other way around would artificially cripple basic
features of @code{terminfo} which are used in @code{ne}.

There are, however, some details which are not specified by @sc{posix}, or are
specified with insufficient precision. The places of the source where such
details come to the light are evidenced by the @samp{PORTABILITY PROBLEM}
string, which is followed by a complete explanation of problem. I will mention
here some examples.

@code{ne} uses the @code{alarm()} system function in order to get out of a
@code{getchar()} call when more than one second elapsed, and a partial match
with a key capability in the terminal database is in progress (this is, for
instance, the case whenever you hit the @key{Escape} key and there is one key
capability starting with the escape character). The problem lies in the fact
that the passing @var{n} as argument of @code{alarm()} can produce a signal
after @var{n} @emph{or} @var{n}-1 seconds---both possibilities are accepted by
@sc{posix}. On the machines where @code{ne} was developed, the first case
happens. But on machines which wait for @var{n}-1 seconds, the @code{alarm(1)}
call will produce immediately a signal: it has to be changed to @code{alarm(2)}
(using this version in the first case would produce an intolerably bad
responsiveness of the program when you hit the @key{Escape} key).

Another relevant issue is how to print extended @sc{ascii} characters (i.e.,
characters whose code is smaller than 32 or greater than 126). On many system,
these characters have to be filtered and replaced with something printable: the
default behaviour is to add 64 to all characters under 32 (so that control
characters will translate to the respective letter) and to visualize all
characters after 126 as a question mark. If your system has a more powerful
display, you may want to change the @code{DECONTROL()} macro which takes a
character variable as an argument, and transforms it into a printable character.

Note that it is perfectly possible that some system features not standardized
by @sc{posix} interfere with @code{ne}'s usage of the I/O stream. Such problems
should be attached locally, by using the system facilities, rather than by
@code{#ifdef}'ing horribly the source code. An example is given in @ref{Hints
and Tricks}.



@node Acknowledgments
@chapter Acknowledgments

A lot of people contributed to this project. Part of the code comes from the
@code{emacs} sources. Many people, in particular at the silab (the Milan
University Computer Science Department Laboratory), helped in beta testing.

In particular, I would like to cite Roberto Attias, Ivan Buttinoni, Alfredo
Chizzoni, Fabrizio Lodi, Antonio Piccolboni, Marco Pugliese, Marco Rodolfi,
Sergio Ruocco, Carlo Santagostino, Markus Senoner, Paolo Silvera and
Reinhard Spisser.

@ignore

Simon Raybould provided the @code{terminfo} libraries for the Amiga.

@end ignore

Comments, complaints, desiderata are welcome.

@example
    Sebastiano Vigna
    Via California 22
    I-20144 Milano MI

    BIX: svigna@@bix.com
    INTERNET: vigna@@ghost.dsi.unimi.it
    UUCP:seba@@sebamiga.adsp.sub.org
@end example
@page

@page
@node Command Index
@unnumbered Command Index
@printindex co

@page
@node Concept Index
@unnumbered Concept Index
@printindex cp

@contents
@bye
