[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 2. Basics

Simple things should be simple. Complex things should be possible. (Alan Kay)

`ne`'s user interface is essentially a compromise between the limits of character driven terminals and the power of GUIs. While real editing is done without ever touching a mouse, it is also true that editing should be doable without ever touching a manual. These two conflicting goals can be accomodated easily in a single program if we can offer a series of interfaces that allow for differentiated use.

In other words, it is unlikely that an `ne` wizard will ever have to activate a menu, but 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 esoteric features, but few users will ever need to change `ne`'s menus or key bindings.

Another important thing is that powerful features should always be accessible, at least in part, to every user. The average user should be able to record his actions, replay them, and save them in a humanly readable format for further use and editing.

In the following sections we shall take a quick tour of `ne`'s features.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.1 Terminology

In this section we explain and contrast some of the terms `ne` uses. Understanding these distinctions will go a long way towards making the rest of this manual make sense.

A file is a group of bytes stored on disk. This may seem rather obvious, but the important distinction here is that `ne` does not edit files; it edits documents.

A document is what `ne` calls one of the "text thingies" that you can edit. It is a sequence of lines of text in the computer's memory--not on disk. Documents can be created, edited, saved in files, loaded from files, discarded, et cetera. When a document is loaded from or saved to a file, it remains associated with that file by name until the document is either closed or saved to a different file. Interactions between documents and files are handled by the commands under the `File` menu. The `Documents` menu commands only deal with documents. See section Menus.

Internally, `ne` holds its documents in buffers. A buffer is a chunk of memory in which `ne` holds something. For example, each document is held in its own buffer, as are any loaded or recorded macros, undo records, a copy of your last deleted line of text, a copy of all your previous responses to long input, and several other things.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.2 Starting

To start `ne`, just type `ne` and press `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 UN*X command. The screen of your terminal will be cleared (or filled with text loaded from the first file you specified).

At the bottom of the screen, you will see a line containing some numbers and letters. This is called the status bar because it reports to you part of the internal state of the editor.

Writing text is pretty straightforward: if your 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 `Delete` and `Backspace` key to perform corrections. If your keyboard has an `Insert` key, you can use it to toggle (switch from on to off, or vice versa) insert mode. In general, `ne` tries to squeeze everything it can from your keyboard. Functions keys and special movement keys should work flawlessly if your terminal is properly configured. If not, complain to your system administrator.

At startup, the status bar has the following form:

     L:       1 C:       1  12% ia----pvu-------@A <unnamed>

(the numbers could be different, and a file name could be shown as last item instead of `'<unnamed>'`). You probably already guessed that the numbers after `'L:'` and `'C:'` are the line and column numbers, respectively, whereas the percentage indicates approximately your position in the file. The small letters represent user flags that you can turn on and off. In particular, `'i'` tells you that insert mode is on, while `'p'` tells that the automatic preferences system is activated. For a thorough explanation of the meaning of the flags on the status line, see The Status Bar.

Once you are accustomed to cursor movement and line editing, it is time to press `f1` (the first function key), or in case your keyboard does not have such a key, `Escape`. Immediately, the menu bar will appear, and the first menu will be drawn (if you find yourself waiting for the menu to appear, you can press `Escape` twice in a row). 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 `ne`. If you want to save your work, you should use the `'Save As...'` item from the `'File'` menu. Menus are fully discussed in Menus. When you want to exit from the menu system, press `f1` (or `Escape`) again. If you instead prefer to choose a command and execute it, move to the respective menu item and press `Return`.

At the end of several menu items you will find strange symbols like `^A` or `f1`. They represent 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 `'^'` in front of a character denotes the shortcut produced by the `Control` key plus that character (we assume here that you are perfectly aware of the usage of the `Control` key: it is just as if you had to type a capital letter with `Shift`). The descriptions of the form `f` n represent instead function keys. Finally, the symbol `'['` in front of a character denotes the shortcut produced by `Control` plus `Meta` (a.k.a. `Alt`) plus that character, or `Meta` plus that character, depending on your terminal emulator--you must check by yourself. Moreover, these last bindings could not work with some terminals, in which case you can replace them with a sequence: just press the `Escape` key followed by the letter. A few menu items are bound to two control sequences (just in case one does not work, or it is impractical).

Note that under certain conditions (for instance, while using `ne` through a `telnet` connection) some of the shortcuts might not work because they are trapped by the operating system for other purposes (see section Hints and Tricks).

Finally, we have the third and last interface to `ne`'s features: the command line. If you press ``Control`-K`, or `Escape` followed by `':'` (a la `vi`), you will be requested to enter a command to execute. Just press `Return` for the time being (or, if you are really interested in this topic, see section The Command Line).

In the sections that follow, when explaining how to use a command we shall usually describe the corresponding menu item. The related shortcut and command can be found on the menu item itself, and in Menus.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.3 Loading and Saving

The first thing to learn about an editor is how to exit. `ne` has a `CloseDoc` command that can be activated by pressing ``Control`-Q`, by choosing the `'Close'` item of the `'Document'` menu, or by activating the command line with ``Control`-K`, writing `'cd'` and pressing `Return`. Its effect is to close the current document without saving any modifications. (You will be requested to confirm your choice in case the current document has been modified since the last save.)

There is also a `Quit` command, which closes all the documents without saving any modifications, and an `Save&Exit` (``Meta`-X`) command, which saves the modified documents before quitting.

This choice of shortcuts could surprise you. Wouldn't `Quit` be a much better candidate for ``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 `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 may use the `Open` command, which can be activated by pressing ``Control`-O`, by choosing the `'Open...'` item of the `'File'` menu, or by typing it on the command line (as in the previous case). You will be prompted with a list of files and directories in the current working directory. (You can tell the directory names because they end with a slash; they will also appear in a bold face if your terminal allows it.) You can select any of the file names by using the cursor keys, or any other movement key. Pressing an alphabetic key will move the cursor to the first entry after the cursor that starts with the given letter. When the cursor is positioned over the file you want to open, press `Return`, and the file will be opened. If instead you move to a directory name, pressing `Return` will display the contents of that directory.

You can also escape with `f1`, `Escape` or `Escape`-`Escape` and manually type the file name on the command line (or escape again, and abort the `Open` operation). If you escape with `Tab` instead, the file or directory under the cursor will be copied in the input line, where you can modify it manually. `ne` has also file name completion features activated by `Tab` (see section The Input Line).

When you want to save a file, just use the command `Save` (``Control`-S`). It will use the current document name or will ask you for one if the current document has no name. `SaveAs`, on the other hand, will always ask for a new name before saving the file.

If `ne` is interrupted by an external signal (for instance, if your terminal crashes), it will try to save your work in some emergency files. These files will have names similar to your current files, but they will have a pound sign `#` prepended to their names. See section Emergency Save.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.4 Editing

An editor is presumably used for editing text. If you decide not to edit text, you probably don't want to use `ne`, because that's all it does--it edits text. It does not play `Tetris`. It does not evaluate recursive functions. It does not solve your love problems. It just allows you to edit text.

The design of `ne` makes editing extremely natural and straightforward. There is nothing special you have to do to start editing once you've started `ne`. Just start typing, and the text you type shows up in your document.

`ne` provides two ways of deleting characters, the `Backspace` (or ``Control`-H`, if you have no such key) and the `Delete` key. In the former case you delete the character to the left of the cursor, while in the latter case you delete the character just under the cursor. This is in contrast with many UN*X editors, which for unknown reasons decide to limit your ways of destroying things--something notoriously much funnier than creating. (See DeleteChar and Backspace.)

If you want to delete a line, you can use the `DeleteLine` command, or ``Control`-Y`. A very nice feature of `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 `UndelLine` command or ``Control`-U`. (See DeleteLine and 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 `Mark` command, activated by choosing the `'Mark Block'` item of the `'Edit'` menu, or by pressing ``Control`-B` (think "block"). This command toggles the mark (puts it in the current cursor position or removes it from wherever it is). Whenever the mark is set, the zone between the mark and the cursor can be cut, copied or erased. Note that by using ``Control`-@` you can set a vertical mark instead, which allows you to mark rectangles of text. Whenever a mark has been set, either an `'M'` appears on the command line or a `'V'` appears if the mark is vertical. If you forget where the mark is currently, you can use the `'Goto Mark'` menu item of the `'Search'` menu to move the cursor to it.

When you cut or copy a block, you can save it with the `'Save Clip...'` menu item of the `'Edit'` menu. You can also load a file into a clip with `'Open Clip...'`, and paste it anywhere. All such operations act on the current clip, which is by default the clip 0. You can change the current clip number with the `ClipNumber` command. See section ClipNumber.

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

Another interesting feature of `ne` is it's ability to load an unlimited number of documents. If you activate the `NewDoc` command (using the `'Document'` menu or the command line), a new, empty document will be created. You can switch between the existing documents in memory with `f2` and `f3`, which are bound to the `PrevDoc` and `NextDoc` commands. If you have a lot of documents, the `'Select...'` menu item (`f4`) prompts you with the list of names of currently loaded documents and allows you to choose directly what to edit.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.5 Basic Preferences

`ne` has a number of flags that specify alternative behaviours, the most prototypical example being the insert flag, which specifies whether the text you type is inserted into the existing text or overwrites it. You can toggle this flag with the `'Insert'` menu item of the `'Prefs'` menu, or with the `Insert` key of your keyboard. (Toggle means to change the value of a flag from true to false, or from false to true; see section Insert.)

Another important flag is the free form flag, which specifies whether the cursor can be moved beyond the right end of each line of text or only to existing text (a la `vi`). Programmers usually prefer non free form editing; text writers seem to prefer free form. See FreeForm for some elaboration. The free form flag can be set with the `'Free Form'` menu item of the `'Prefs'` menu.

At this point, we suggest you explore by trial and error the other flags of the `Prefs` menu, or try the `Flags` command (see section Flags), which explains all the flags and the commands that operate on them. We prefer spending a few words discussing automatic preferences or autoprefs.

Having many flags ensures a high degree of flexibility, but it can turn editing into a nightmare if you have to turn on and off dozens of flags for each different kind of file you edit. `ne`'s solution is to automatically set a document's flags when a file is loaded based on your stated preferences for each file type. A file's type is determined by the extension of its file name, that is, the last group of letters after the last dot. For instance, the extension of `'ne.texinfo'` is `'texinfo'`, the extension of `'source.c'` is `'c'`, and the extension of `'my.txt'` is `'txt'`.

Whenever you select the `'Save AutoPrefs'` menu item, `ne` saves the flags of your current document to be used when you load other files with the same extension as your current document. These autoprefs are saved in a file in your `'~/.ne'` directory. This file has the same name as the extension of the current document with `'#ap'` appended to it. It contains all the commands necessary to recreate your current document's flag settings. Whenever you open a file with this file name extension, `ne` will automagically recreate your prefered flag settings for that file type. (There is a flag that inhibits the process; see section AutoPrefs.)

Finally, when you select the `'Save Def Prefs'` menu item, a special preferences file named `'.default#ap'` is saved. These preferences are loaded whenever `ne` is run before loading any file. This is how you set up 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, it can be edited manually if necessary.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.6 Basic Macros

Very often, the programmer or the text writer has to repeat some complex editing action over a series of similar blocks of text. This is where macros come in.

A macro is a stored sequence of commands. Any sequence of commands you find yourself repeating is an excellent candidate for being made into a macro. You could create a macro by editing a document that only contains valid `ne` commands and saving it, but by far the easiest way to create a macro is to have `ne` record your actions. `ne` allows you to record macros and then play them (execute the commands they contain) many times. You can save them on disk for future use, edit them, or bind them to any key. You could even reconfigure each key of your keyboard to play a complex macro if you wanted to.

`ne` can have any number of named macros loaded at the same time. It can also have one unnamed macro in its current macro buffer. The named macros are typically loaded from disk files, while the current macro buffer is where your recorded macro is held before you save it or record over it.

Recording a macro is very simple. The keystroke ``Control`-T` starts and stops recording a macro. When you start recording a macro, `ne` clears the current macro buffer and starts recording all your actions (with a few exceptions). You can see that you are recording a macro if an `'R'` appears on the status bar. When you stop the recording process (again using ``Control`-T`), you can play the macro with the `'Play Once'` item of the `'Macros'` menu or with the `f9` key. If you want to repeat the action many times, the `Play` command allows you to specify a number of times to repeat the macro. You can always interrupt the macro's execution with ``Control`-\`.

A recorded macro has no name. It's just an anonymous sequence of commands in the current macro buffer, and it will go away when you exit `ne` or record another macro. If you want to save your recorded macro for future use, you can give it a name and save it with the `'Save Macro...'` menu item or the `SaveMacro` command. The macro is saved as a file in your current directory by default or whatever directory you specify when prompted for the macro's name. If you save it in your `'~/.ne'` directory then it will be easy to access it later from any other directory. The `'Open Macro...'` menu item and the `OpenMacro` command load a macro from a file into the current macro buffer just as if you just `Record`ed it.

Any macro can be loaded from a file and played with the `'Play Macro...'` menu item or the `Macro` command. (This won't modify any recorded anonymous macro that may be in the current macro buffer; `OpenMacro` does that.) Useful macros can be permanently bound to a keystroke as explained in Key Bindings. Moreover, whenever a command line does not specify one of `ne`'s builtin commands, it is assumed to specify the name of a macro to execute. Thus, you can execute macros just by typing their file names. Include a path if the macro file's directory is different from your current directory or your `'~/.ne'` directory.

If the first attempt to open a macro fails, `ne` checks for a macro with the given name in your `'~/.ne'` directory. This allows you to program simple extensions to `ne`'s language. For instance, all automatic preferences macros--which are just specially named macros that contain only commands to set preferences flags--can be executed just by typing their names. For example, if you have an automatic preference for the `'doc'` extension for example, you can set `ne`'s flags exactly as if you loaded a file ending with `'.doc'` by typing the command `doc#ap`.

In general, it is a good idea to save frequently used macros in `'~/.ne'` so that you can invoke them by name without specifying a path regardless of your current directory. On the other hand, if you have a macro that is customized for one document or a set of documents that you store in one directory, then you might want to save the macro in that directory as well. If you do, then you would want to `cd` to that directory before you start `ne` so that you can access that macro without specifying a path.

If your macro has the same name as one of `ne`'s builtin commands, you can only access it with the `Macro name` command. Builtin command names are always found first before `ne` command interpreter looks for macros.

The system administrator may make some macros available from a global directory (`'/usr/local/lib/ne'` by default). You can change where `ne` looks for this global directory by setting and exporting the environment variable `NE_GLOBAL_DIR` before running `ne`.

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. Subsequent invocations of the macro will used the cached version.

Warning: the macro names are not case sensitive or path sensitive. `ne` only caches the file name of a macro, not the path name, and uses a case insensitive comparison. That is, if you invoke `'~/foobar/macro'`, a subsequent call for `'/usr/MACRO'` will use the cached version of `'~/foobar/macro'`. You can clear the cache by using the `UnloadMacros` command. See section UnloadMacros.

The behaviour of macros may vary with different preferences. If the user changes the AutoIndent and WordWrap flags, for example, new lines and new text may not appear in the same way they would have when a macro was recorded. Good general purpose macros avoid such problems by using the `PushPrefs` command first. This preserves the user's preferences. Then they set any preferences that could affect their behaviour. Once that is taken care of they get on with the actual work for which they were intended. Finally, they use the `PopPrefs` command to restore the user's preferences. Note that if a macro is stopped before it restores the preferences (either by the user pressing ``Control`-\` or by a command failing) then that responsibility falls on the user.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 2.7 More Advanced Features

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.1 UTF-8 support

UTF-8 is a character encoding that can represent the whole ISO 10646 character set--two billion characters! `ne` can load and manipulate UTF-8 files transparently, in particular on systems that provide UTF-8 I/O. See section UTF-8 Support.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.2 Bookmarks

It often happens that you have to browse through a file, switching frequently between a small number of positions. In this case, you can use bookmarks. There are up to ten bookmarks per document, each designated by a single digit, with the default being `'0'`. You can set them with the `SetBookmark` command, and you can return to any set bookmark with the `GotoBookmark` command. Also, `ne` sets an automatic bookmark (designated by `'-'`) to your current position in a document whenever you use the `GotoBookmark` command. You can use this automatic bookmark to return to that previous location with a `GotoBookmark -` command. Doing so will reset the automatic bookmark, so that subsequent `GotoBookmark -` commands will switch between those two locations. See section SetBookmark, GotoBookmark, and UnsetBookmark. Note that in the default configuration no key binding is assigned to these commands. If you use them frequently, you may want to change the key bindings. See section Key Bindings.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.3 MS-DOS files

`ne` will detect automagically the presence of MS-DOS line terminators (CR/LFs) and set the CR/LF flag. When the file will be saved, the terminators will be restored correctly. You can change this behaviour using the `PreserveCR` and `CRLF` commands. See section PreserveCR, and CRLF.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.4 Binary files

`ne` allows a simplified form of binary editing. If the binary flag is set, only NULLs are considered newlines when loading or saving. Thus, binary files can be safely loaded, modified and saved. Inserting a new line or joining two lines has the effect of inserting or deleting a NULL. Be careful not to mismatch the state of the binary flag when loading and saving the same file.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.5 File requester

The `NoFileReq` command deactivates the file requester. It is intended for "tough guys" who always remember the names of their files and can type them at the speed of light (maybe with the help of the completer, which is activated by the `Tab` key; see section The Input Line).

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.6 Executing UN*X commands

There are three ways to execute UN*X commands from within `ne`. The `System` command can run any UN*X command; you will get back into `ne` as soon as the command execution terminates. See section System. The `Through` (``Meta`-T`) command (which can be found in the `'Edit'` menu), however, is much more powerful; it cuts the current block, passes it as standard input to any UN*X command, and pastes the command's output at the current cursor position. This provides a neat way to pass a part of your document through one of UN*X's many filter commands (commands that read from standard input and write to standard output, e.g., `sort`). See section Through. Finally, you can use the `Suspend` (``Control`-Z`) command to temporarily stop `ne` and return to your command shell. See section Suspend.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 2.7.7 Advanced key bindings

For an exaustive list of the remaining features of `ne`, see Reference.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Sebastiano Vigna on February, 7 2009 using texi2html 1.76.