     [file version.texinfo not included]

This file documents ne VERSION, a free text editor for UN*X.

Copyright (C) 1993-1998 Sebastiano Vigna. Copyright (C) 1999-RELEASE_YEAR Todd M. Lewis and 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.

This file describes ne version VERSION, a free text editor that runs (we hope) on almost any UN*X machine. ne is easy to use for the beginner, but powerful and fully configurable for the wizard, and most sparing in its resource use.

Copyright (C) 1993-1998 Sebastiano Vigna

Copyright (C) 1999-RELEASE_YEAR Todd M. Lewis and Sebastiano Vigna

Introduction
************

ne is a full screen text editor for UN*X (or, more precisely, for POSIX: see Motivations and Design). I came to the decision to write such an editor after getting completely sick of 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 LITHP (This otherwise unremarkable language is distinguished by the absence of an s in its character set; users must substitute th.  LITHP is said to be useful in protheththing lithtth.) operating system just to do some editing.

A concise overview of the main features follows:

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

  * syntax highlighting;

  * full support for UTF-8 files, including multiple-column characters;

  * 64-bit file/line length;

  * simple scripting language where scripts can be generated via an idiotproof record/play method;

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

  * automatic preferences system based on the extension of the file name being edited or regex content matching;

  * automatic completion of prefixes using words in your documents as dictionary;

  * a file requester with completion features for easy file retrieval;

  * extended regular expression search and replace à la emacs and vi;

  * a very compact memory model---you can easily load and modify very large files, even if they do not fit your core memory;

  * editing of binary files.

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 accommodated 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.

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. (Actually, it can be in a region of the disk used to simulate a larger memory. ne will switch to such a simulation whenever the computer's memory is not sufficient for editing a file. This means, in particular, that out-of-memory errors can be caused by insufficient disk space, too.) 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 Menus.

Internally, ne holds its documents' text in buffers.  A buffer is a chunk of memory in which ne holds text. In addition to each document's text, buffers hold any loaded or recorded macros, undo records, a copy of your last deleted line, a copy of all your previous responses to long input, and several other things.

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). You can also pipe the result of a command directly into ne: it will be loaded and opened as the first document. See Arguments for other command line options.

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. Function keys and special movement keys should work flawlessly if your terminal is properly configured. If not, complain to your system administrator. If that doesn't help, see Key Bindings.

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. At startup, the status bar has the following form:

      L:       1 C:       1  12% ia----pvu-t------@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 your cursor's 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. The * means this document has not been saved. For a thorough explanation of the meaning of the flags on the status bar, 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 next item in the current menu whose name starts with that letter, and an upper case alphabetic key will move to the next 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 instead you 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 fN 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 for yourself. Moreover, these last bindings may 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 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 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.

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 a 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 to the input line, where you can modify it manually. ne also has file name completion features activated by Tab (see 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. SaveAll will save all modified documents. If the file you are saving a document to has changed since you last loaded or saved it, perhaps because another user updated it while you were editing, ne will warn you before overwriting 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 # prefixed to their names. See Emergency Save.

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 key (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, shift 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 sets the mark at the current cursor position. Whenever the mark is set, the text 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.

The block of text you cut or copy is saved in a clip, which you can Paste somewhere else in your document, or save it to a file with the Save Clip... menu item of the Edit menu. You can also load a file directly 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 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 its 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 your documents 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 which to edit. In that list, names of documents with unsaved changes will be bold. You can also change their relative order in that list with the f2 and f3 keys.

Basic Preferences
=================

ne has a number of flags that specify alternative behaviors, the most prototypical example being the insert flag, which specifies whether the text you type is inserted into the existing text or replaces 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 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 Flags), which explains all the flags and the commands that operate on them. We prefer spending a few words discussing automatic preferences or autoprefs, and default preferences or defprefs.

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 load your default preferences whenever ne is run before loading any file, then additionally set your stated preferences automatically for each file type as files are loaded. 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.

Thus, when you select the Save Def Prefs menu item or use the SaveDefPrefs command, a special preferences file named .default#ap is saved. In addition to other preferences, this file also includes a small set of preferences which are global to ne rather than specific to particular document types. These preferences are: FastGUI, RequestOrder, StatusBar and VerboseMacros; see FastGUI, see RequestOrder, see StatusBar, and see VerboseMacros. These extra preferences are not saved by the SaveAutoPrefs command.

By contrast, 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. 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 preferred flag settings for that file type. (There is a flag that inhibits the process; see AutoPrefs.)

Similar to preference flags, the current syntax definition is specific to the current document type, so it also is saved in autoprefs files by the SaveAutoPrefs command or Save AutoPrefs menu; it is not saved in the .default#ap file.

Note that a preferences file---whether .default#ap or an AutoPrefs file--- is just a macro (as described in the following section). Thus, it can be edited manually if necessary.

Some files have no extension, but the file type can be discerned by simple examination. Consider for example a file named example which contains XML. You may reasonably expect it to be treated as an .xml file rather than a generic file. For the purposes of applying automatic preferences and syntax definitions, ne provides a mechanism for overriding a wrong or missing extension with a virtual extension based on a document's contents. You do this by creating a ~/.ne/.extensions file which is fully described in the Virtual Extensions section.

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 recorded macros as files 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. In addition, each document has one unnamed macro in its current macro buffer. Named macros are loaded from---and get the name of---files, while each document's unnamed current macro buffer is where your recorded macro is held before you save it, play 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 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 recording (again using Control-T), ne throws away the current document's current macro and replaces it with the one you just finished recording. You can then 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-\.

These commands are omitted from recorded macros:

        Escape       Help         Play
        Exec         KeyCode      Quit
        Flags        Macro        Record

A recorded macro has no name. It's just an anonymous sequence of commands associated with your current document. It will go away when you record another macro, close the document, or exit ne. If you want to save your recorded macro for future use, you can give it a name by saving it with the Save Macro... menu item or the SaveMacro command. The macro is saved as a regular text 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 document's macro buffer just as if you had just Recorded it.

The current setting of your VerboseMacros flag determines whether long or abbreviated command names are used when saving a macro. For your convenience, SaveMacro will also convert consecutive InsertChar commands into single---usually much more readable--- InsertString commands, but only if all the inserted characters are simple printable characters, and only if the macro contains no Undo commands or macro invocations later in the macro.

Any macro can be loaded from a file and played with the Play Macro... menu item or the Macro command. (This won't modify the 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's first non-blank character is an ASCII letter but does not specify one of ne's built in commands, it is assumed to specify the name of a macro to execute. Thus, you can execute macros just by typing their file names at the command line. If the file containing your macro is somewhere besides your current directory or your ~/.ne directory, and you have not already loaded it, then use the Macro command on the command line followed by the path to the macro. That's only necessary the first time you use such a macro. From then on, you can use the macro's base name on the command line without the preceding Macro command.

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 command set. 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 txt extension, you can set ne's flags exactly as if you had loaded a file ending with .txt by typing the command txt#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 instead. 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 built-in commands, you can only access it with the Macro NAME command. Built-in command names are always searched before the ne command interpreter looks for macros.

The system administrator may make some macros available from the macros subdirectory of ne's global directory. See Arguments.

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

Warning: while path and file names are case sensitive when initially loading macros, loaded macro names are not case sensitive or path sensitive. ne only caches the file name of an already loaded macro, not the path, and it uses a case insensitive comparison when resolving command and macro names. As such, if you invoke ~/foobar/MyMacro, ne remembers it with the case-insensitive name mymacro; a subsequent call for /usr/MYMACRO will instead find and use the cached version of ~/foobar/MyMacro. You can clear all macros from the cache by using the UnloadMacros command. See 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 the way they would have when a macro was recorded. A good general purpose macro avoids such problems by using the PushPrefs command first to preserve the current preferences. The macro then sets any preferences that could affect its behaviour. Once that is taken care of it can get on with the actual work for which it were intended. Finally, it will use the PopPrefs command to restore the original preferences. Note that if a macro stops before it restores the preferences (either by the user pressing Control-\ or by a command failing) then dealing with the changed preferences falls to the user.

Any changes made to a document by a macro are recorded just as if you had entered the text and commands yourself. Therefore you can use the Undo command to roll back those changes one at a time. This can be useful especially when developing macros, but you may want to be able to undo all the changes made by a macro with a single Undo command. The AtomicUndo command makes this possible. If you add AtomicUndo + at the start of your macro and AtomicUndo - at the end, then the Undo and Redo commands will handle all changes made by your macro atomically, i.e., as if they had been made by a single command, even if your macro calls other macros which could themselves contain matching AtomicUndo + and AtomicUndo - commands. See AtomicUndo.

Leading spaces in macros are ignored, so you can indent your macros to make them more readable. Any line in a macro that starts with a non-blank, non-alphabetical character is considered a comment, so you can add comments to a macro by starting a line with #. Recorded macros sometimes have comments added to them indicating calls to other macros.

Macros can operate across multiple documents, by using the NextDoc and PrevDoc commands for example. When you stop recording, the unnamed macro is associated with the current document, replacing that document's prior unnamed macro.

You can cancel in-progress macro recording---and thus avoid wiping out a document's existing unnamed macro---with the Record 0 command, or by selecting Record Cancel from the Macro menu.

You can append additional recorded commands to your document's current macro with the Record 1 command, or by selecting Record Append from the Macro menu.

Finally, you can insert the current document's unnamed macro into your in-progress macro recording as many times as you like either by pressing the f9 key or entering the Play 1 command. Although the unnamed macro is distroyed and replaced when you stop recording your new macro, until then it's available for use like any other.

More Advanced Features
======================

UTF-8 support
-------------

ne can load and manipulate UTF-8 files transparently, in particular on systems that provide UTF-8 I/O. See UTF-8 Support.

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. Another pair of bookmarks designated by < and > mark the start and end points of the last block of text you pasted into your current document. So for example GotoBookmark > will take you to the end of the most recently pasted text. Also, ne sets an automatic bookmark (designated by -) at your current position in a document whenever you use the GotoBookmark command. You can use a GotoBookmark - command to return to the location of the previous GotoBookmark command. Doing so will reset the automatic bookmark, so that subsequent GotoBookmark - commands will switch between those two locations. The special parameters +1 and -1 indicate the next or previous set bookmark in conjunction with GotoBookmark and UnsetBookmark, but reference the next or previous unset bookmark when used with SetBookmark. A sequence of GotoBookmark +1 commands lets you easily cycle through all your set bookmarks. Finally, the special parameter ? causes SetBookmark and GotoBookmark to prompt you for a bookmark designation. This prompt includes an indication of which bookmarks are already set for the current document. See 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 Key Bindings.

Automatic Completion
--------------------

The AutoComplete command helps you extend a given prefix with matching words from your open documents.  You can specify the AutoComplete command and prefix on the command line, or you can enter the prefix directly into your document and activate the AutoComplete command. With the cursor at the right end of your prefix, activate the AutoComplete command by entering either the Escape-Tab or the Escape-I key sequence, or the Control-META-I key combination, or by selecting AutoComplete from the Extras menu.

If the prefix can be extended unambiguously, the extension will be immediately inserted into your document (this is the case, for instance, if only one word matches the prefix), and a message will tell you whether the extension is an actual word or just the longest possible extension (for instance, if you expand fo and your document contains foobar and foofoo then the partial match will be foo). Otherwise, ne presents you with a list of all matching words: choose the one you want and press Return, to select it; otherwise, press f1, Escape or Escape-Escape to cancel the completion operation.

The current state of the CaseSearch flag determines whether the prefix match is case sensitive. Any matching words which only exist in other open documents but not the current one are displayed in bold with an asterisk; think of that as a warning that if you select one of these bold words you will introduce a new word into your current document. Plain words already exist somewhere in your current document. See AutoComplete, and CaseSearch.

Automatic Bracket Matching
--------------------------

Unless you tell it not to (with the AutoMatchBracket command), ne will highlight any recognized bracket that matches the bracket your cursor is on if that matching bracket is currently visible on your screen. Recognized bracket pairs are {}, (), [], <>, and `'. See AutoMatchBracket.

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 PreserveCR, and CRLF.

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.

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 The Input Line).

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 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 Through. Finally, you can use the Suspend (Control-Z) command to temporarily stop ne and return to your command shell. See Suspend.

Advanced key bindings
---------------------

ne allows you to associate any keystroke with any command, both built-in commands (with or without parameters) and macros. These associations are referred to as key bindings, which you define in your ~/.ne/.keys file. The KeyCode command allows you to see the key code ne sees in response to any key or key combination on your keyboard. It also shows the command string currently bound to that key code. This is described in Key Bindings.

The following chapters provide an exhaustive list of the remaining features of ne. See Reference.

Reference
*********

In this chapter we shall methodically overview each part of ne. It is required reading for becoming an expert user because some commands and features are not available through menus.

Arguments
=========

The main arguments you can give to ne are the names of files you want to edit. They will be loaded into separate documents. If you specify --help or -h anywhere on the command line, a simple help text describing ne's arguments will be printed.

The +N option causes ne to advance to the Nth line of the next document loaded. This option is fairly common among editors and text display programs like vi and less. The N itself is optional. Without it, a bare + on the command line causes ne to advance to the last line of the first document. You can specify a line and column as +N,M. Any non-digit can be used to separate the N from the M. As it only affects the next document loaded, it can appear multiple times on the command line.

The --binary option causes ne to load the next document in binary mode. Binary mode treats the normal line termination characters as any other character and only breaks lines on NULL characters. Like +N,M, --binary only affects the next document loaded, and it can appear multiple times on the command line. See Binary.

The --read-only/--readonly/--ro option causes ne to load the next named file into a read-only document. You can't modify a read-only document without first taking special action such as turning off the read-only flag. You can still Save (Save) a read-only document to a file if the file's permissions allow it, but ne will prompt you before attempting to save a document marked read-only. The --read-only option only affects the next document loaded, so it can appear multiple times on the command line. A document's read-only flag is automatically set when a file is loaded if the corresponding file is not writable (as determined by the access() system call) regardless of whether the --read-only option is used. See ReadOnly.

The --no-config/--noconfig option skips the reading of the key bindings and menu configuration files (see Configuration). This is essential if you are experimenting with a new configuration and you make mistakes in it.

The --prefs EXTENSION option makes ne load a specified set of automatic preferences, that is, those associated with the provided extension, instead of the default ones, before loading the first file. It can be useful, for instance, when piping a file into ne or when reading from named pipes, as in those cases there is no file extension from which ne can guess the correct preferences. Note that preferences are cloned from the current document when a new document is created, so if you open a number of files without extension this option will propagate to all of them.

The --macro FILENAME option specifies the name of a macro that will be started just after all documents have been loaded. A typical macro would move the cursor to a certain line.

The --keys FILENAME option and the --menus FILENAME option specify a name different from the default one (.keys and .menus, respectively) for the key bindings and the menu configuration files.

For key bindings, ne loads system wide files first, then those in your ~/.ne directory, and finally those in the current directory. Key bindings loaded later may override those loaded previously. In each location, ~/.ne will first look for a file named .keys (or whatever base name you specify with the --keys option), then a file with the same name followed by a dash and the value of your TERM environment variable. This is how you can create key bindings specifically for different terminals on a single system.

Menu configuration, unlike key bindings, is not cumulative; ne looks first in your ~/.ne directory possibly followed by the system wide global directory for a menu configuration file and loads only the first one it finds, if any.

The --ansi and the --no-ansi/--noansi options manage ne's built-in ANSI sequences. Usually ne tries to retrieve from your system some information that is necessary to handle your terminal. If for some reason this is impossible, you can ask ne to use a built-in set of sequences that will work on many terminals using the --ansi option (to be true, ne can be even compiled so that it uses directly the built-in set, but you need not know this). If you want to be sure (usually for debugging purposes) that ne is not using the built-in set, you can specify --no-ansi.

The --no-syntax option disables ne's normal syntax highlighting capability. For most editing situations, this would be unnecessary, but for extremely large files it may be helpful. Syntax highlighting incurs small memory usage and processor overhead penalties for each line of text. The --no-syntax option eliminates that overhead. Note that files longer than ten million bytes will have syntax highlighting disabled by default, but it is possible to re-enable it. See Syntax Highlighting.

The --utf8 and --no-utf8 options can be used to force or inhibit UTF-8 I/O, overriding the choice imposed by the system locale. Note, however, that in general it is more advisable to set the LANG environment variable to a locale supporting UTF-8 (you can usually see the locale list with locale -a). See UTF-8 Support.

If you need to open a file whose name starts with --, you can put -- before the filename, which will skip command recognition for the next word.

You can use I/O redirection to pipe the output of other commands into your first document. For example,

       ls -l | ne file1.txt --read-only file2.txt

will open three documents: an unnamed document containing the output of the ls -l command, the contents of file1.txt, and the contents of file2.txt with the read-only flag set.

It's possible to apply the --binary, --read-only, and +N,M options to the piped unnamed document by referencing it as a single -. Only the first such file name will reference the piped document (even if it isn't the first file name on the command line). Subsequent dashes will be considered normal file names. If you want the first dash to be treated like a normal file instead of a reference to the piped document, prefix the dash with --. Consider these two command lines:

       ls -l | ne --read-only +3,8 - file1.txt -
       ls -l | ne file1.txt -- - --read-only +3,8 -
       ls -l | ne --binary file1.txt --read-only -- -

All three of these commands open ne with three documents: the output of the ls -l command will be in the first unnamed document, the contents of file1.txt will be in the second document, while the third document will contain the contents of the file - (or an empty document with that name if there is no such file). The first and second commands do exactly the same thing: the unnamed first document is marked read-only and the cursor is positioned on line 3 column 8, while the other two document are opened normally. In the case of the third command, file1.txt is opened in binary mode, the document named - is marked read-only, while the first, unnamed, document---which is not referenced on the command line---with the output from ls -l is opened normally.

Finally, ne has a global directory where the system administrator can store macros, default preferences, and syntax definitions for all users of the system. The location of this directory is defined when ne is built, but you can override it by creating and exporting the NE_GLOBAL_DIR environment variable prior to invoking ne. If you load no files when you start ne, or if you invoke the About command, it will display a splash screen. The last line on that screen shows the global directory ne is using, if it exists, or an error message otherwise.

The Status Bar
==============

The last line of the screen, the status bar, is reserved by ne for displaying some information about its internal state. Note that on most terminals it is physically impossible to write a character on the last column of the last line, so we are not stealing precious editing space.

The status bar looks more or less like this:

     L:      31  C:      25   12% iabcwfpvurt!MRPC@8*       20 /foo/bar

The numbers after L: and C: are the line and column of the cursor position. The first line and the first column are both number 1. Then, ne shows the percentage of lines before the current line (it will be 0% on the first line, and 100% on the last line).

Following that are a sequence of letters or dashes. These indicate the status of a series of flags which we shall look at later.

The hexadecimal digits following the flags give the code for the character at the cursor, and are displayed optionally (see HexCode). If your cursor is at or beyond the right end of the current line, the code disappears.

The file name appearing after the character code is the file name of the current document. The left end of very long file names may be truncated to keep the right end visible. Of course, ne is keeping track internally of the complete file name. It is used by the Save command and as the default input for the SaveAs command. See Save, and SaveAs.

The displayed line and column numbers, the percentage indicator and the character code change when the cursor moves. This fact can really slow down cursor movement if you are using ne through a slow connection. If you find this to be a problem, it is a good idea to turn off the status bar using either the Status Bar menu item of the Prefs menu or the StatusBar command. See StatusBar. Alternatively you can turn on the fast GUI mode using either the Fast GUI menu item of the Prefs menu or the FastGUI command (see FastGUI). In fast GUI mode the location of the mark is not highlighted, and status bar is not draw in reverse, so some additional optimization can be done when refreshing it.

The letters after the line and column number represent the status of the flags associated with the current document. Flags that are off display a - instead of a letter. Each flag also has an associated command. The Flags command describes them all when you don't have this manual handy. Here's the list in detail:

i
     appears if the insert flag is true. See Insert.

a
     appears if the auto indent flag is true. See AutoIndent.

b
     appears if the back search flag is true. See SearchBack.

c
     appears if the case sensitive search flag is true. See CaseSearch.

w
     appears if the word wrap flag is true. See WordWrap.

f
     appears if the free form flag is true. See FreeForm.

p
     appears if the automatic preferences flag is true. See AutoPrefs.

v
     appears if the verbose macros flag is true. See VerboseMacros.

u
     appears if the undo flag is true. See DoUndo.

r
     appears if the read only flag is true. See ReadOnly.

t or T
     appears as t if the tabs flag is true, T if the shifttabs flag is also true. See Tabs, ShiftTabs.

d
     appears if the deltabs flag is true. See DelTabs.

B or !
     appears if the binary flag is true. See Binary.

!
     appears in place of B when not in binary mode and the last line of the document is not empty (i.e. the last line of the saved file would not be terminated).

M or V
     appears if you are currently marking a block. See Mark.

V
     can appear in place of M if you are currently marking a vertical block. See MarkVert.

R
     appears if you are currently recording a macro. See Record.

P
     appears if the PreserveCR flag is true. See PreserveCR.

C
     appears if the CRLF flag is true. See CRLF.

@
     appears if UTF-8 I/O is enabled. See UTF8IO.

A/8/U
     denotes the current document encoding---US-ASCII, 8-bit or UTF-8. See UTF8.

*
     appears if the document has been modified since the last save, or if the Modified command was issued to set this flag. See Modified. This - or * may be underlined, which indicates the corresponding file's modification time has changed since the current document was loaded from or saved to that file.

Note that sometimes ne needs to communicate some message to you. The message is usually written over the status bar, where it stays until you do something. Any action such as moving the cursor or inserting a character will restore the normal status bar.

The Input Line
==============

The bottom line of the screen is usually occupied by the status bar (see The Status Bar). However, whenever ne prompts you for a command or file name or asks you to confirm some action, the bottom line becomes the input line. You can see this because a prompt is displayed at the start of the line, suggesting what kind of input is required. (Prompts always ends with a colon, so it is easy to distinguish them from error messages, which overwrite the status bar from time to time.)

ne uses the input line in two essentially different ways: immediate input and long input. You can easily distinguish between these two modes because in immediate input mode the cursor is not on the input line, while for long input mode it is.

Immediate input is used whenever ne needs you to specify a simple choice that can be expressed by one character (for example, y or n). When you type the character, ne will immediately accept and use your input. Most immediate inputs display a character just after the prompt. This character is the default response, which is used if you just press the Return key. Note that immediate input is not case sensitive. Moreover, if a yes/no choice is requested, anything other than y will be considered a negative response.

Long input is used when a whole string is required. You can enter and edit your response to long inputs like a line of text in a document. Most key bindings related to line editing work on the command line exactly as they do in a document. This is true even of custom key bindings. Just edit as you are used to. Moreover, the you can paste the first line of the current clip using the keystroke that is bound to the Paste command, usually Control-V. If your long input is longer than the screen width, the input line scrolls to accommodate your text so you can input very long lines even on small monitors. (There is a limit of 2048 characters.)

The default response to a long input is the response you gave to the previous long input. Your first action when presented with a long input will either erase the default response or allow you to edit it. If the first thing you type is a printing character, the default response will be erased. Anything else (cursor movement for example) will allow you to edit it further.

Long input also lets you access your previous long input responses with the up and down cursor commands (or with wider movement commands, such as start/end of file, page up/down, etc.). Once you find a previous input you like, you can edit it further. Long input history is not document specific, so you can recall any of your inputs regardless of which document was active when you entered it. Furthermore, ne saves the most recent long inputs in ~/.ne/.history when you end your ne session and loads them again when you begin another ne session.

Invoking the Find command, usually bound to Control-F, brings up a requester showing your prior inputs. You can close the requester with the Escape key, replace your input line with a highlighted prior entry with the Enter key, or insert that prior entry into your input line with the Tab key.

When asked to input a number, you can choose between decimal, octal and hexadecimal notation in the standard way: a number starting with 0 is considered in octal, a number starting with 0x is considered in hexadecimal, and in all other cases decimal base is assumed.

Whenever a file name is requested, you can type a partial file name and complete it with the Tab key. ne will scan the current directory (or the directory that you partially specified) and search for the files matching your partial suggestion. The longest prefix common to all such files will be copied to the input line (ne will beep if no completion exists). It's easier done than said---just try. If you press Tab again, you will be brought into the file requester: only the files and directories matching your partial specification will appear, and as usual you will be able to navigate and select a file or escape. See The Requester.  Note that ne considers the last word on the input line the partial file name to complete, no matter where the cursor is currently (you must use quotes if the name contains spaces, even if it is the only item on the input line).

Complete long input with the Return key. You can cancel a long input using f1, Escape, Escape-Escape or any key that is bound to the Escape command. The effect will vary depending on what your were requested to input, but the execution of the command requiring the input will stop.

The Command Line
================

The command line is a typical (topical) way of controlling an editor on character driven systems. It has some advantages over menus in terms of access speed, but it is not desirable from a user interface point of view. ne has a command line that should be used whenever strange features have to be accessed, or whenever you want to use a command that you are familiar with and that is not bound to any key.

You have two ways to access the command line: by activating the menu and typing a colon (:) or by typing Control-K (or any key that is bound to the Exec command; see Exec). The first method will work regardless of any key binding configuration if you activate the menus with the Escape key since that key cannot be reconfigured. Of course, there is also a menu entry that does the same job.

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

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

The Requester
=============

In various situations, ne needs to ask you to choose one string from several (where ``several'' can mean a lot). For this kind of event, the requester is issued. The requester displays the strings in as many columns as possible and lets you move with the cursor from one string to another. The strings can fill many screens, which are handled as consecutive pages. Most navigation keys work exactly as in normal editing. This is true even of custom key bindings. Thus, for instance, you can page up and down through the list with Control-P and Control-N (in the standard keyboard configuration).

A special feature is bound to printing characters: the requester progressively advances to entries that match the characters you type without regard to case. You can use Backspace to incrementally undo your matched characters. This progressive matching works in two modes which you can switch between on the fly with either the Insert or Delete key. In the default mode, the cursor indicating your current selection simply advances to the next matching entry (if there is one). In the other mode, all entries which don't match the characters you've entered are removed from the list so you only see the matching entries. The Backspace key incrementally returns them to your list as your match becomes less specific. You can switch between the two modes as often as you wish while searching for your desired entry. This lets you quickly navigate large lists to get to the entries you really want.

One example of a requester is the list of commands appearing when you use the Help command. Another is the list of document words matching a prefix given to the AutoComplete command. A third example is the file requester that ne issues whenever a file operation is going to take place. In this case, pressing Return while on a directory name will enter that directory and refresh the requester with that directory's entries. Note also that, should the requester take too long to appear, you can interrupt the directory scanning with Control-\. However, the listing will likely be incomplete.

Yet another example of a requester is the list of documents you currently have open. This requester is displayed when you use the Select... entry from the Documents menu, or invoke the SelectDoc command with the f4 key. Documents with unsaved changes will be bold (if your terminal supports bold) and marked with an asterisk.

These documents are generally listed in the order they were opened. However, in this requester you can reorder these documents by using the keys bound to the NextDoc and PrevDoc commands, usually f2 and f3. Any document reordering and selection will only take effect if you exit the requester with the Return key.

You can also save named documents and close unmodified documents without leaving the SelectDoc requester by using the key bound to the Save and CloseDoc commands respectively, usually Control-S and Control-Q. You can't close the last document this way because it would cause ne to exit.

Regardless of the type of requester, you can confirm your selection with Return just as with the input line (see The Input Line), or you can escape the requester without making a selection with f1 or the Escape key (or whatever has been bound to the Escape command).

Moreover, if you are selecting a file name through the requester there is a third possibility: by escaping with the Tab key, the file or directory name that the cursor is currently on will be copied to the input line. This allows you to choose an existing name with Tab and modify the name on the input line before hitting Return.

Note that there are two items that always appear at the top of a file requester: ./ and ../. The first one represents the current directory and can be used to force a reread of the directory. The second one represents the parent directory and can be used to move up by one directory level.

The path to file names and directories selected through the requester will be relative to the current directory, i.e. the directory you were in when you invoked ne. The exception is when you've entered a path on the command line that starts with a /, then hit Tab to invoke the requester. In that case the path eventually returned by the requester will be an absolute path. (Note that you can change the current document's name from relative to absolute or absolute to relative with the NameConvert command either on the command line or from the Extras menu.)

All requesters present their selections by default in ``row major order,'' which means the second string is on the same row as the first but to its right, at the top of the second column, and so on across each row before filling in the next row down. If you prefer your lists displayed in ``column major order''---the first, second, and third strings are in the same column and each column is filled before starting on the next column to the right---then use the RequestOrder command to switch that preference. The setting can be stored in your default preferences the next time you save them. See Preferences Commands.

Syntax Highlighting
===================

Syntax highlighting is particularly useful for programming language text or other types of documents which have a strictly defined syntax. Colors indicate different syntactic categories of text according to the syntax definition in use.

Syntax definitions are stored in separate files. ne comes with a suite of syntax definitions for many popular programming languages and other common text file types. When you load a file, ne selects the appropriate syntax definition as determined by the filename extension in much the same way autoprefs are loaded. (See Virtual Extensions for ways to override a file's extension based on file contents.) It also contains a built-in table of common filename extensions that share the same syntax definitions. For example, both cbl, and cob files use the cobol definition. See the Syntax command for the complete list of built-in extension mappings.

If there is no matching syntax definition for the filename extension, or if the document you are editing has no filename yet, or you just want to try a different syntax definition, you can load and use the syntax definition of your choice with the Syntax command. It takes the syntax name as a parameter. For example, the name ``c'' works for C syntax files with extensions .c, .h, c++, etc. ne searches for the specified syntax definition file in the syntax subdirectory of your ~/.ne directory first. If not found there, ne then looks in the syntax subdirectory of ne's global directory for the syntax definition file. See Arguments.

With no parameter, the Syntax command prompts you for a syntax to load, the offered default being the currently loaded syntax if there is one. Use the Tab key at that prompt to get a list of available syntax recognizers.

One syntax definition you may find useful for any type of text file is called simply tabs. It highlights the TABs in your text so you can distinguish them from regular spaces.

You can create your own syntax definitions and store them in your ~/.ne/syntax directory (actually, modifying the colors of an existing definition is much easier; see Hints and Tricks). A complete explanation of syntax specifications is beyond the scope of this document, but the existing definition files should prove to be useful examples. In particular, the syntax/c.jsf file contains some particularly helpful comments. Syntax definition files have a .jsf extension. Do not include that extension when using the Syntax command.

Your own syntax recognizers will be preferred over the global recognizers. If you use the Tab key at the syntax prompt to display the requester of extant recognizers, yours will be marked with an asterisk and bold if your terminal supports that.

Syntax highlighting does incur a slight penalty in memory used per line of text, and it also consumes some CPU resources. For small to medium sized files you'll probably never notice. But for extremely large files---on the order of the size of your system's RAM---the difference could be significant. If you invoke ne with the --no-syntax parameter, ne will disable the syntax highlighting mechanism entirely, freeing up the memory and CPU otherwise consumed. (Note that if you are that tight on memory, you may need to disable the undo buffer as well. See DoUndo.) On the other hand, ne will silently disable syntax highlighting on files longer than ten million bytes, but you can force it using the Syntax command.

Note that there is a basic difference between these two cases: when you use the --no-syntax parameter, the additional memory is not allocated at all, and syntax highlighting cannot be enabled without restarting ne. On the contrary, the automatic disabling for long files keeps only ne from computing the actual highlighting, and it can be overridden as explained above.

ne uses code from another editor---the GPL-licensed joe---for its syntax highlighting capabilities. Because of this fact, the syntax definition files are identical, even to the .jsf extension, which is an acronym for ``Joe's Syntax File''. It's possible that if both joe and ne are installed on your system that they share the same syntax file directory.

Menus
=====

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.

You activate menus with the f1 key, or in case your keyboard does not have such a key, Escape, Escape-Escape or any key that is bound to the Escape command. Move around the menus pressing with the cursor keys, the Page Up and Page Down keys (which move to the first or last menu item in a menu), and the Home and End keys (which move to the first or last menus). You can also move around menus and menu items by pressing the alphabetic keys; a lower case letter will move to the first item in the current menu whose name starts with the given letter; an upper case letter will move to the first menu whose name starts with the given letter.

If you've activated the menus and you want to switch immediately to the command line, press the : key. The menus will clear and you'll find yourself on the command line. See The Command Line.

Each menu item of ne's standard menu corresponds to a single command. In explaining what each menu item allows you to do, we shall simply refer you to the section that explains the command relative to the menu item.

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

File
----

The File menu contains standard items that allow loading and saving files. Quitting ne (which doesn't save changes) or exiting ne (which does save changes) is also possible.

Open...
     See Open.

Open New...
     See OpenNew.

Save
     See Save.

Save As...
     See SaveAs.

Save All
     See SaveAll.

Quit Now
     See Quit.

Save&Exit
     See Exit.

About
     See About.

Documents
---------

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

New
     See NewDoc.

Clear
     See Clear.

Close
     See CloseDoc.

Next
     See NextDoc.

Prev
     See PrevDoc.

Select...
     See SelectDoc.

Edit
----

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

Mark Block
     See Mark.

Cut
     See Cut.

Copy
     See Copy.

Paste
     See Paste.

Erase
     See Erase.

Through
     See Through.

Delete Line
     See DeleteLine.

Delete EOL
     See DeleteEOL.

Mark Vert
     See MarkVert.

Paste Vert
     See PasteVert.

Open Clip...
     See OpenClip.

Save Clip...
     See SaveClip.

Search
------

The Search menu contains commands related to searching for specific contents or locations within a document.

Find...
     See Find.

Find RegExp...
     See FindRegExp.

Replace...
     See Replace.

Replace Once...
     See ReplaceOnce.

Replace All...
     See ReplaceAll.

Repeat Last
     See RepeatLast.

Goto Line...
     See GotoLine.

Goto Col...
     See GotoColumn.

Goto Mark...
     See GotoMark.

Match Bracket
     See MatchBracket.

Set Bookmark
     See SetBookmark.

Unset Bookmark
     See UnsetBookmark.

Goto Bookmark
     See GotoBookmark.

Macros
------

The Macros menu contains commands related to creating and using macros.

Record
     See Record.

Stop
     See Record.

Replace...
     See Replace.

Play Once
Play Many...
     See Play.

Play Macro...
     See Macro.

Open Macro...
     See OpenMacro.

Save Macro...
     See SaveMacro.

Extras
------

This menu contains a few special items that don't fit in obvious ways into other menus.

Exec...
     See Exec.

Suspend
     See Suspend.

Help...
     See Help.

Refresh
     See Refresh.

Undo
     See Undo.

Redo
     See Redo.

Undel Line
     See UndelLine.

Center
     See Center.

Shift Right
Shift Left
     See Shift.

Paragraph
     See Paragraph.

Adjust View
Center View
     See AdjustView.

ToUpper
     See ToUpper.

ToLower
     See ToLower.

Capitalize
     See Capitalize.

Navigation
----------

The Navigation menu contains commands related moving around in a document.

Move Left
     See MoveLeft.

Move Right
     See MoveRight.

Line Up
     See LineUp.

Line Down
     See LineDown.

Prev Page
     See PrevPage.

Next Page
     See NextPage.

Page Up
     See PageUp.

Page Down
     See PageDown.

Start Of File
     See MoveSOF.

End Of File
     See MoveEOF.

Start Of Line
     See MoveSOL.

End Of Line
     See MoveEOL.

Top Of Screen
     See MoveTOS.

Bottom Of Screen
     See MoveBOS.

Incr Up
     See MoveIncUp.

Incr Down
     See MoveIncDown.

Prev Word
     See PrevWord.

Next Word
     See NextWord.

Prefs
-----

The Prefs menu contains commands related to setting, storing, and using your preferred document flags.

Tab Size...
     See TabSize.

Tabs as Spaces
     See Tabs.

Insert/Over
     See Insert.

Free Form
     See FreeForm.

Status Bar
     See StatusBar.

Hex Code
     See HexCode.

Fast GUI
     See FastGUI.

Word Wrap
     See WordWrap.

Right Margin
     See RightMargin.

Auto Indent
     See AutoIndent.

Request Order
     See RequestOrder.

Preserve CR
     See PreserveCR.

Save CR/LF
     See CRLF.

Load Prefs...
     See LoadPrefs.

Save Prefs...
     See SavePrefs.

Load AutoPrefs
     See LoadAutoPrefs.

Save AutoPrefs
     See SaveAutoPrefs.

Save Def Prefs
     See SaveDefPrefs.

Regular Expressions
===================

Regular expressions are a powerful way of specifying complex search and replace operations. ne supports the full regular expression syntax on US-ASCII and 8-bit documents, but has to impose a restriction on character sets when searching in UTF-8 text. See UTF-8 Support.

Syntax
------

The following section is taken (with minor modifications) from the GNU regular expression library documentation and is 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 foo when regarded as a regular expression matches 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 foo|bar matches either the string foo or the string bar; the regular expression c[ad]*r matches any of the strings cr, car, cdr, caar, cadddar and all other such strings with any number of a's and d's.

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

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

Any two regular expressions A and B can be concatenated. The result is a regular expression that matches a string if A matches some amount of the beginning of that string and B matches the rest of the string.

As a simple example, we can concatenate the regular expressions f and o to get the regular expression fo, which matches only the string 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, *foo treats * as ordinary since there is no preceding expression on which the * can act. It is poor practice to depend on this behaviour; better to quote the special character anyway, regardless of where is appears.

The following are the characters and character sequences that 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.

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

*
     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 fo*, the * applies to the o, so fo* matches f followed by any number of o's.

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

     * always applies to the smallest possible preceding expression. Thus, fo* has a repeating o, not a repeating fo.

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

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

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

     Character ranges can also be included in a character set, by writing two characters with a - between them.  Thus, [a-z] matches any lower-case letter.  Ranges may be intermixed freely with individual characters, as in [a-z$%.], which matches any lower case letter or $, % 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: ], - and ^. As \ is not special inside character sets, you cannot use the shortcuts \s or \w there.

     To include a ] in a character set, you must make it the first character.  For example, []a] matches ] or a. To include a -, 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.

     Note that when searching in UTF-8 text, a character set may contain US-ASCII characters only.

[^ ... ]
     [^ begins a complement character set, which matches any character except the ones specified.  Thus, [^a-z0-9A-Z] matches all characters except letters and digits. Also in this case, when searching in UTF-8 text a complemented character set may contain US-ASCII characters only.

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

^
     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, ^foo matches a foo that occurs at the beginning of a line.

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

\
     has two functions: it quotes the above special characters (including \), and it introduces additional special constructs.

     Because \ quotes special characters, \$ is a regular expression that matches only $, and \[ is a regular expression that matches only [, and so on.

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

|
     specifies an alternative. Two regular expressions A and B with | in between form an expression that matches anything that either A or B will match.

     Thus, foo|bar matches either foo or bar but no other string.

     | applies to the largest possible surrounding expressions.  Only a
     surrounding ( ... ) grouping can limit the grouping power of
     |.

( ... )
     is a grouping construct that serves three purposes:

      1. To enclose a set of | alternatives for other operations. Thus, (foo|bar)x matches either foox or barx.

      2. To enclose a complicated expression for the postfix * to operate on. Thus, ba(na)* matches bananana et cetera, with any (zero or more) number of na's.

      3. To mark a matched substring for future reference.

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

\DIGIT
     After the end of a ( ... ) 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 \ followed by DIGIT to mean ``match the same text matched the DIGIT'th time by the ( ... ) construct.''  The ( ... ) constructs are numbered in order of commencement in the regexp.

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

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

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

\B
     matches the empty string, provided it is not at the beginning or end of a word.

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

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

\s
     matches any white-space character in US-ASCII. These are tab, Control-J (line feed), Control-k (vertical tab), Control-L (form feed), Control-M (carriage return), and space.

\w
     matches any word-constituent character. These are US-ASCII letters, numbers and the underscore, independently of the document encoding.

\W
     matches any character that is not a word-constituent.

Replacing regular expressions
-----------------------------

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

Another example: if you search for (a+)(b+), replacing with \2x\1, you will match any string composed by a series of a's followed by a series of b's, and you will replace it with the string obtained by moving the a in front of the b's, adding moreover x in between. For instance, aaaab will be matched and replaced by bxaaaa.

Note that the backslash character can escape itself. Thus, to put a backslash in the replacement string, you have to use \\.

Automatic Preferences
=====================

Automatic preferences let you set up a custom configuration that is automatically used whenever you open a file with a given extension. For instance, you may prefer a TAB size of three when editing C sources, but eight could be more palatable when writing electronic mail.

The use of autoprefs is definitely straightforward. You simply use the Save AutoPrefs menu item (or the SaveAutoPrefs command; see SaveAutoPrefs) when the current document has the given extension and the current configuration suits your tastes. The internal state of a series of options will be recorded as a macro containing commands that reproduce the current configuration. The macro is then saved in the ~/.ne directory (which is created if necessary) with the name given by the extension, postfixed with #ap. Thus, the C sources automatic preferences file will be named c#ap, the one for TeX files tex#ap, and so on.

Macros are generated with short or long command names depending on the status of the verbose macros flag. See VerboseMacros.

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

Emergency Save
==============

When ne is interrupted by an abnormal event (for instance, the crash of your terminal), it will try to save all unsaved documents in its current directory. Named documents will have their names prefixed with a #. Unnamed documents will be given names made up of hexadecimal numbers obtained by some addresses in memory that will make them unique.

UTF-8 Support
=============

ne can manipulate UTF-8 files and supports UTF-8 when communicating with the user. At startup, ne fetches the system locale description, and checks whether it contains the string utf8 or utf-8. In this case, it starts communicating with the user using UTF-8. This behaviour can be modified either using a suitable command line option (see Arguments), or using UTF8IO. This makes it possible to display and read from the keyboard a wide range of characters.

Independently of the input/output encoding, ne keeps track of the encoding of each document. ne does not try to select a particular coding on a document, unless it is forced to do so, for instance because a certain character is inserted. Once a document has a definite encoding, however, it keeps it forever.

More precisely, every document may be in one of three encoding modes: US-ASCII, when it is entirely composed of US-ASCII characters; 8-bit, if it contains also other characters, but it is not UTF-8 encoded; and finally, UTF-8, if it is UTF-8-encoded.

The behaviour of ne in US-ASCII and 8-bit mode is similar to previous versions: each byte in the document is considered a separate character.

There are, however, two important differences: first, if I/O is not UTF-8 encoded, any encoding of the ISO-8859 family will work flawlessly, as ne merely reads bytes from the keyboard and displays bytes on the screen. On the contrary, in the case of UTF-8 input/output ne must take a decision as to which encoding is used for non-UTF-8 documents, and presently this is hardwired to ISO-8859-1. Second, 8-bit documents use localized casing and character type functions. This means that case-insensitive searches or case foldings will work with, say, Cyrillic characters, provided that your locale is set correctly.

In UTF-8 mode, instead, ne interprets the bytes in the document in a different way---several bytes may encode a single character. The whole process is completely transparent to the user, but if you really want to look at the document content, you can switch to 8-bit mode (see UTF8).

For most operations, UTF-8 support should be transparent. However, in some cases, in particular when mixing documents with different encodings, ne will refuse to perform certain operations because of incompatible encodings.

The main limitation of UTF-8 documents is that when searching for a regular expression in a UTF-8 text, character sets may only contain US-ASCII characters (see Regular Expressions). You can, of course, partially emulate a full UTF-8 character set implementation specifying the possible alternatives using | (but you have no ranges).

Commands
********

Everything ne can do is specified through a command. Commands can be manually typed on the 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 ne, you will be faced sooner or later with using commands directly.

General Guidelines
==================

Every command in ne has a long and a short name. Except in a very few cases, the short name is given by two or three letters that are the initials of the words that form the long name. For instance, SearchBack has short name SB, SaveDefPrefs has the short name SDP, and AdjustView's short name is AV. There are some exceptions however. The most frequently used commands such as Exit have one-letter short names (X). Also some commands use a different short name to avoid clashes with a more common command's short name. For example, StatusBar's short name is ST rather than SB  to avoid clashes with SearchBack's short name.

A command always has at most one argument. This is a chosen limitation that allows ne's parsing of commands and macros to be very fast. Moreover, it nullifies nearly all problems related to delimiters, escape characters, and the like. 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 Help command says about the given command. Note that when a command's argument is enclosed in square brackets, it is optional.

Strings are general purpose arguments. Numbers are used to modify internal parameters, such as the size of a TAB. A flag modifier is an optional number that is interpreted as follows:

  * 0 means clearing the flag;

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

  * no number means toggling the flag.

Thus, StatusBar 1 will activate that status bar, while I will toggle insert/overstrike. This design choice is due to the fact that most of the time during interactive editing you need to change a flag. For instance, you may be in insert mode and you want to overstrike, or vice versa. Absolute settings (those with a number) are useful essentially for macros. It is reasonable to use the fastest approach for the most frequent interactive event. When a number or a string is required and the argument is optional, most of the time you will be prompted to type the argument on the command line.

As for the input line, for numeric arguments you can choose between decimal, octal and hexadecimal notation in the standard way: a number starting with 0 is considered in octal, a number starting with 0x is considered in hexadecimal, and in all other cases decimal base is assumed.

When a number represents how many times ne should repeat an action, it is always understood that the command will terminate when the conditions for applying it are no longer true. For instance, the Paragraph command accepts the number of paragraphs to format. But if not enough paragraphs exists in the text, only the available ones will be formatted.

This easily allows performing operations on an entire document by specifying preposterously huge numbers as arguments. ToUpper 200000000 will make all the words in the document upper case. (At least, one would hope so!) Note that this is much faster than recording a macro with the command ToUpper in it and playing it many times because in the former case the command has to be parsed just one time.

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

To handle situations such as an argument string starting with a space, ne implements a simple mechanism whereby you can enclose any string argument in double quotes. If the first non-blank character after the command and last character of the command line are double quotes, the quotes will be removed and whatever is left will be used as the string argument. For example, the Find command to find a space could be entered on the command line or in a macro as Find " ". The only case needing special treatment is when a string starts and ends with double quotes. The command Find ""quote"" would locate the next occurrence of the string "quote" (including the double quotes). However, Find onequote" wouldn't require special treatment because the command argument doesn't both start and end with a double quote.

File Commands
=============

These commands allow opening and saving files. They all act in the context of the current document (i.e., the document displayed when the command is issued).

Open
----

Syntax: Open [FILENAME]

Abbreviation: O

replaces the contents of the current document with that of the file specified by the FILENAME string. (To load FILENAME's content into a new document without changing the current document, see OpenNew.) The current document's macro, search, and replace strings are preserved.

If the optional 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 NoFileReq command; see 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 the current document is marked as modified at the time the command is issued, you have to confirm the action.

OpenNew
-------

Syntax: OpenNew [FILENAME]

Abbreviation: ON

creates a new document and loads into it the contents of the file specified by the optional FILENAME string. This new document will inherit the macro, search, and replace strings from the current document.

If FILENAME is unspecified, the file requester behaves the same as for the Open command; see Open.

Save
----

Syntax: Save

Abbreviation: S

saves the current document using its default file name.

If the current document is unnamed, the file requester will open and you will be prompted to select a file. (You can inhibit the file requester opening by using the NoFileReq command; see NoFileReq.)

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

If the file has been modified since the current document was loaded or last saved (perhaps by another user), ne will warn you before overwriting the updated file. If the current document's read only flag is set, ne will prompt you before attempting to save it.

SaveAs
------

Syntax: SaveAs [FILENAME]

Abbreviation: SA

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

If the optional FILENAME argument is not specified, the file requester will open and you will be prompted to select a file. (You can inhibit the file requester opening by using the NoFileReq command; see 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.

If the file has been modified since the current document was loaded or last saved (perhaps by another user), ne will warn you before overwriting the updated file. If the current document's read only flag is set, ne will prompt you before attempting to save it.

SaveAll
-------

Syntax: SaveAll

Abbreviation: SL

saves all modified documents. If any modified documents cannot be saved, the action is suspended and an error message is issued. Note that only named documents can be saved, so SaveAll will report an error if you have any modified unnamed documents. Other reasons SaveAll may fail include: if any of the modified documents' corresponding files have been updated since they were loaded or last saved, or if any modified documents' read only flags are set.

Document Commands
=================

These commands allow manipulation of the circular list of documents in ne.

Quit
----

Syntax: Quit

Abbreviation: Q

closes all documents and exits. If any documents are modified, you have to confirm the action.

Exit
----

Syntax: Exit

Abbreviation: X

saves all modified documents, closes them and exits. If any documents cannot be saved, the action is suspended and an error message is issued and no documents are closed. Note that only named documents can be saved, so Exit will report an error if you have any modified unnamed documents. Like SaveAll, Exit will not save a document if its corresponding file has been modified since the document was loaded or last saved, or if its read only flag is set, in which cases an error is reported and no documents are closed.

NewDoc
------

Syntax: NewDoc

Abbreviation: N

creates a new, empty, unnamed document that 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 a copy of the preferences of the current document.

Clear
-----

Syntax: Clear

Abbreviation: CL

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

CloseDoc
--------

Syntax: CloseDoc

Abbreviation: CD

closes the current document. If the document was modified since it was last saved, you have to confirm the action. If it is the only document, ne exits. Otherwise ne will select the most recently active next or previous document adjacent to the one you just closed as the new current document. See NextDoc, and PrevDoc.

NextDoc
-------

Syntax: NextDoc

Abbreviation: ND

sets as current document the next document in the document list. See PrevDoc and SelectDoc.

PrevDoc
-------

Syntax: PrevDoc

Abbreviation: PD

sets as current document the previous document in the document list. See NextDoc and SelectDoc.

SelectDoc
---------

Syntax: SelectDoc

Abbreviation: SD

displays a requester containing the names of all the documents in memory. Your cursor will be on your current document's name, and documents with unsaved changes will be indicated with asterisks (and bold if your terminal supports that). You select whichever document you want to become the current document by moving your cursor to its name and hitting Return.

While the list of documents is displayed, you can close unmodified documents with your CloseDoc key (Control-Q), save named documents with your Save key (Control-S), and you can alter their relative order using your NextDoc and PrevDoc keys (f2 and f3), which have the effect of moving the currently selected document forward or backward in the list, respectively.

Using plain characters and the BackSpace navigates your displayed document names based on their common prefixes. The text between the beginning and the cursor within the currently selected document's name is the current common prefix. The Ins key toggles between hiding or displaying names not matching the current common prefix. This can be especially useful if you have a large number of open documents.

If you escape from the requester, the requester goes away, you are returned to your original current document (unless you closed it!), and no reordering of documents takes place.

SelectDoc is especially useful if you have a large number of documents open or if you want to quickly see which documents contain unsaved changes. See NextDoc, and PrevDoc.

Clip Commands
=============

These commands control the clipping system. A clip is a snippet of text separate from any document, which you can save to a file or insert into a document. You can select text in a document and copy it to a clip, optionally deleting it from your text. You can also load text directly from a file into a clip. ne can have any number of clips, which are distinguished by an integer. Most clip commands act on the current clip, which can be selected with ClipNumber. Clips can be copied and pasted in two ways---normally (as lines of text) or vertically (as a rectangular block of characters).

Note that by using the Through command you can automatically pass a (possibly vertical) block of text through any filter (such as sort under UN*X).

Mark
----

Syntax: Mark [0|1]

Abbreviation: M

sets the mark at the current position or cancels the previous mark. The mark and cursor together define the range of text over which clips (Cut, Copy, Erase) and left and right shifts operate.

If you invoke Mark with no arguments, it will set the mark. If you specify 0 or 1, the mark will be cancelled or set to the current position, respectively.  A capital M appears on the status bar, if the mark is active.

MarkVert
--------

Syntax: MarkVert [0|1]

Abbreviation: MV

is the same as Mark, but the region manipulated by the cut/paste commands is the rectangle having as vertices the cursor and the mark. If you invoke MarkVert with no arguments, it will set the mark. If you specify 0 or 1, the mark will be cancelled or set to the current position, respectively. Moreover, a capital V, rather than a capital M, will appear on the status bar.

For example, if you have the following text:

        aaaBbbccc
        aaabbbccc
        aaabbbCcc

and you set a vertical mark at B then move the cursor to C, you can cut or copy all of the Bs.

If you have made a vertical cut or copy, it's very likely you will want to use PasteVert rather than the usual Paste to reinsert the text in a rectangle. See PasteVert.

Copy
----

Syntax: Copy [N]

Abbreviation: C

copies the contents of the characters lying 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 ClipNumber command; see ClipNumber. If the current mark was vertical, the rectangle of characters defined by the cursor and the mark is copied instead.

Cut
---

Syntax: Cut [N]

Abbreviation: CU

acts just like Copy, but also deletes the block being copied.

Paste
-----

Syntax: Paste [N]

Abbreviation: P

pastes the contents of specified clip into the current document at the cursor position. If you don't specify the clip number, the current clip is used; Specify which clip is current with ClipNumber.

Every time you paste into a document, a pair of bookmarks designated by < and > mark the start and end points of the text you pasted. Subsequently you can move to either end of a pasted block with the GotoBookmark < or GotoBookmark > commands.

PasteVert
---------

Syntax: PasteVert [N]

Abbreviation: PV

vertically pastes 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.

Every time you paste into a document, a pair of bookmarks designated by < and > mark the start and end points of the text you pasted. Subsequently you can move to either end of a pasted block with the GotoBookmark < or GotoBookmark > commands.

Erase
-----

Syntax: Erase

Abbreviation: E

acts like Cut, but the block is just deleted and not copied into any clip.

Shift
-----

Syntax: Shift [<|>][n][t|s]

Abbreviation: SH

shifts the text on lines between the mark and the cursor either right (>) or left (<) by adding or removing white space on each line. The adjustment size, specified as an unsigned integer n, is in units of the current tab size (t) or spaces (s). The defaults are >, 1, and t. Adjustments start at the left edge of a vertical mark, or column 1 otherwise. If the mark is not currently set, only the current line is affected.

Shift will insert tab characters only if s is not used, and both of the document's Tabs and ShiftTabs flags are set---in which case an upper case T will appear in the status bar. If either of the Tabs or ShiftTabs flags is unset (i.e there is no upper case T in the status bar) Shift will only insert spaces.

In the case of left shifts, if any indicated line has insufficient leading white space for the requested adjustment to be made, then Shift reports an error and makes no changes.

OpenClip
--------

Syntax: OpenClip [FILENAME]

Abbreviation: OC

loads the given file name as the current clip, just as if you cut or copied it from the current document; see Copy.

If the optional FILENAME argument is not specified, the file requester will open and you will be prompted to select a file. (You can inhibit the file requester opening by using the NoFileReq command; see NoFileReq.)

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

SaveClip
--------

Syntax: SaveClip [FILENAME]

Abbreviation: SC

saves the current clip to the given file name.

If the optional FILENAME argument is not specified, the file requester will open and you will be prompted to select a file. (You can inhibit the file requester opening by using the NoFileReq command; see NoFileReq.)

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

ClipNumber
----------

Syntax: ClipNumber [N]

Abbreviation: CN

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

If the optional argument N is not specified, you can enter it on the input line, the default being the current clip number.

Through
-------

Syntax: Through [COMMAND]

Abbreviation: T

asks the shell to execute COMMAND, piping the current block in the standard input, and replacing it with the output of the command. This command is most useful with filters, such as sort. Its practical effect is to pass the block through the specified filter.

Note that by selecting an empty block (or equivalently by having the mark unset) you can use Through to insert the output of any UN*X command in your file.

If the optional argument COMMAND is not specified, you can enter it on the input line.

Search Commands
===============

These commands control the search system. ne offers two complementary searching techniques: a simple, fast exact matching search (optionally ignoring case), and a very flexible and powerful, but slower, regular expression search based on the GNU regex library (again, optionally case insensitive).

Find
----

Syntax: Find [PATTERN]

Abbreviation: F

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 back search and case sensitive search flags. See SearchBack, and CaseSearch.

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

FindRegExp
----------

Syntax: FindRegExp [PATTERN]

Abbreviation: FX

searches the current document for the given extended regular expression (see Regular Expressions) . 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 back search and case sensitive search flags. See SearchBack, and CaseSearch.

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

Replace
-------

Syntax: Replace [STRING]

Abbreviation: R

moves to the first match of the most recent find string or regular expression and prompts you for which action to perform. You can choose among:

  * replacing the string found with the given string and moving to the next match (Yes);

  * moving to the next match (No);

  * replacing the string found with the given string, and stopping the search (Last);

  * stopping the search immediately (Quit);

  * replacing all occurrences of the find string with the given string (All);

  * reversing the search direction (Backward or Forward); this choice will also modify the value of the back search flag. See SearchBack.

Replace is mainly useful for interactive editing. ReplaceOnce, ReplaceAll and RepeatLast are more suited to macros.

If no find string was ever specified, you can enter it on the input line. If the optional argument STRING is not specified, you can enter it on the input line, the default being the last string used. When the last search was a regular expression search, there are some special features you can use in the replace string (see Regular Expressions) . See FindRegExp.

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

Warning: when recording a macro with Record, there is no trace in the macro of your interaction with ne during the replacement process. When the macro is played, you will again have 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 ReplaceOnce, ReplaceAll, and RepeatLast.

ReplaceOnce
-----------

Syntax: ReplaceOnce [STRING]

Abbreviation: R1

acts just like Replace, but without any interaction with you (unless there is no find string). The first string matched by the last search pattern, if it exists, is replaced by the given replacement string.

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

ReplaceAll
----------

Syntax: ReplaceAll [STRING]

Abbreviation: RA

is similar to ReplaceOnce, but replaces all occurrences of the last search pattern between the cursor position and the end of the document (in the direction indicated by the SearchBack flag) with the given replacement string.

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

Note that a single Undo will restore all the occurrences of the search pattern replaced by ReplaceAll. See Undo.

RepeatLast
----------

Syntax: RepeatLast [TIMES] [F|Find|R|Replace]

Abbreviation: RL

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 Replace operation ended with a global substitution). If you don't specify either FIND or REPLACE, it will repeat whichever one was last performed.

If any find or replace operation runs into the end of the document (in the direction indicated by the SearchBack flag) and stops, then and only then will a RepeatLast command ``wrap around'' to the other end of the document to continue the find or replace operation.

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

 1. Find (or FindRegExp) the string you are interested in;

 2. if you want to repeat a replace operation, ReplaceOnce with the replacement string you are interested in;

 3. now issue a RepeatLast N-1 command, where N is the number of occurrences you wanted to skip over, or replace.

The important thing about this sequence of actions is that it will work this way even in a macro. The Replace command cannot be used in a macro unless you really want to interact with ne during the macro execution. Avoiding interaction during macros is the primary reason the commands ReplaceAll and ReplaceOnce are provided.

MatchBracket
------------

Syntax: MatchBracket

Abbreviation: MB

moves the cursor to the bracket associated with the bracket the cursor is on. If the cursor is not on a bracket, or there is no bracket associated with the current one, an error message is issued. Recognized brackets are {}, (), [] <>, and `'. See AutoMatchBracket.

AutoMatchBracket
----------------

Syntax: AutoMatchBracket [0..15]

Abbreviation: AMB

sets the auto match bracket mode. When the cursor is on a recognized bracket ({}, (), [], <>, or `') and the associated matching bracket is on the screen, that matching bracket will be indicated according to the mode. The mode is either zero for no bracket matching, or the sum of 1 (altered foreground and background brightness), 2 (inverse), 4 (bold), and 8 (underline). If no mode is specified, ne prompts you for one. The default mode is 1. See MatchBracket.

SearchBack
----------

Syntax: SearchBack [0|1]

Abbreviation: SB

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

If you invoke SearchBack 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 b will appear on the status bar if the flag is true.

Note that this flag also can be set through interactions with the Replace command. See Replace.

CaseSearch
----------

Syntax: CaseSearch [0|1]

Abbreviation: CS

sets the case sensitivity flag. When this flag is true, the search commands distinguish between the upper and lower case letters. By default the flag is false.

If you invoke CaseSearch 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 c will appear on the status bar if the flag is true.

AutoComplete
------------

Syntax: AutoComplete [PREFIX]

Abbreviation: AC

attempts to extend the PREFIX using matching words from your open documents, and inserts the extended text into your document. If the PREFIX can be extended unambiguously, the matching text is immediately inserted into your document. Otherwise, ne displays a selection of all words in open documents that match PREFIX, and inserts the word you select into the current document. Matching words from the current document display normally; those which only exist in other open documents are bold and with a trailing asterisk. If no PREFIX is given on the command line, or if AutoComplete is selected from the Extras menu or using a keyboard shortcut, the word characters to the immediate left of the cursor in the current document are used as the PREFIX. Note that if no word characters are to the left of the cursor, or the PREFIX given on the command line is an empty string (""), then all words in all your open documents are displayed. Prefix matches may be case sensitive or not depending on the current document's CaseSearch flag state. See CaseSearch.

Macros Commands
===============

Macros are lists of commands. Any series of operations that has to be performed frequently is a good candidate for being a macro.

Macros can be written manually: they are just ASCII files, each command occupying a line (lines starting with # are considered comments; lines starting with other nonalphabetical characters are presently ignored). But the real power of macros is that they be recorded during the normal usage of ne. When the recording terminates, the operations that have been recorded can be saved for later use. Note that each document has its own current macro (the last macro that has been opened or recorded).

Record
------

Syntax: Record [0|1]

Abbreviation: REC

starts, stops, cancels, or resumes macro recording. With no arguments, Record starts recording your commands as a new macro unless recording is already underway. In that case, macro recording is stopped, and the newly recorded macro replaces the current document's unnamed macro. The new macro can be played or saved via Play, or SaveMacro. The default key binding for Control-T is Record with no arguments, and is by far the most common way to use the Record command.

If you've started recording a macro and wish to cancel rather than wipe out your existing macro, you can cancel the recording by using Record 0. An error will be displayed if you aren't recording already, but it's harmless.

Sometimes you've got a macro either recorded or loaded from a file (see OpenMacro), but you'd like to record additional commands onto the end of it. Record 1 will do that. It will start recording onto the end of a copy of your current document's macro. An error will be displayed if you are already recording, but it's otherwise harmless.

Play
----

Syntax: Play [TIMES]

Abbreviation: PL

plays the current document's macro the given number of times. If the optional argument TIMES is not specified, you can enter it on the input line.

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 containing a certain pattern by recording a macro that searches for the pattern and performs the operation, and then playing it a preposterously huge number of times.

Execution of a macro can be interrupted by Control-\.

Macro
-----

Syntax: Macro [FILENAME]

Abbreviation: MA

executes the given file name as a macro.

If the optional 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 NoFileReq command; see NoFileReq.)

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

Note that macros whose names do not conflict with a command can be called without using Macro. Whenever ne is required to perform a command it cannot find in its internal tables, it will look for a macro by that name in the current directory. If this search also fails, ne looks in ~/.ne and finally in the macros subdirectory of ne's global directory (defined when ne was built, or in a place specified by your NE_GLOBAL_DIR environment variable) for a macro file by that name.

Warning: the first time a macro is executed it is cached into a hash table and is kept forever in memory unless the UnloadMacros command is issued; see 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 ~/foobar/macro, a subsequent call for /usr/MACRO or even just MaCrO will use the cached version of ~/foobar/macro. Note that the cache table is global to ne and not specific to any single document. This greatly improves efficiency when macros are used repeatedly.

OpenMacro
---------

Syntax: OpenMacro [FILENAME]

Abbreviation: OM

loads the given file name as the current document's macro just as if you Recorded it; see Record.

If the optional 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 NoFileReq command; see NoFileReq.)

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

SaveMacro
---------

Syntax: SaveMacro [FILENAME]

Abbreviation: SM

saves the current document's macro in a file with the given name.

If the optional 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 NoFileReq command; see NoFileReq.)

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

SaveMacro is of course most useful for saving macros you just recorded. The macros can then be loaded as normal text files for further editing, if necessary. Note that SaveMacro converts InsertChar commands into a possibly smaller number of InsertString commands. This makes macros easier to read and edit. See InsertChar, and InsertString.

UnloadMacros
------------

Syntax: UnloadMacros

Abbreviation: UM

frees the macro cache list. After this command, the Macro command will be forced to search for the file containing the macros it has to play.

UnloadMacros is especially useful if you are experimenting with a macro bound to some keystroke, and you are interactively modifying it and playing it. UnloadMacros forces ne to look for the newer version available.

Undo Commands
=============

The following commands control the undo system.

Undo
----

Syntax: Undo [N]

Abbreviation: U

undoes the last N actions. If N is not specified, it is assumed to be one. After you undo a number of actions, you can Redo all or some of them; see Redo. However, if you take any new actions after having Undone some, you can no longer Redo those Undone actions. See Redo.

Redo
----

Syntax: Redo [N]

Abbreviation: RE

redoes the last N actions undone by Undo (as long as you don't take any actions that change the text between the Undo and Redo commands). If N is not specified, it is assumed to be one. You can only Redo actions that have been Undone. See Undo.

UndelLine
---------

Syntax: UndelLine [N]

Abbreviation: UL

inserts at the cursor position for N times the last non-empty line that was deleted with the DeleteLine command. If N is not specified, it is assumed to be one.

UndelLine 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 UndelLine works independently of the status of the undo flag. See DoUndo.

DoUndo
------

Syntax: DoUndo [0|1]

Abbreviation: DU

sets the flag that 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 invoke DoUndo 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 u will appear on the status bar if the flag is true. (The U will be upper case if the flag is true and the AtomicUndo level is non-zero.)

The usefulness of this option relies in the fact that the undo system is a major memory eater. If you plan to do massive editing (say, cutting and pasting 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 we see no reason to not keep the undo flag always true, and this is indeed the default.

AtomicUndo
----------

Syntax: AtomicUndo [0|+|-]

Abbreviation: AU

increases, decreases, sets or clears the AtomicUndo level. The normal level is zero. All current document changes made while the AtomicUndo level is above zero are treated as a single change by the Undo and Redo commands. If no parameter is given, a level of 0 is set to 1; otherwise the current non-zero level is decremented. If 0 is given, the level is reset to zero. Parameters of + and - respectively increment and decrement the level, which in no case can be negative. If the level is above zero, the DoUndo flag in the status bar, which is normally a lower-case u, becomes upper case U.

Two other actions will reset the AtomicUndo level to zero: invoking the Undo command, and disabling the undo system with the DoUndo command. You cannot set a non-zero AtomicUndo level unless the undo system is enabled.

Note: macros that you wish to undo and redo atomically---i.e., as if they were single commands---should begin with AtomicUndo + and end with AtomicUndo - so that they can call and/or be called by other macros.

Formatting Commands
===================

The following commands allow simple formatting operations on the text. Note that for ne a paragraph is delimited by an empty line or a line with leading white space incongruous with that of preceding lines.

Center
------

Syntax: Center [N]

Abbreviation: CE

centers N lines from the cursor position onwards. If 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 RightMargin command. See RightMargin.

Paragraph
---------

Syntax: Paragraph [N]

Abbreviation: PA

reformats N paragraphs from the cursor position onwards. If N is not specified, it is assumed to be one. The paragraphs are formatted relatively to the value of the right margin as set by the RightMargin command. See RightMargin.

ne's notion of a paragraph includes the current non-blank line (regardless of its leading white space) and all subsequent non-blank lines that have identical (to each other's---not to the first line's) leading white space. Therefore your paragraphs can have various first line indentations and left margins.

After the Paragraph command completes, your cursor will be positioned on the first non-blank character after the last reformatted paragraph (or, if there is no such character, at the end of the document).

Paragraph does not insert ``smart'' spaces after full stops and colons, nor does it do other ``smart'' things such as justification. If you need such facilities, you should consider using a text formatter. TeX for example is usually an excellent choice.

ToUpper
-------

Syntax: ToUpper [N]

Abbreviation: TU

shifts to upper case the letters from the cursor position up to the end of a word, and moves to the first letter of next word for N times.

The description of the command may seem a little bit cryptic. What is really happening is that there are situations where you only want to upper case 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 ToUpper with no argument.

If you apply ToUpper on the first character of a word, it will just upper case N words.

ToLower
-------

Syntax: ToLower [N]

Abbreviation: TL

acts exactly like ToUpper, but lowers the case. See ToUpper.

Capitalize
----------

Syntax: Capitalize [N]

Abbreviation: CA

acts exactly like ToUpper, but capitalizes, that is, makes the first letter upper case and the other ones lower case. See ToUpper.

RightMargin
-----------

Syntax: RightMargin [N]

Abbreviation: RM

sets the right margin for all formatting operations, and for WordWrap. See WordWrap.

If the optional argument N is not specified, you can enter it on the input line, the default being the current value of the right margin.

A value of zero for N will force ne to use (what it thinks it is) the current screen width as right margin.

WordWrap
--------

Syntax: WordWrap [0|1]

Abbreviation: WW

sets the word wrap flag. When this flag is true, ne will automatically break lines of text when you attempt to insert characters beyond the right margin. See RightMargin.

If you invoke WordWrap 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 w will appear on the status bar if the flag is true.

AutoIndent
----------

Syntax: AutoIndent [0|1]

Abbreviation: AI

sets the auto indent flag. When this flag is true, ne will automatically insert TABs and spaces on a new line (created by an 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 invoke AutoIndent 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 a will appear on the status bar if the flag is true.

AutoIndent features a nice interaction with 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 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). See Undo.

Preferences Commands
====================

These commands allow you to set your preferences, that is, the value of a series of flags that modify the behaviour of ne. (Some of the flag commands, like the command for the indent flag, appear in other sections.) The status of the flags can be saved and restored later either by writing them out to a file (saved as a macro that suitably sets the flags) or by pushing them onto a ``preferences stack''. The back search and the read only flags are not saved, because they do not represent a preference, but rather a temporary state. The escape time and the turbo parameter are global to ne, and are not saved. However, you can add manually to a preferences file any preferences command (such as EscapeTime or Turbo); usually, this will be done to the default preferences file ~/.ne/.default#ap.

Note that there is an automatic preferences system, which automagically loads a preferences file related to the extension of the file name. Automatic preferences files are kept in your ~/.ne directory. They are named as an extension postfixed with #ap. Each time you open a file whose name has an extension for which there is an automatic preferences file, the latter is executed. Opening a file which has no extension causes the prefs from ~/.ne/.default#ap to be loaded. If you want to inhibit this process, you can clear the automatic preferences flag. See AutoPrefs.

Flags
-----

Syntax: Flags

Abbreviation: FLAG

displays a list of all the status flags for ne and their associated commands. It is not recorded when recording a macro.

     FLAG COMMAND      ABBR  DESCRIPTION
       i   Insert        I    inserts new characters (vs. replacing)
       a   AutoIndent    AI   aligns cursor under previous line after <Return>
       b   SearchBack    SB   searches search backward rather than forward
       c   CaseSearch    CS   searches are case sensitive
       w   WordWrap      WW   breaks long lines as you type
       f   FreeForm      FF   allows cursor to move beyond the end of lines
       p   AutoPrefs     AP   use automatic preferences based on file extension
       v   VerboseMacros VM   record macros using use long command names
       u   DoUndo        DU   record edits for later undoing
       r   ReadOnly      RO   changes are not allowed/saves are prompted
       t/T Tabs          TAB  TAB key inserts TABs instead of spaces
       T   ShiftTabs     SHT  Shift may insert TABs (only if 't' is also set)
       d   DelTabs       DT   BS and DEL may remove tabs worth of space
       B/! Binary        B    affects file loading/saving
       M   Mark          M    mark set for line-oriented block operations
       V   MarkVert      MV   like mark, but block is rectangle
       R   Record        REC  actions are being recorded in a macro
       P   PreserveCR    PCR  affects how <CR> chars are loaded from files
       C   CRLF          CRLF use CR/LF as line terminator
       @   UTF8IO        U8IO I/O (keyboard and terminal) are UTF-8 encoded
     A/8/U UTF8          U8   the document encoding (ASCII, 8-bit or UTF-8)
       */_ Modified      MOD  document has been modified since last saved
       _   (none)             file's modtime changed since doc was loaded/saved

The RequestOrder and AutoMatchBracket flags' states are not indicated on the status bar. See RequestOrder and AutoMatchBracket respectively. A ! indicates the last line is not terminated.

AutoPrefs
---------

Syntax: AutoPrefs [0|1]

Abbreviation: AP

sets the automatic preferences flag. If this flag is true, each time an Open command is executed and a file is loaded, ne will look for an automatic preferences file in your ~/.ne directory. The preferences file name is given by the extension of the file loaded, postfixed with #ap. Thus, for instance, C sources have an associated c#ap file. See Automatic Preferences.

If you invoke AutoPrefs 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 p will appear on the status bar if the flag is true.

Binary
------

Syntax: Binary [0|1]

Abbreviation: B

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, line feeds, 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 itself. Thus, binary editing within ne should be considered not a normal activity, but rather an exceptional one.

If you invoke Binary 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 B will appear on the status bar if the flag is true. If false, a - or ! will indicate whether the last line of the document is empty, which will determine whether the resulting file will have a normal line termination when the document is saved.

Insert
------

Syntax: Insert [0|1]

Abbreviation: I

sets the insert flag. If this flag is true, the text you type is inserted, otherwise it overwrites the existing characters. This also governs the behaviour of the InsertChar and InsertString commands.

If you invoke Insert 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 i will appear on the status bar if the flag is true.

FastGUI
-------

Syntax: FastGUI [0|1]

Abbreviation: FG

sets the fast graphical user interface flag. When this flag is true, ne tries to print as little as possible while displaying menus and the status bar. In particular, menu items are highlighted by the cursor only, the status bar is not highlighted (which allows printing it with fewer characters), the current position of the mark is not highlighted, and the hexadecimal code for the character under the cursor is not displayed. This option is only (but very) useful if you are using ne through a slow connection.

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

The FastGUI setting is saved in your ~/.ne/.default#ap file when you use the SaveDefPrefs command or the Save Def Prefs menu. It is not saved by the SaveAutoPrefs command.

FreeForm
--------

Syntax: FreeForm [0|1]

Abbreviation: FF

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

If you invoke FreeForm 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 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 has engaged users 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.

NoFileReq
---------

Syntax: NoFileReq [0|1]

Abbreviation: NFR

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

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

RequestOrder
------------

Syntax: RequestOrder [0|1]

Abbreviation: RQO

sets the request order flag. When this flag is true, the requester displays entries in column order. Otherwise entries are displayed by rows.

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

The RequestOrder setting is saved in your ~/.ne/.default#ap file when you use the SaveDefPrefs command or the Save Def Prefs menu. It is not saved by the SaveAutoPrefs command.

StatusBar
---------

Syntax: StatusBar [0|1]

Abbreviation: ST

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 we are aware of:

  * if you are using ne through a slow connection, updating the line/column indicator can really slow down editing;

  * scrolling caused by cursor movement on terminals that do not allow to set a scrolling region can produce annoying flashes at the bottom of the screen.

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

The StatusBar setting is saved in your ~/.ne/.default#ap file when you use the SaveDefPrefs command or the Save Def Prefs menu. It is not saved by the SaveAutoPrefs command.

HexCode
-------

Syntax: HexCode [0|1]

Abbreviation: HC

sets the hex code flag. When this flag is true, the hexadecimal code of the character currently under the cursor is displayed on the status bar.

ReadOnly
--------

Syntax: ReadOnly [0|1]

Abbreviation: RO

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). Saving read only documents is inhibited as well; you must affirmatively answer a prompt to save a document with the read only flag set. This flag is automatically set whenever you open a file that you cannot write to. See Open.

If you invoke ReadOnly 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 r will appear on the status bar if the flag is true.

EscapeTime
----------

Syntax: EscapeTime [N]

Abbreviation: ET

sets the escape time. The Escape key is recognized as such after N tenths of second. (see Motivations and Design.) Along slow connections, it can happen that the default value of 10 is too low: in this case, escape sequences (e.g., those of the arrow keys) could be erroneously broken into an escape and some spurious characters. Rising the escape time usually solves this problem. Allowed values range from 0 to 255, with 0 disabling escape time, which means that a single Escape will not be recognized as a distinct command. Note that you can accelerate the recognition of the Escape key by hitting it twice in a row.

Note that the escape time is global to ne, and it is not saved. However, you can add an EscapeTime command manually to a preferences file.

TabSize
-------

Syntax: TabSize [SIZE]

Abbreviation: TS

sets the number of spaces ne will use when expanding a TAB character.

If the optional argument SIZE is not specified, you can enter it on the input line, the default being the current TAB size. Allowed values are strictly between 0 and half the width of the screen.

Tabs
----

Syntax: Tabs [0|1]

Abbreviation: TAB

sets the Tabs flag. When this flag is set, Tab key and the InsertTab command will insert literal TAB characters. Otherwise it will insert enough spaces to have the same visual effect.

In normal editing, the Tab key invokes the command "InsertTab 1". Unlike most others, the Tab key cannot be mapped to other commands. Thus the Tabs flag provides the only customization ne offers for the Tab key.

If set, either a lower case t or upper case T will appear in the status bar depending on the state of the ShiftTabs flag. (The ShiftTabs flag is irrelevant if the Tabs flag is off.) See ShiftTabs.

DelTabs
-------

Syntax: DelTabs [0|1]

Abbreviation: DT

sets the DelTabs flag. When this flag is set, a d will appear on the status bar, and the BackSpace and Del keys will remove a tab's worth of SPACE characters if a TAB character could have occupied the same whitespace in the current line as the removed spaces. This is the deletion counterpart to the Tabs flag. See Tabs.

ShiftTabs
---------

Syntax: ShiftTabs [0|1]

Abbreviation: SHT

sets the ShiftTabs flag. ShiftTabs has an effect only when the Tabs flag is set, in which case an upper case T appears in the status bar. When this flag and the Tabs flag are both set, left and right Shift commands may use tab characters to adjust leading white space. Otherwise only spaces are used. See Shift.

Turbo
-----

Syntax: Turbo [STEPS]

Abbreviation: TUR

sets the turbo parameter. Iterated actions and global replaces will update at most STEPS lines of the screen (or at most twice the number of visible rows if STEPS is zero); 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 STEPS lines, 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 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, small values ensure that operations such as paragraph formatting will not take too long.

You have to be careful about setting the turbo parameter too low. ne keeps track internally of the part of the screen that 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 zero, which means twice the number of lines of the screen; for several reasons this does seem to be a good value.

VerboseMacros
-------------

Syntax: VerboseMacros [0|1]

Abbreviation: VM

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 edit the macro manually, but it can slow down command parsing.

If you invoke VerboseMacros 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 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.

The VerboseMacros setting is saved in your ~/.ne/.default#ap file when you use the SaveDefPrefs command or the Save Def Prefs menu. It is not saved by the SaveAutoPrefs command.

PreserveCR
----------

Syntax: PreserveCR [0|1]

Abbreviation: PCR

sets the preserve carriage returns flag.  When a file is loaded into a document for which this flag is false, both CR (carriage return) and NL (new line) characters are treated as line terminators. If the flag is true, CR characters do not act as line terminators but are instead preserved in the document. This flag has no effect except when loading a file into a document.

If you invoke PreserveCR 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 P will appear on the status bar if the flag is true.

CRLF
----

Syntax: CRLF [0|1]

Abbreviation: CRLF

sets the CR/LF flag. When a file is saved from a document for which this flag is true, both a CR (carriage return) and a NL (new line) character are output as line terminators. This flag has no effect except when saving a file.

This flag is automatically set if you load a file that has at least one CR/LF sequence in it.

If you invoke CRLF 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 C will appear on the status bar if the flag is true.

BracketedPaste
--------------

Syntax: BracketedPaste [0|1|MACRO_NAME_BEFORE MACRO_NAME_AFTER]

Abbreviation: BP

``Bracketed paste'' is an informal though widely adopted protocol between terminal mode programs (like ne) and the terminal emulators through which they present their user interfaces. When BracketedPaste is enabled, blocks of text pasted from a system clipboard are ``bracketed'' -- that is, they are immediately preceded and followed -- by special character sequences which distinguish such blocks from text you actually typed. Bracketed paste text is usually already indented, tabbed, and line wrapped. The BracketedPaste command lets you manage factors that change input handling while inserting bracketed paste text into your document.

BracketedPaste 0 disables bracketed paste support entirely; BracketedPaste 1 enables bracketed paste support, temporarily disables the AutoIndent flag, and increases the AtomicUndo level during bracketed pastes; when given a pair of macro names, bracketed paste support is enabled and the indicated macros will be run immediately before and after processing bracketed paste text. The macros need not already exist. (See the Macro help page, especially the warning at the bottom.) BracketedPaste with no argument will prompt you to enter a new value with the prompt's default being the current value.

The default value is 1 -- enabled with default behaviour. This is an automatic preference (see AutoPrefs) and so will be saved by both SaveAutoPrefs and SaveDefPrefs.

The flags AutoIndent, Tabs, ShiftTabs, and WordWrap all affect handling of pasted text. The examples below show contents of before and after macros which would have effects similar to BracketedPaste 1.

     # Invoked Before Bracketed Paste    # Invoked After Bracketed Paste
     SetBookMark <                       SetBookMark >
     PushPrefs                           PopPrefs
     AtomicUndo +                        AtomicUndo -
     AutoIndent 0                        GotoBookMark <
     Refresh                             Refresh

VisualBell
----------

Syntax: VisualBell [0|1]

Abbreviation: VB

sets the visual bell flag. When this flag is true, the terminal will flash (if possible) instead of beeping.

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

PushPrefs
---------

Syntax: PushPrefs [N]

Abbreviation: PUSHP

pushes N copies of the user preferences onto a stack. If not specified, N defaults to one. Use the PopPrefs command to pop preferences off the stack and restore the values. See PopPrefs. Note that the preferences stack is global, not document-specific, so you could PushPrefs one document's preferences, switch documents, then PopPrefs those preferences, thereby altering the preferences for the second document. The maximum preferences stack depth is 32.

PushPrefs and PopPrefs are useful in macros that require certain preferences to work properly.  A macro can PushPrefs, change any preferences necessary, do its work, then PopPrefs to restore the users previous preferences settings.

PushPrefs saves the following values on the preferences stack:

       AutoIndent  DelTabs   NoFileReq    StatusBar  VisualBell
       AutoPrefs   DoUndo    PreserveCR   ShiftTabs  WordWrap
       Binary      FreeForm  ReadOnly     Tabs
       CaseSearch  HexCode   RightMargin  TabSize
       ClipNumber  Insert    SearchBack   UTF8Auto

PopPrefs
--------

Syntax: PopPrefs [N]

Abbreviation: POPP

pops N sets of preferences from the preferences stack (where they were placed previously by PushPrefs) and applies those preferences to the current document. See PushPrefs. If not specified, N defaults to one. Note that the preferences stack is global, not document specific. Therefore you could PushPrefs one document's preferences, switch documents, then PopPrefs those settings altering the preferences for the second document. The maximum preferences stack depth is 32.

PushPrefs and PopPrefs are useful in macros that require certain preferences to work properly.  A macro can PushPrefs, change any preferences necessary, do its work, then PopPrefs to restore the users previous preferences settings.

PopPrefs restores the following values from the preferences stack:

       AutoIndent  DelTabs   NoFileReq    StatusBar  VisualBell
       AutoPrefs   DoUndo    PreserveCR   ShiftTabs  WordWrap
       Binary      FreeForm  ReadOnly     Tabs
       CaseSearch  HexCode   RightMargin  TabSize
       ClipNumber  Insert    SearchBack   UTF8Auto

LoadPrefs
---------

Syntax: LoadPrefs [FILENAME]

Abbreviation: LP

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

If the optional 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 NoFileReq command; see NoFileReq.) If you escape from the file requester, you can input the file name on the command line.

Note that a preferences file is just a macro containing only option modifiers. You can manually edit a preferences file for special purposes, such as filtering out specific settings. See Hints and Tricks.

SavePrefs
---------

Syntax: SavePrefs [FILENAME]

Abbreviation: SP

saves the current preferences to the given file.

If the optional 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 NoFileReq command; see NoFileReq.) If you escape from the file requester, you can input the file name on the command line.

LoadAutoPrefs
-------------

Syntax: LoadAutoPrefs

Abbreviation: LAP

loads the preferences file in ~/.ne associated with the current document's file name extension. If the current file name has no extension, the default preferences are loaded. See AutoPrefs.

SaveAutoPrefs
-------------

Syntax: SaveAutoPrefs

Abbreviation: SAP

saves the current preferences to the file in ~/.ne associated with the current document's file name extension. If the current file name has no extension, an error message is issued. See AutoPrefs.

SaveDefPrefs
------------

Syntax: SaveDefPrefs

Abbreviation: SDP

saves the current preferences to the ~/.ne/.default#ap file. This file is always loaded by ne at startup.

Modified
--------

Syntax: Modified [0|1]

Abbreviation: MOD

sets the modified flag.  This flag is set automatically whenever a document is modified, and is used to determine which documents need to be saved by SaveAll or when ne exits.  Normally you would not alter this flag, but when a document is inadvertently modified and you don't want the changes saved, Modified provides a way to make ne consider the document unchanged.

If you invoke Modified 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 asterisk (*) will appear on the status bar when this flag is set. If your terminal supports underlining, it will be underlined if the corresponding file's modification time has changed since the document was loaded or saved (perhaps by another user).

Syntax
------

Syntax: Syntax [NAME|*]

Abbreviation: SY

loads the syntax with the given name, and colors the current document accordingly.

If the optional NAME argument is not specified, you are prompted for one. The current one, if set, is suggested as the default. Use the Tab key for a requester of the extant syntax recognizers. The special NAME * turns off syntax highlighting for the current document. Otherwise, NAME must match a syntax definition either in your ~/.ne/syntax directory or in a directory named syntax inside ne's global directory. Additionally, ne has a table mapping common suffixes to syntax names. If there is no syntax with a given name, ne will try to remap the name using the following table  (the string before the colon is the name of the syntax file):

        ada: adb, ads
        asm: s
        c: c++, cc, cpp, cxx, h, h++, hpp, l, lex, y, yacc
        cobol: cbl, cob
        csh: tcsh
        diff: patch
        fortran: f, F, for, f90, F90
        html: htm
        java: js
        lisp: el, lsp
        mason: mas
        ocaml: ml, mli
        pascal: p, pas
        perl: pl, pm
        ps: eps
        puppet: pp
        python: py, sage
        rexx: rex
        ruby: rb
        sh: bash, bash_login, bash_logout, bash_profile, bashrc, ksh,
            profile, rc
        skill: il
        tex: latex, dtx, sty
        texinfo: texi, txi
        troff: 1
        verilog: v, vh, vhd
        xml: xsd
        yaml: yml

UTF8
----

Syntax: UTF8 [0|1]

Abbreviation: U8

sets the UTF-8 flag.  When this flag is true, ne considers the current document as UTF-8 coded.  Note that this flag is set automatically upon file loading (if possible) if you required automatic detection. See UTF8Auto.

If you invoke UTF8 with no arguments, it will toggle the flag. If you specify 0 or 1, the flag will be set to false or true, respectively. When you try to set this flag, the document will be checked for UTF-8 compliance, and you will get an error message in case of failure. When you try to reset it, the document is set to ASCII or 8-bit, depending on its content.  A U will appear on the status bar if the flag is true. Alternatively, an A or an 8 will be displayed to denote whether the document is composed exclusively by US-ASCII characters, or also by other 8-bit characters (whose encoding is likely to be part of the ISO-8859 family). Note that each time this command modifies the document encoding, it also resets the undo buffer.

UTF8Auto
--------

Syntax: UTF8Auto [0|1]

Abbreviation: U8A

sets the UTF-8 automatic-detection flag.  When this flag is true, ne will try to guess whether a file just loaded is UTF-8 encoded. Moreover, when a non US-ASCII character is inserted in a pure US-ASCII document, ne will automatically switch to UTF-8. See UTF8. The flag is true by default if ne detects UTF-8 I/O at startup. See UTF8IO.

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

UTF8IO
------

Syntax: UTF8IO [0|1]

Abbreviation: U8IO

sets the UTF-8 input/output flag.  This flag is set automatically depending on your locale setting, and is used to determine whether communication with the user (keyboard and terminal) should be UTF-8 encoded. Normally you would not alter this flag, but sometimes ne may make the wrong guess (e.g., when you are remotely connected).

If you invoke UTF8IO 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 @ will appear on the status bar if the flag is true.

Navigation Commands
===================

These commands allow you to move through a document. Besides the standard commands that allow you to move by lines, pages, et cetera, ne has bookmarks that let you mark a position in a file so to move to the same position later.

MoveLeft
--------

Syntax: MoveLeft [N]

Abbreviation: ML

moves the cursor to the left by one character N times. If the optional N argument is not specified, it is assumed to be one.

MoveRight
---------

Syntax: MoveRight [N]

Abbreviation: MR

moves the cursor to the right by one character N times. If the optional N argument is not specified, it is assumed to be one.

LineUp
------

Syntax: LineUp [N]

Abbreviation: LU

moves the cursor up by one line N times. If the optional N argument is not specified, it is assumed to be one.

LineDown
--------

Syntax: LineDown [N]

Abbreviation: LD

moves the cursor down by one line N times. If the optional N argument is not specified, it is assumed to be one.

GotoLine
--------

Syntax: GotoLine [LINE]

Abbreviation: GL

moves the cursor to the LINEth line of the file. If LINE is zero or greater than the number of lines in the file, the cursor is moved to the last line.

If the optional argument LINE is not specified, you can enter it on the input line; the default input response is the current line number.

GotoColumn
----------

Syntax: GotoColumn [COLUMN]

Abbreviation: GC

moves the cursor to the COLUMNth column of the file.

If the optional argument LINE is not specified, you can enter it on the input line; the default input response is the current column number.

GotoMark
--------

Syntax: GotoMark

Abbreviation: GM

moves the cursor to the current mark, if it exists. See Mark.

GotoMark is mainly useful if you forgot where you started marking. If you want to record positions in a file and jump to them later, you may want to use bookmarks instead. See SetBookmark.

PrevPage
--------

Syntax: PrevPage [N]

Abbreviation: PP

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

NextPage
--------

Syntax: NextPage [N]

Abbreviation: NP

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

PageUp
------

Syntax: PageUp [N]

Abbreviation: PUP

pages the screen backward by N screens. If N is not specified, it is assumed to be one.

PageDown
--------

Syntax: PageDown [N]

Abbreviation: PDN

pages the screen forward by N screens.  If N is not specified, it is assumed to be one.

PrevWord
--------

Syntax: PrevWord [N][<|>]

Abbreviation: PW

moves the cursor to the left to the Nth word beginning or ending. If the optional N argument is not specified, one is used. The optional < or > determines whether to move to the word beginning or ending, respectively. If unspecified, the left end (<) is used.

NextWord
--------

Syntax: NextWord [N][<|>]

Abbreviation: NW

moves the cursor to the right to the Nth word beginning or ending. If the optional N argument is not specified, one is used. The optional < or > determines whether to move to the word beginning or ending, respectively. If unspecified, the left end (<) is used.

MoveEOL
-------

Syntax: MoveEOL

Abbreviation: EOL

moves the cursor to the end of the current line  (EOL = end of line).

MoveSOL
-------

Syntax: MoveSOL

Abbreviation: SOL

moves the cursor to the start of the current line (SOL = start of line).

MoveTOS
-------

Syntax: MoveTOS

Abbreviation: TOS

moves the cursor to the top line of the screen (TOS = top of screen).

MoveBOS
-------

Syntax: MoveBOS

Abbreviation: BOS

moves the cursor to the lowest line currently visible (BOS = bottom of screen).

MoveEOF
-------

Syntax: MoveEOF

Abbreviation: EOF

moves the cursor to the end of the document (EOF = end of file).

MoveSOF
-------

Syntax: MoveSOF

Abbreviation: SOF

moves the cursor to the start of the document (SOF = start of file).

MoveEOW
-------

Syntax: MoveEOW [<|>]

Abbreviation: EOW

moves the cursor to the end of the current word, that end being the right end unless you include the optional parameter <. If the cursor is not currently in a word, or if it's already at the indicated end, it retains its current location.

MoveEOW is extremely useful in macros, because it allows you to copy precisely the word the cursor is on. See Hints and Tricks.

MoveIncUp
---------

Syntax: MoveIncUp

Abbreviation: MIU

moves the cursor incrementally towards the beginning of the document. More precisely, if the cursor is not on the start of the line it lies on, then it is moved to the start of that line. Otherwise, if it is on the first line of the screen, then it is moved to the start of the document; otherwise, it is moved to the first line of the screen.

MoveIncDown
-----------

Syntax: MoveIncDown

Abbreviation: MID

moves the cursor incrementally towards the end of the document.  More precisely, if the cursor is not on the end of the line it lies on, then it is moved to the end of that line. Otherwise, if it is on the last line of the screen, then it is moved to the end of the document; otherwise, it is moved to the last line of the screen.

AdjustView
----------

Syntax: AdjustView [T|M|B|L|C|R] [N]

Abbreviation: AV

shifts the view (text visible in the terminal window) horizontally or vertically without changing the cursor's position in the document. View adjustments are constrained by the current TAB size and the length and width of the current document. If called with no arguments T is assumed.

T, M, and B cause vertical shifts so that the current line becomes the top, middle, or bottom-most visible line respectively.

L, C, and R cause horizontal shifts, making the current column the left-most, center, or right-most visible positions.

A optional number N immediately after T, B, L, or R indicate the number or rows or columns to shift the view toward the top, bottom, left, or right of the window.

Horizontal and vertical adjustment specifications may be combined, so that for example AdjustView TL shifts the view so that the current position becomes the top left-most character on screen (within the limits of the current TAB size). Likewise, AdjustView B3R5 shifts the view three lines toward the bottom and five columns (excepting TAB size) toward the right.

ToggleSEOF
----------

Syntax: ToggleSEOF

Abbreviation: TSEOF

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 is very useful in order to gain some keystrokes on systems with very few keys. See also ToggleSEOL, MoveSOF, and MoveEOF.

ToggleSEOL
----------

Syntax: ToggleSEOL

Abbreviation: TSEOL

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 is very useful in order to gain some keystrokes on systems with very few keys. See also ToggleSEOF, MoveSOL, and MoveEOL.

SetBookmark
-----------

Syntax: SetBookmark [N|+1|-1|<|>|-|?]

Abbreviation: SBM

sets a document bookmark to the current cursor position. Each document has 10 available bookmarks designated 0 to 9, the most recently pasted block's start and end designated < and >, plus the automatic bookmark designated by -. If no option is given, 0 is assumed. Values of N from 0 to 9 set the Nth bookmark, while +1 and -1 indicate respectively the next and previous available unset bookmarks. You can also set the pasted block's start and end which will be reset on the next Paste or PasteVert command, or the - automatic bookmark, but it will be reset automatically to the current position whenever a GotoBookmark command is issued.

The ? option will cause SetBookmark to prompt you for a bookmark designation. The promp will include an indication of which bookmarks are currently set. You may find this useful in macros, or to bind a key to SetBookmark ?.

GotoBookmark
------------

Syntax: GotoBookmark [N|+1|-1|<|>|-]|?]

Abbreviation: GBM

moves the cursor to the designated bookmark if that bookmark is set; see SetBookmark. Each document has 10 available bookmarks designated 0 to 9, either end of the most recently pasted text block designated < and >, plus the automatic bookmark designated by -. If no option is given, 0 is assumed. The options +1 and -1 indicate respectively the next and previous set bookmarks, so that repeated GotoBookmark +1 commands will cycle through all currently set numbered bookmarks.

When successful, the automatic bookmark - is set to the position in the document from which the command was issued, so that GotoBookmark - returns you to the location from which you last issued a successful GotoBookmark command. Subsequent repeated GotoBookmark - commands will toggle you between the two locations.

The ? option will cause GotoBookmark to prompt you for a bookmark designation. The promp will include an indication of which bookmarks are currently set. You may find this useful in macros, or to bind a key to GotoBookmark ?.

UnsetBookmark
-------------

Syntax: UnsetBookmark [N|+1|-1|<|>|-|*]

Abbreviation: UBM

unsets either the Nth bookmark (0 through 9), the next (+1) or previous (-1) set bookmarks, the bookmarks designating the start (<) or end (>) of the most recently pasted text block, the automatic (-) bookmark, or all (*) bookmarks, making it as if they had never been set; see SetBookmark. If no option is specified, N is assumed to be zero.

While you can unset the automatic bookmark -, it will be reset automatically to the current position whenever a GotoBookmark command is issued.

Editing Commands
================

These commands allow modifying a document directly.

InsertChar
----------

Syntax: InsertChar [CODE]

Abbreviation: IC

inserts a character whose ASCII code is CODE at the current cursor position. CODE can be either decimal, hexadecimal if preceded by 0x, or octal if preceded by 0. In any case, CODE must be different from 0. All the currently active preferences options (insert, word wrapping, auto indent, et cetera) are applied.

If the optional argument CODE is not specified, you can enter it on the input line, the default being the last inserted character.

Note that inserting a line feed (10) is completely different from inserting a line with InsertLine. InsertChar 10 puts the control char Control-J in the text at the current cursor position. See InsertLine.

Note also that SaveMacro converts InsertChar commands into a possibly smaller number of InsertString commands. This makes macros easier to read and edit. See SaveMacro.

InsertString
------------

Syntax: InsertString [TEXT]

Abbreviation: IS

inserts TEXT at the current cursor position. If the optional argument TEXT is omitted, you will be prompted for it on the command line.  All the currently active preferences options (insert, word wrapping, auto indent, et cetera) are applied.

Note that SaveMacro converts InsertChar commands into a possibly smaller number of InsertString commands. This makes macros easier to read and edit. See SaveMacro.

InsertTab
---------

Syntax: InsertTab [N]

Abbreviation: IT

inserts either N literal TAB characters or one or more spaces sufficient to advance the current cursor position N tab stops depending on the Tabs flag. See Tabs, TabSize.

DeleteChar
----------

Syntax: DeleteChar [N]

Abbreviation: DC

deletes N characters from the text. If the optional 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 words, the carriage return between the two lines will be deleted. Note that if the cursor is past the end of the current line, no action will be performed.

DeletePrevWord
--------------

Syntax: DeletePrevWord [N]

Abbreviation: DPW

deletes text from the current position through the first character of the N'th previous start-of-word. If the optional N argument is not specified, it is assumed to be one (in which case, if the cursor is in the middle of a word the effect is just to delete to the start of that word).

DeleteNextWord
--------------

Syntax: DeleteNextWord [N]

Abbreviation: DNW

deletes text from the current position to the N'th next end-of-word If the optional N argument is not specified, it is assumed to be one (in which case, if the cursor is in the middle of a word the effect is just to delete to the end of that word).

Backspace
---------

Syntax: Backspace [N]

Abbreviation: BS

acts like DeleteChar, but moves the cursor to the left before deleting each character.

InsertLine
----------

Syntax: InsertLine [N]

Abbreviation: IL

inserts N lines at the current cursor position, breaking the current line. If the optional N argument is not specified, it is assumed to be one.

DeleteLine
----------

Syntax: DeleteLine [N]

Abbreviation: DL

deletes N lines starting from the current cursor position, putting the last one in the temporary buffer, from which it can be undeleted. See UndelLine. If the optional N argument is not specified, it is assumed to be one. Note that this action is in no way inverse with respect to InsertLine.

DeleteEOL
---------

Syntax: DeleteEOL

Abbreviation: DE

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

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

Support Commands
================

These commands perform miscellaneous useful actions. In particular, they provide access to the shell and a way to assign the functionality of Escape to another key.

About
-----

Syntax: About

Abbreviation: About

displays the copyright splash screen and places a simple information line containing the version and build date of ne on the status bar. Press any key to dismiss this screen.

Alert
-----

Syntax: Alert

Abbreviation: AL

beeps or flashes, depending on the value of the visual bell flag.

Beep
----

Syntax: Beep

Abbreviation: BE

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

Exec
----

Syntax: Exec

Abbreviation: EX

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

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

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

Flash
-----

Syntax: Flash

Abbreviation: FL

acts as Beep, but interchanging the words ``beep'' and ``flash''. Same comments apply. See Beep.

Help
----

Syntax: Help [NAME]

Abbreviation: H

displays some help about the command NAME (both the short and the long versions of the command names 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 Return, the command list will be displayed again. If you press f1 or Escape, you will return to normal editing.

Invocations of the Help command are never registered while recording macros so that you can safely access the help system while recording. See Record.

NOP
---

Syntax: NOP

Abbreviation: NOP

does nothing. Mainly useful for inhibiting standard key bindings.

Refresh
-------

Syntax: Refresh

Abbreviation: REF

refreshes the display. Refresh is very important, and should preferably be bound to the 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.

Refresh has the side effect of checking to see if your window size has changed, and will modify the display to take that into account.

Suspend
-------

Syntax: Suspend

Abbreviation: SU

suspends ne and returns you to a shell prompt; usually, the shell command fg is used to resume ne.

System
------

Syntax: System [COMMAND]

Abbreviation: SYS

asks the shell to execute COMMAND. The terminal is temporarily reset to the state it was in before ne's activation, and COMMAND is started. When the execution is finished, control returns to ne.

If the optional argument COMMAND is not specified, you can enter it on the input line.

Escape
------

Syntax: Escape

Abbreviation: ESC

toggles the menus on and off, 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. See Record.

KeyCode
-------

Syntax: KeyCode [K]

Abbreviation: KC

prompts you to press a key, and reports on the status bar the key code ne associates with that key, the command currently associated with that key code, as well as the input class for that key code. Input class codes are: ALPHA, COMMAND, RETURN, TAB, IGNORE, and INVALID. This can be useful while configuring your ~/.ne/.keys file.

If the optional integer K (between 0 and 511) is given, KeyCode uses K as the key code and displays the information described above. K can be either decimal, hexadecimal if preceded by '0x', or octal if preceded by '0'.

NameConvert
-----------

Syntax: NameConvert [0|1]

Abbreviation: NC

converts the current document's name between relative and absolute path names. With no parameter it switches the current name from relative to absolute, or absolute to relative. With 1 it converts the relative path to absolute or leaves the absolute path unchanged. With 0 it converts the absolute path to relative or leaves the relative path unchanged.

Configuration
*************

In this chapter we shall see how the menus and the key bindings of ne can be completely configured. Note that menu and key configuration is parsed at startup time, and cannot be changed during the execution of the program. This is a chosen limitation.

We will also see how to override incorrect or missing file name extensions by comparing the contents of documents to patterns to determine virtual extensions.

Key Bindings
============

ne allows you to associate any keystroke with any command. These associations are referred to as key bindings. You define your key bindings in a (possibly UTF-8) file named .keys in your ~/.ne directory. You could additionally create a .keys file in your current directory, any your system administrator might also place a .keys file in your system's global directory. These will always be loaded each time you start ne, but you can also create key binding files with the same base name (.keys) followed by a dash and some string. Such a file will only be loaded when the string matches the value of your TERM environment variable. For example, you might have files named ~/.ne/.keys, ~/.ne/.keys-xterm, and ~/.ne/.keys-vt102. The first file's key bindings will always be loaded, while at most one of the latter two files will be loaded, depending on your TERM environment variable.

You can change your key binding files' default base name from .keys by passing an argument to the --keys option when you start ne, and you can prevent any configuration from being loaded with the --no-config option (see Arguments).

The format of key binding files is simple: each line starting with the KEY sequence of capital characters is considered the description of a key binding. Each line starting with SEQ binds a character sequence to a key. All other lines are considered comments. The format of a key binding description is

     KEY HEXCODE COMMAND

The HEXCODE value is the ASCII code of the keystroke. (For special keys such as Insert or function keys, you should take a look at the file default.keys that comes with ne's distribution: it contains a complete, commented definition of ne's standard bindings that you can modify with a trial-and-error approach.) The easiest way to see the code ne uses for a given key is by using the KeyCode command. It prompts you to press a key, then reports the code for that key on the status bar. It also displays the command bound to that key if there is one.

You can write just the hexadecimal digits, nothing else is necessary (but a prefixing 0x is tolerated).  For instance,

     KEY 1 MoveSOL

binds to Control-A the action of moving to the start of a line, while

     KEY 101 LineUp

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

COMMAND can be any ne command, including Escape (which allows reconfiguring the menu activator) and Macro, which allows binding 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. See Macro.

Note that you cannot ever redefine Return or 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.

Besides the ``standard'' combinations (e.g., Control-LETTER), it possible to program combinations based on the Meta key (a.k.a. Alt). The situation in this case is a bit more involved, because depending on the terminal emulator you are using, the effect of the Meta key can be widely different. For instance, xterm raises the eighth bit of a character, so, for instance,

     KEY 81 MoveSOF

binds Control-Meta-a to the action of moving to the start of the document. However, gnome-terminal will emit the character of ASCII code 1 prefixed with ESC instead (``\x1b\x01''). To handle this case, ne provides codes from 180 on for simulated Meta sequences: for instance,

     KEY 181 MoveSOF

binds the abovementioned sequence to the same action as before. In general, the code 180+X corresponds to the sequence ESC followed by the ASCII character of code X. Note that some of these sequences may be disabled, if they conflict with existing sequences of your terminal (for instance, ESC followed by O is always disabled because it prefixes several built-in keyboard sequences).

As a final note, we remark that typing Meta-a on gnome-terminal will produce an ESC followed by a (``\x1ba''). Since it is obviously easier to press just Meta rather than Meta and Control at the same time, it is a good idea to associate the same sequence also to this combination, using

     KEY 1E1 MoveSOF

Moreover, this setting provides the user with a second choice: one can press Escape followed by a letter instead of using modifiers.

This is the approach used by default in ne: this way, Control with Meta plus a letter should always work, and Meta should work sometimes (of course, if you're sure to use always the same kind of emulator you can bind more features). Again, the best place to look is the default.keys file.

As stated above, each line starting with SEQ binds a character sequence to a key code. The format for a SEQ binding is

     SEQ "SEQUENCE" HEXCODE

where "SEQUENCE" is a double-quoted string of characters (which can include escaped hexadecimals) followed by a hexadecimal key code as described above for KEY definitions.

You should rarely need this, as properly configured systems already do this for most keys. However, some key combinations (Control in conjunction with cursor keys for example) are usually not defined. If you know the character sequence your system generates for such a combination, you may use SEQ to bind that sequence to a particular key code if that sequence isn't already defined on your system. For example, Control-``cursor-left'' may generate the sequence \x1b[1;5D. The following lines bind that sequence to the f10 key code 14A, then bind that key code to the HELP command.

     SEQ  "\x1b[1;5D"  14A
     KEY  14A          HELP

Sequences are inherently terminal- or terminal emulator-specific, so their utility will vary depending on how many emulators you use. At least they give you the possibility to use keys or key combinations that aren't covered by curses.

The key binding file is parsed at startup. If something does not work, ne exits displaying an error message. If you want ne to skip parsing the key binding file (for instance, to correct the broken file), just give ne the --no-config argument. See Arguments.

Changing Menus
==============

ne allows you to change the contents of its menus. To accomplish this task, you have to create a file named .menus in your home directory, or in ~/.ne. You can change the default name (possibly specifying a complete path) using the --menus argument (see Arguments).

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

     MENU "File"
     ITEM "Open...     ^O" Open
     ITEM "Close         " Close
     ITEM "DoIt          " Macro DoIt

In other words: a line of this form

     MENU "TITLE"

will start the definition of a new menu, having the given title. Each line of the form

     ITEM "TEXT" COMMAND

will then define a menu item, and associate the given command to it.

Any number of menus can be accommodated, but you should consider that many terminals are 80 columns wide. There is also a minor restriction on the items---their width has to be constant throughout each menu (but different menus can have different widths). 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.

Warning: the description of key bindings in menus (^O in the previous example) is very important for the beginner; there is no relation inside ne about what you say in the menu and how you configure the key bindings (see Key Bindings). Please do not say things in the menus that are not true in the key binding file.

The menu configuration file is parsed at startup. If something does not work, ne exits displaying an error message. If you want ne to skip the menu configuration phase (for instance, to correct the broken file), just give ne the --no-config argument. See Arguments.

Virtual Extensions
==================

When a document is loaded or saved under a different name, ne may examine the contents of the document to determine whether to ignore the corresponding file's actual or missing extension and use instead a virtual extension. This affects which AutoPrefs and Syntax settings ne applies to the document.

The document's contents are matched against the regular expressions (see Regular Expressions) you include in your ~/.ne/.extensions file. (There may also be an extensions file (no leading .) in the global directory.) If ne finds a match it will act as if the document's name had the corresponding extension.

Note that by default ne does not override a file's given extension. However, you can specify any number of extensions that you would like to allow to be overridden by including lines in your ~/.ne/extensions containing only a dot followed by a single extension or shell ``glob pattern''. In particular, ``.*'' would allow overriding all extensions.

Here's an example ~/.ne/.extensions file:

     # The following patterns match some common command interpreters.
     # They must match on the first line.
      sh   1  ^#!\s*/.*\b(bash|sh|ksh|zsh)\s*
      csh  1  ^#!\s*/.*\b(csh|tcsh)\s*
      pl   1  ^#!\s*/.*\bperl\b
      py   1  ^#!\s*/.*\bpython[0-9]*\s*
      rb   1  ^#!\s*/.*\bruby\s*
      xml  1  ^<\?xml
     # These must match in the first 30 and 1000 lines, respectively.
      yaml   30  ^---$
      ini  1000i ^\[\s*(\w|[.-])+\s*\]\s*$
     # You must list the existing extensions you wish to override, one
     # per line. Shell glob patterns are allowed. Note that ".*" would
     # allow overriding any extension. (Think before you do that!)
     .conf
     .tx[0-9]

The only lines which matter consist of a space-delimited set of
  extension   number   regular_expression
or a single . followed by a glob pattern. Anything else is treated as a comment. The number must be a positive integer indicating the maximum line number of the document in which the corresponding regular expression must match. The exception is zero, which allows a match on any line in the document. (Actually, ne restricts the examined portion of the document to the first 1,000,000 bytes.) If the number has a lower-case i suffix (see the ini example above), the corresponding regular expression is not case sensitive. Trailing spaces are not included as part of the regular_expression.

Only the last instance of any extension specification is considered. This allows you to override any specifications from the global extensions file. If you really need two different patterns, join them into one by concatenating them with a | like so:
  foo  1000i  (pattern_A)|(pattern_B)

Hints and Tricks
****************

Use f1 or Escape-Escape, not 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 Escape key for about a second after the actual key press (see EscapeTime). This means that you will experience annoying delays when using menus. If you have no f1 key, use Escape-Escape, or redefine a keystroke assigning the command Escape, and you will be able to use that keystroke instead of Escape. Unfortunately, some GUI-based terminals (most notably, gnome-terminal) use f1 for their own purposes; in that case, you can assign the Escape command to another key (see Configuration).

Check for the presence of a Meta key.
     If your system has a standard Meta or Alt key, there is a good chance that you have several other shortcuts. If the built-in Meta bindings do not work, you must discover which is the effect of the Meta in your terminal emulator. Indeed, it is possible in theory to configure about 150 shortcuts. See Configuration. In any case, prefixing a key with Escape has the same effect as holding down Meta, so with the standard key bindings you can, for instance, advance by word with Escape followed by F.

When editing very large files, please use the --no-syntax option.
     Even if ne will switch transparently to memory-mapped disk files, syntax highlighting requires a great deal of additional memory.

Mac users should turn on ``Delete sends CTRL-H'' in the Terminal settings.
     If you are a Mac user, you need to check the ``Delete sends CTRL-H'' option in the Advanced tab of the Terminal application settings.

ne does tilde expansion.
     When you have to specify a file name, you can always start with ~/ in order to specify your home directory, or ~USER/ to specify the home directory of another user.

It is easy to correct bad colors.
     Sometimes, due to different opinions about the best default foreground and background colors, some of the color choices in a syntax file might be unreadable (for instance, dim white on a terminal with a white background). Just copy the guilty syntax specification file to the ~/.ne/syntax directory, and change the color names at the start of the file.

Use the tabs syntax to distinguish TABs from SPACEs.
     When you're struggling to clean up a mix of TABs and SPACEs, temporarily switching to the tabs syntax may help. The command Syntax tabs makes TAB characters show up in a different background color from SPACEs. Once you've gotten your white space issues straightened out, you can switch back to the syntax appropriate for your current file type.

ne does interactive filename completion.
     When you have to specify a file name as last element of a long input, you can invoke the completer using Tab. If you hit it twice in a row, you will enter the file requester, where you can navigate and escape back to the command line, either with f1, which will let you edit again your previous input, or with Tab, which will copy your current selection over your previous file name. In other words, you can freely alternate completion, editing and browsing.

Disable the status bar for slow connections.
     ne tries to emit as few characters as possible when updating the screen. However, for each key you type it is likely that the status bar has to be updated. If your connection is very slow, you can disable the status bar to get a quicker response (see StatusBar).

The Escape delay when activating menus can be avoided.
     If you press after Escape any key that does not produce the second character of an escape sequence, ne will immediately recognize the Escape key code as such. Since non-alphabetical keys have no effect while browsing through the menus, if you're forced to use Escape as menu activator you can press, for instance, , just after it to speed up the menu activation (note that : would not work, because it would activate the command line). Alternatively, you can just type Escape twice in a row.

Use turbo mode for lengthy operations.
     Turbo mode (see Turbo) allows performing very complex operations without updating the screen until the operations are complete. This can be a major plus if you are editing very long files, or if your terminal is slow. If the default value (0, which means twice the number of visible rows) does not give you the best results, experiment other values.

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 \N convention. But remember always that regular expressions are much slower than a normal search: in particular, if you use them on a UTF-8 text, ne has to transform them into an equivalent (but more complex) expression that cannot match partially a UTF-8 sequence, and this expansion makes the search even slower.

Use the correct 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 MoveEOW command, which guarantee a correct behaviour in all situations.

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

If some keystrokes do not work, check for system-specific features.
     Sometimes it can happen that a keystroke does not work---for instance, Control-O does not open a file. This usually is due to the kernel tracking that key for its purposes. For instance, along a telnet connection with xon/xoff flow control, Control-S and 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 BSD-like systems feature a delayed suspend signal that is not in the POSIX standard, and thus cannot be disabled by ne. On HP-UX, the command stty dsusp ^- would disable the signal, and would let the control sequence previously assigned to it to run up to ne.

Motivations and Design
**********************

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

The design goal of ne was to write an editor that is easy to use at first sight, powerful, and completely configurable. Making ne run on any terminal that vi could handle was also a basic issue, because there is no use getting accustomed to a new tool if you cannot use it when you really need it. Finally, using resources sparingly was considered essential.

ne has no concept of mode. All shortcuts are defined by a single key, possibly with a modifier (such as Control or 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  user interface. The same can be said about the input line, because it is always preceded by a (possibly highlighted) prompt ending with a colon.

ne has no sophisticated visual updating system similar to, for instance, the one of curses. All updating is done while manipulating the text, and only if the turbo flag is set can some iterated operations delay the update. (In this case, ne keeps track in a very rough way of the part of the screen that 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 reasonably fast connections, the responsiveness of the editor is greatly enhanced by the direct update. And since we update the screen in parallel with the internal representation, we can exploit our knowledge to output a very small number of characters per modification. As it is typical in ne, when such design tradeoffs arise, preference is given to the solution that is effective on a good part of the existing hardware and will be very effective on most future hardware.

ne uses a particular scheme for handling text. There is a doubly linked list of line descriptors that 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 ne keeps track just of the first and of the last character used. A character is free iff it contains a null, so there is no need for a list of free chunks. The point is that the free characters lying between that first and the last used characters (the lost characters) can only be allocated locally: whenever a line has to grow in length, 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.

ne takes the POSIX standard as the basis for UN*X compatibility. The fact that this standard has been designed by a worldwide recognized and impartial organization such as IEEE makes it in my opinion the most interesting effort in its league. No attempt is made to support ten thousand 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 ANSI C (C99) compiler is assumed.

If the system has a terminfo database and the related functions (which are usually contained in the curses library), ne will use them. The need for a terminal capability database is clear, and the choice of terminfo (with respect to termcap) is compulsory if you want to support a series of features (such as more than ten function keys) that termcap lacks. If terminfo is not available, ne can use a termcap database, or, as a last resort, a built-in set of ANSI control sequences. Some details about this can be found in Portability Problems.

ne does not allow redefinition of the Escape, Tab or Return keys, nor of the interrupt character Control-\. This decision has been made mainly for two reasons. First of all, it is necessary to keep a user from transforming ne's bindings to such a point that another unaware user cannot work with it. These two keys and the alphabetic keys allow activating 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 Escape key usage should generally be avoided. The reason is that most escape sequences that are produced by special keys start with the escape character. When Escape is pressed, ne has to wait for one second (this timing can be changed with the EscapeTime command), 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 :, or by Escape, again.  See Hints and Tricks.

Note that, as has been stated several times, the custom key bindings also work when doing a long input, navigating through the menus or browsing the requester. However, this is only partially true. To keep the code size and complexity down, in these cases ne recognizes only direct bindings to commands, and discards the arguments. Thus, for instance, if a key is bound to the command line LineUp 2, it will act like LineUp, while a binding to Macro MoveItUp would produce no result. Of course full binding capability is available while writing text. (This limitation will probably be lifted in a future version: presently it does not seem to limit seriously the configurability of ne.)

ne has some restrictions in its terminal handling. It does not support highlighting on terminals that use a magic cookie. Supporting such terminals correctly 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 that specify a file to print or a program to launch in order to initialize the terminal.

The macro capabilities of ne are rather limited. For instance, you cannot give an argument to a macro: macros are simply sequences of commands that can be played back automatically. This makes them very useful for everyday use in a learn/play context, but rather inflexible for extending the capabilities of the editor.

ne has been written with sparing resource use as a basic goal. Every possible effort has been made to reduce the use of CPU time and memory, the number of system calls, and the number of characters output to the terminal. 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 emacs. The update of files using syntax highlighting is as lazy as possible: modifications cause just the update of the current line, and the rest of the screen is updated only when you move away. The search algorithm is a simplified version of the Boyer-Moore algorithm that provides high performance with a minimal setup time. An effort has been taken to move to the text segment all data that do not change during the program execution. When the status bar is switched off, additional optimizations reduce the cursor movement to a minimum.

A word should be said about lists. Clearly, handling the text as a single block with an insertion gap (a la emacs) allows you to gain some memory. However, the management of the text as a linked list requires much less 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.

The Encoding Mess
*****************

ne supports UTF-8. It can use UTF-8 for its input/output, and it can also interpret one or more documents as containing UTF-8 encoded text, acting accordingly. Note that the document content is actual UTF-8 text---ne does not use wide characters. As a positive side-effect, ne can support fully the ISO-10646 standard, but nonetheless non-UTF-8 texts occupy exactly one byte per character.

More precisely, any piece of text in ne is classified as US-ASCII, 8-bit or UTF-8. A US-ASCII text contains only US-ASCII characters. An 8-bit text sports a one-to-one correspondence between characters and bytes, whereas an UTF-8 text is interpreted in UTF-8.  Of course, this raises a difficult question: when should a document be classified as UTF-8?

Character encodings are a mess. There is nothing we can do to change this fact, as character encodings are metadata that modify data semantics. The same file may represent different texts of different lengths when interpreted with different encodings. Thus, there is no safe way of guessing the encoding of a file.

ne stays on the safe side: it will never try to convert a file from an encoding to another one. It can, however, interpret data contained in a document depending on an encoding: in other words, encodings are truly treated as metadata. You can switch off UTF-8 at any time, and see the same document as a standard 8-bit file.

Moreover, ne uses a lazy approach to the problem: first of all, unless the UTF-8 automatic detection flag is set (see UTF8Auto), no attempt is ever made to consider a file as UTF-8 encoded.  Every file, clip, command line, etc., is firstly scanned for non-US-ASCII characters: if it is entirely made of US-ASCII characters, it is classified as US-ASCII. An US-ASCII piece of text is compatible with anything else---it may be pasted in any document, or, if it is a document, it may accept any form of text. Documents classified as US-ASCII are distinguished by an A on the status bar.

As soon as a user action forces a choice of encoding (e.g., an accented character is typed, or an UTF-8-encoded clip is pasted), ne fixes the mode to 8-bit or UTF-8 (when there is a choice, this depends on the value of the UTF8Auto flag). Of course, in some cases this may be impossible, and in that case an error will be reported.

All this happens behind the scenes, and it is designed so that in 99% of the cases there is no need to think of encodings. In any case, should ne's behaviour not match your needs, you can always change at run time the level of UTF-8 support.

History
*******

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

The first versions of ne were created on an Amiga 3000T, using the port of the curses library by Simon John Raybould. After switching to the lower-level terminfo library, the development continued under UN*X. Finally, I ported terminfo to the Amiga, thus making it possible to develop on that platform again. For ne 1.0, an effort has been made to provide a terminfo emulation using GNU's termcap. The development eventually moved to Linux.

Todd Lewis got involved with ne when the University of North Carolina's Chapel Hill campus migrated its central research computers from MVS to UNIX in 1995. The readily available UNIX editors had serious weaknesses in their user interfaces, especially from the standpoint of MVS users who were not too excited about having to move their projects to another platform while learning an entirely new suite of tools. ne offered an easily understood interface with enough capabilities to keep these new UNIX users productive. Todd installed and has maintained ne at UNC since then, making several improvements to the code to meet his users' needs. In early 1999 his code base and mine were merged to become version 1.17.

Support for syntax highlighting was added in 2009 with code and techniques heavily borrowed from the GNU-licensed editor joe, which was written by Joseph H. Allen. Much of the work to incorporate this code into ne was undertaken by Daniele Filaretti, an undergraduate student working under the direction of Sebastiano at the Università degli Studi di Milano.

Portability Problems
********************

This chapter is devoted to the description of the (hopefully very few) problems that could arise when porting ne to other flavors of UN*X.

The fact that only POSIX calls have been used (see Motivations and Design) should guarantee that on POSIX-compliant systems a recompilation should suffice. Unfortunately, terminfo has not been standardized by IEEE, so that different calls could be available. The necessary calls are setupterm(), tparm() and tputs(). The other terminfo functions are never used.

If terminfo is not available, the source files info2cap.c and info2cap.h map terminfo calls on termcap calls. The complete GNU termcap sources are distributed with ne, so no library at all is needed to use them. You just have to compile using one of the options explained in the makefile and in the README. Should you need comprehensive information on GNU termcap, you can find the distribution files on any ftp site that distributes the GNU archives. I should note that the GNU termcap manual is definitely the best manual ever written about terminal databases.

There are, however, some details that are not specified by POSIX, or are specified with insufficient precision. The places of the source where such details come to the light are evidenced by the PORTABILITY PROBLEM string, which is followed by a complete explanation of the problem.

For instance, there is no standard way of printing extended 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 print them in reverse video; moreover, all characters between 127 and 160 are visualized as a reversed question mark (this works particularly well with ISO Latin 1, but Windows users might not like it). This behavior can be easily changed by modifying the out() function in term.c.

Note that it is certainly possible that some system features not standardized by POSIX interfere with ne's use of the I/O stream. Such problems should be dealt with locally by using the system facilities rather than by horribly #ifdef'ing the source code. An example is given in Hints and Tricks.

Acknowledgments
***************

A lot of people contributed to this project. Part of the code comes from emacs and joe. Many people, in particular at the silab (the Milan University Computer Science Department Laboratory), helped in beta testing the first versions. Daniele Filaretti worked at the integration of syntax-highlighting code from joe. John Gabriele suggested several new features and relentlessly tested them.

Comments, complaints, desiderata are welcome.

         Sebastiano Vigna
         Via California 22
         I-20144 Milano MI
         Italia

         sebastiano.vigna@unimi.it

         Todd M. Lewis
         418 Arlington Cir.
         Sanford, NC 27330-7600
         USA

         utoddl@gmail.com

         ne home page: http://ne.di.unimi.it/
         Discuss ne at http://groups.google.com/group/niceeditor/
         Github repo: https://github.com/vigna/ne/