###Contents###
 @@@Introduction@@@
 @@@Getting Started@@@
 @@@Selecting Text@@@
 @@@Finding and Replacing Text@@@
 @@@Cutting and Pasting@@@
 @@@Using the Mouse@@@
 @@@Keyboard Shortcuts@@@
 @@@Shifting Text@@@
 @@@Language Modes@@@
 @@@Line Numbers@@@
 @@@Line Endings@@@
 @@@Character Sets and Encodings@@@
 @@@Matching Parentheses@@@
 @@@Opening Included Files@@@
 @@@Tabs vs Spaces@@@
 @@@Syntax Highlighting@@@
 @@@Using CTAGS and calltips files@@@
 @@@Bookmarks@@@
 @@@Regular expressions@@@
 @@@Shell Commands and Filters@@@
 @@@Macro Recording and Playback@@@
 @@@Customizing the Tools Menu@@@
 @@@Hook Functions@@@
 @@@Custom Keybindings@@@
 @@@The Toolbar@@@
 @@@Multiple documents and multiple views@@@
 @@@Named Instances and Configurations@@@
 @@@Crash Recovery@@@
 @@@Embedded Scripting Engine@@@
 @@@Support and Contact Information@@@
 
###Introduction###
__APP__ is a standard GUI (Graphical User Interface) style text editor for \
program source code and other plain-text files. Most of the menus, dialogs, \
mouse functions, keyboard shortcuts, and basic editing features of __APP__ should \
be familiar to users of other GUI based editors. Additionally, __APP__ has some \
features intended specifically for programmers. 

Much of __APP__'s design was inspired by the famous Nirvana editor (aka NEdit) and \
a substantial portion of this help file was adapted from NEdit's documentation, \
although internally they are quite different animals. The documentation is rather \
lengthy, and still doesn't cover everything, but hopefully whatever isn't \
discussed here should be easy enough to work out on your own.

###Getting Started###

Note: if you get into trouble, the %%%Undo%%% command in the %%%Edit%%% menu \
can reverse any  modifications that you make.  __APP__ does not change the disk file \
you are editing until you tell it to %%%Save%%%. 

%%%Editing an Existing File%%%
To open an existing file, choose %%%Open Files%%% from the %%%File%%% menu. \
Select the file that you want to open in the pop-up dialog that appears and \
click on %%%OK%%%.  To open several files at the same time, enable multi-file mode by toggling the \
%%%"M"%%% button in the upper right corner of the dialog, then hold the %%%[Ctrl]%%% key down \
while clicking on the desired files with the mouse. Note that you can manually type or paste a \
filename into the dialog when in single-file mode, but not in multi-file mode.

%%%Creating a New File%%%
If you already have an empty (Untitled) window displayed, just begin typing in \
the window.  To create a new Untitled window, choose %%%New%%% from the \
%%%File%%% menu. To give the file a name and save its contents to the disk, \
choose %%%Save%%% or %%%Save As%%% from the %%%File%%% menu. 


%%%Shortcuts%%%
As you become more familiar with __APP__, you may want to use the keystroke \
combinations shown on the right side of the menus rather than pulling down \
the menus with the mouse. 

Dialogs are also streamlined so you can enter information quickly and without \
using the mouse.  To move the keyboard focus around a dialog, use the tab \
and arrow keys, or use the %%%[Alt]%%% key in combination with one of the \
underlined accelerator keys.  Most of the dialogs can be confirmed by pressing \
%%%[Return]%%% or %%%[Enter]%%%. The %%%Cancel%%% button can usually be \
activated by pressing the %%%[Esc]%%% key. 


###Selecting Text###

To select text for copying, deleting, or replacing, press the left mouse \
button with the pointer at one end of the text you want to select, and drag \
it to the other end. The text will become highlighted. To select a whole \
word, double click (click twice quickly in succession). Similarly, you can \
select a whole line by triple clicking. Pressing %%%[Ctrl+A]%%% selects the \
whole file. After selecting, you can re-adjust a selection by holding down \
the %%%[Shift]%%% key and dragging on either end of the selection. You can \
also select text and adjust the selection by holding the %%%[Shift]%%% key \
while using the standard navigation keys (PageUp, PageDown, Home, End, and the \
Arrow keys). To delete the selected text, press %%%[Delete]%%% or backspace. \
To replace it, simply begin typing, or select %%%Paste%%% from the %%%Edit%%% \
menu to replace it with contents of the clipoard (if any).

To select a rectangle or column of text, press and hold the %%%[Ctrl]%%% key \
down ///before/// dragging the mouse. Rectangular selections can be used in \
most contexts that normal selections can be used, including cutting, pasting, \
and search/replace.

Selected text can also be moved to a new location in the file by pressing \
the left mouse button somewhere inside the selection, and  dragging the text \
to the desired location. Holding the %%%[Ctrl]%%% key while dragging the \
text will ///copy/// the selected text, leaving the original text in place.


###Finding and Replacing Text###

The %%%Find%%% and %%%Replace%%% commands from the %%%Search%%% menu present \
dialogs for entering text for searching and replacing.  These dialogs also \
allow you to choose whether you want the search to be sensitive to upper and \
lower case, or whether to use the standard Unix pattern matching characters \
(regular expressions). Searches begin at the current text insertion (caret) position. 

The %%%Find Next%%% and %%%Find Prev%%% commands repeat the last find command \
without prompting for search strings.  To selectively replace text, use \
the %%%[<]%%% and %%%[>]%%% buttons in the replace dialog to navigate between \
occurences of the text in the document, and the %%%Replace%%% button to insert \
the new text. 

The %%%Find Selected%%% menu commands search for the text contained in the \
current primary selection (see "Selecting Text").  The selected text does not \
have to be in the current editor window, it may even be in another program.  \
For example, if the word %%%dog%%% appears somewhere in a window on your \
screen, and you want to find it in the file you are editing, select the word \
dog by dragging the mouse across it, switch to your __APP__ window and choose \
%%%Next%%% from the %%%Find Selected%%% sub-menu below the %%%Search%%% menu. 

To replace all occurrences of a string within some range of text, select the \
range (see "Selecting Text"), and choose %%%Replace%%% from the %%%Search%%% \
menu, then type the string to search for and the string to substitute, and \
press the %%%All in Selected%%% button in the dialog.  Note that selecting \
text in the Replace dialog will ///unselect/// the text in the document.


###Cutting and Pasting###

The easiest way to copy and move text around in your file or between documents, \
is to use the ///clipboard///, an imaginary area that temporarily stores text \
and data.  The %%%Cut%%% command removes the selected text (see "Selecting \
Text") from your file and places it in the clipboard.  Once text is in the \
clipboard, the %%%Paste%%% command will copy it to the insert position in the \
current window.  For example, to move some text from one place to another, \
select it by dragging the mouse over it, choose %%%Cut%%% to remove it, click \
the pointer to move the insert point where you want the text inserted, then \
choose %%%Paste%%% to insert it.  The %%%Copy%%% command copies text to the \
clipboard without deleting it from your file. You can also use the clipboard \
to transfer text to and from other programs which make proper use of the \
X-clipboard. 

Another method for copying and moving text within __APP__ documents \
and between __APP__ and other programs is by clicking the middle mouse button \
to paste the primary selection (to the clicked position).  In many cases this \
may be the only way to transfer data to and from some other programs, such as \
XTerm.


###Using the Mouse###

If you don't have time to learn everything, you can get by adequately with \
just the left mouse button:  Clicking the left button moves the cursor. \
Dragging with the left button makes a selection. Dragging an existing selection \
moves the selected text to a new location. Holding the shift key while clicking \
extends the existing selection, or begins a selection between the cursor and the \
mouse.  Double or triple clicking selects a whole word or a whole line. 


###Keyboard Shortcuts###

Many of the keyboard shortcuts in __APP__ are shown on the right hand sides of \
the pull-down menus.  However, there are more which are not as obvious.  \
These include: dialog button shortcuts; menu and dialog mnemonics; labeled \
keyboard keys, such as the arrows, page-up, page-down, and home; and optional \
Shift modifiers on accelerator keys, like [Shift]Ctrl+O. 

%%%Menu Accelerators%%%
Pressing the key combinations shown on the right of the menu items is a \
shortcut for selecting the menu item with the mouse.  

%%%Menu Mnemonics%%%
Pressing the %%%[Alt]%%% key in combination with one of the underlined \
characters in the menu bar pulls down that menu.  Once the menu is pulled \
down, typing the underlined characters in a menu item (still holding the Alt \
key) activates that item.  With a menu pulled down, you can also use the \
arrow keys to select menu items, and the %%%Space%%% or %%%Enter%%% keys \
to activate them. 

%%%Keyboard Shortcuts within Dialogs%%%
Pressing the %%%[Return]%%% or %%%[Enter]%%% key in most dialogs will \
activate dialog's "default" button, which is usually the affirmative \
response to the dialog, such as %%%Yes%%% or %%%OK%%%.   Likewise, pressing \
the %%%[Esc]%%% key will activate the dialog's negative repsonse, such as \
the %%%Cancel%%% or %%%Close%%% button.

Pressing the %%%[Tab]%%% key moves the keyboard focus to the next item in a \
dialog. Within an associated group of buttons, the arrow keys move the focus \
among the buttons.  Holding the %%%[Shift]%%% key while pressing %%%[Tab]%%% \
moves backward through the items. 

Many items in dialogs have one character in their name underlined. \
Pressing the %%%[Alt]%%% key along with this character, activates a button \
as if you had pressed it with the mouse, or moves the keyboard focus to the \
associated text field or list. 

You can select items from a list by using the arrow keys to move the \
selection and space to select. 

In file selection dialogs, you can type the first character of the file \
name or directory in the list to select the first file beginning with that \
letter, and use the up and down arrow keys to move to the previous or next \
filename, respectively.

%%%Labeled Navigation Keys%%%
The labeled navigation keys on standard workstation and PC keyboards, like the \
arrows, and page-up and page-down, are active in __APP__, though not shown in \
the pull-down menus. 

Holding down the %%%[Ctrl]%%% key while pressing a navigation key extends the \
scope of the action that it performs.  For example, %%%[Home]%%% normally \
moves the insert cursor the beginning of a line.  %%%[Ctrl]+[Home]%%% moves it \
to the beginning of the file. The right arrow key moves the cursor one \
///character/// forward, holding the %%%[Ctrl]%%% down moves the cursor \
one ///word/// forward.

Holding down the %%%[Shift]%%% key while pressing a navigation key begins or \
extends a selection.  Combining the %%%[Shift]%%% and %%%[Ctrl]%%% keys \
combines their actions.  For example, to select a word without using the \
mouse, position the cursor at the beginning of the word and press \
%%%Ctrl+Shift+RightArrow%%%.  When extending the selection using the \
%%%[Shift]%%% key, the %%%[Alt]%%% key modifies the selection \
commands to make the selection rectangular. 

Under the X-Window system, there are several levels of translation between \
keyboard keys and the actions they perform in a program.  Because of all of \
this configurability, and since keyboards and standards for the meaning of \
some keys vary from machine to machine, the mappings may be changed from \
the defaults listed below. 

%%%A general overview of keyboard commands:%%%

%%%Ctrl:%%%
Extends the scope of the action that the key would otherwise perform. \
For example, %%%Home%%% normally moves the insert cursor to the beginning \
of a line. Ctrl+Home moves it to the beginning of the file. Backspace deletes \
one character, Ctrl+Backspace deletes one word.

%%%Shift:%%%
Extends the selection to the cursor position. If there's no selection, \
begins one between the old and new cursor positions.

%%%Alt:%%%
When modifying a selection, makes the selection rectangular.

%%%Esc:%%%
Cancels operation in progress: menu selection, drag, selection, etc. Also \
equivalent to cancel button in dialogs.

%%%Backspace:%%%
Delete the character before the cursor

%%%Ctrl+Backspace:%%%
Delete the word before the cursor

%%%Left Arrow:%%%
Move the cursor backward one character (or one ///word/// backward in \
combination with the %%%Ctrl%%% key).

%%%Right Arrow:%%%
Move the cursor forward one character (or one ///word/// forward in \
combination with the %%%Ctrl%%% key).

%%%Up Arrow:%%%
Move the cursor up one line. If used with the %%%Ctrl%%% key, it moves \
the scrolled viewport up one line, while retaining the current caret \
position and selection.

%%%Down Arrow:%%%
Move the cursor down one line. If used with the %%%Ctrl%%% key, it moves \
the scrolled viewport down one line, while retaining the current caret \
position and selection.

%%%Ctrl+Tab:%%%
Unconditionally inserts an ASCII tab character, without regard to the the \
current "Use Tabs" settings.

%%%Ctrl+A:%%%
Selects the entire document.

%%%Ctrl+Insert:%%%
Copy the primary selection to the clipboard (same as %%%Copy%%% menu item or \
%%%Ctrl+C%%%)

%%%Shift+Insert:%%%
Paste the primary selection to the cursor location.

%%%Delete:%%%
Delete the character before the cursor.

%%%Ctrl+Delete:%%%
Delete one word to the right of the cursor.

%%%Shift+Delete:%%%
Cut, remove the currently selected text and place it in the clipboard. \
(same as %%%Cut%%% menu item or %%%Ctrl+X%%%)

%%%Shift+Ctrl+Delete:%%%
Deletes all text from the cursor to the end of the current line.

%%%Home:%%%
Move the cursor to the beginning of the line.

%%%Ctrl+Home:%%%
Move the cursor to the beginning of the file.

%%%End:%%%
Move the cursor to the end of the line.

%%%Ctrl+End:%%%
Move the cursor to the end of the file.

%%%PageUp:%%%
Scroll and move the cursor up by one page.

%%%PageDown:%%%
Scroll and move the cursor down by one page.

%%%Ctrl+PageUp:%%%
Switch to the previous document.

%%%Ctrl+PageDown:%%%
Switch to the next document.


###Shifting Text###

While shifting blocks of text is most important for programmers, it is also \
useful for other tasks, such as creating indented paragraphs and outlines. 

To shift a block of text one space to the right, select the text, and then \
choose %%%Edit->Indent->Space Right%%% from the menu. Note that the \
accelerator keys for these menu items are %%%Ctrl+9%%% and %%%Ctrl+0%%%, which \
correspond to the right and left parenthesis on most keyboards.  You can \
remember them as adjusting the text in the direction pointed to by the \
parenthesis character.  Using the the %%%Shift%%% key in combination with \
these keyboard shortcuts will shift the text by one tab stop rather than one \
space.

Programmers who use structured languages usually prefer some form of \
automatic indentation, so that they don't have to continually re-type the sequences \
of tabs and/or spaces needed to maintain lengthy running indents.  __APP__  offers \
two types of auto-indent: the "basic" type, which simply lines up the cursor position with \
the previous line; and a slightly more sophisticated "smart" version, described below. \
You can select the desired behavior by using the %%%Auto indent%%% option under \
the %%%editor%%% tab of the %%%Preferences%%% dialog.

The "smart" indent option adds a further level of indentation when you press ENTER immediately \
after typing an opening brace '%%%{%%%', and also un-indents back to the previous level as soon \
as you type the corresponding closing brace '%%%}%%%'.  If you position the cursor directly \
between a set of consecutive opening/closing braces %%%{}%%% and press ENTER, the editor \
will format the braces into a typical "block" style indentation, and will position the cursor \
so you are ready to begin filling in the block.


###Language Modes###

When __APP__ initially reads a file, it attempts to determine whether the file \
is in one of the computer languages that it knows about.  Knowing what \
language a file is written in allows __APP__ to assign highlight patterns. \
Language mode can be recognized from both the file name and from the \
"shbang" marker at the beginning of the file, for instance a file beginning \
with  === #!/usr/bin/perl ===  is recognized as a perl script.  Language mode \
recognition and language-specific preferences are configured under the \
%%%Syntax%%% tab of the %%%Edit->Preferences%%% dialog.

You can also set the language mode manually for a document, by selecting it \
from the %%%View->Language%%% menu. 


###Line Numbers###

To find a particular line in a source file by line number, choose %%%Go To%%% \
from the %%%Search%%% menu.  You can also select some line number text in \
an external application (such as a compiler or debugger running in a terminal \
window) and choose %%%Go to selected%%% from the %%%Search%%% menu. 

To find out the line number of a particular line in your file, turn on the \
%%%Status bar%%% option from the %%%View%%% menu. The status bar continuously \
updates the line number of the line containing the cursor. You can also have \
__APP__ display the line numbers in the left-hand margin of the document by \
checking the %%%Line numbers%%% option in the %%%View%%% menu.

To go to a specific column on a given line, choose %%%Go to%%% from the \
%%%Search%%% menu and enter a line number. You can also enter a line number and a \
column number separated by a colon or comma.  (e.g. Enter "100:12" for line 100 column 12.)

When you double-click an item in the ///output pane/// that contains properly \
formatted filename and line number information, __APP__ will try to parse the \
message line, and jump to that position in the specified file, opening that \
file if required. (You can also do this with the "%%%Search->Go to error%%%" menu.) \
  By default, the regular expressions used to match the filename and line number should work \
for error messages produced by ===gcc=== and other programs with similar output. You can also \
define your own expressions to match the output of other tools by editing the list found under:
%%%Edit->Preferences->general->Output pane line matching%%%.

(See the section on ///Shell Commands and Filters/// for more \
information on capturing the output of external programs.)



###Line Endings###

__APP__ provides transparent support for Unix (===LF===); DOS (===CR/LF===); and Macintosh (===CR===); text file \
formats. Whenever you open one of these files, __APP__ will try to detect the format, and any new line endings will \
be inserted accordingly. If you copy text in a different from another document or application and paste it \
into __APP__, the line endings are automatically translated into the current format. Note that this automatic \
translation also works for middle-click pasting from the X11 clipboard, but might not work for text \
dragged from another application and dropped into the current document (which is generally an awkward \
thing to do anyway). 

When you create a new document __APP__ will default to the operating system's native format (===LF=== for Unix-style \
systems or ===CR/LF=== for MS-Windows) but you can change the default format for new files from the \
%%%Default file format%%% option on the %%%editor%%% tab of the %%%Preferences%%% dialog. You can also \
transform the line endings in the current document into a different format from the %%%Edit->File Format%%% menu.


###Character Sets and Encodings###

When you open a file in __APP__, it first scans the file's contents and tries to determine \
if the file is encoded as UTF-8.   If the encoding cannot be determined, it consults the settings \
under:
  %%%Edit->Preferences->editor%%%

For new files, empty files, or files whose encoding is ambiguous (i.e. files that contain \
only 7-bit character codes) the file may be treated as either UTF-8 or plain ASCII, \
depending on the setting of:
  %%%[x] Open 7-bit ASCII files as UTF-8%%%

For binary files, extended single-byte encodings, or invalid UTF-8, you can force such \
files to be treated as UTF-8 by setting:
  %%%[x] Treat other files as broken UTF-8%%%
(You will probably never want to enable this option, unless you encounter a corrupted UTF-8 \
file, or you just want to test the compliance of the UTF-8 handler on a deliberately broken file.)

Note that __APP__ does not provide any sort of "on the fly" conversion between encodings, so if you want to \
work with an extended ASCII file as if it were UTF-8 encoded, you will need to convert the file using an \
external tool such as the "===iconv===" program before opening it in __APP__. 

If you paste plain-text data that contains character codes which are not valid UTF-8 into a UTF-8 encoded document, \
__APP__ will try to convert the data to UTF-8 before inserting it into the document. But it will not attempt to \
convert UTF-8 encoded data into plain text, so pasting operations between different encodings may produce unexpected \
results when the current document is in ASCII mode. 

Inserting text of mismatched encodings from the %%%File->Insert file%%% menu or the scripting engine's text functions \
are also likely to produce undesirable results.


###Matching Parentheses###

To help you inspect nested parentheses, brackets, and braces, __APP__ has an \
automatic bracket-matching mode. When you type, or move the cursor directly \
///after/// an "opening" character or directly ///before/// a "closing" \
character, it highlights both the opening and closing characters in green. \
If no matching character can be found, it highlights the mismatched \
parenthesis, bracket, or brace in red. These colors can be changed by \
editing the %%%bracelight%%% and %%%bracebad%%% styles under the %%%Syntax%%% \
tab of the %%%Preferences%%% dialog, or you can disable bracket-matching \
completely by unchecking the "Highlight matching braces" option under \
the %%%Editor%%% tab.

When syntax highlighting is enabled, the matching routines make use of the \
syntax information for improved accuracy. In that case, a brace inside a \
highlighted string will not match a brace inside a comment, for instance. 


###Opening Included Files###

The %%%Open Selected%%% command in the %%%File%%% menu can be used to open \
a file whose name is mentioned in the current document, or selected in an \
external application. In cases where the exact location of the file is not \
obvious, __APP__ uses some heuristics to try and find the file:

On X11 platforms, the primary X selection is queried first.  If it contains the \
name of an existing file, that filename will be used.  In this case, the filename \
must either be an absolute path, or a path relative to the current working directory.  \
If the selection text does not contain the name of an existing file, it is ignored \
and the current document is queried instead.

If any text is selected in the current document, that text is assumed to be the \
name of the file you want to open.  If no text is currently selected, __APP__ will \
try to deduce a filename from the text at the current postion.

If the current document is using a C or C++ based lexer, the file will be searched \
for as if it were an ===#include=== file.  If the selected (or inferred) \
text is enclosed in angle brackets ===<>=== the system include directories will be searched \
first, otherwise __APP__ searches first in the same directory as the current file, \
then in the current working directory, then in the system directories.  You can also \
add additional search paths \
using the dialog:
  %%%Edit->Preferences->general->System header locations%%%

For documents other than C or C++ files, the working directory is searched first, \
followed by the directory containing the active document.

Finally, a filename specification in the form of ===FILENAME:NN=== \
will open ===FILENAME=== to line number ===NN===.


###Tabs vs Spaces###

Tabs are important for programming in languages which use indentation to show \
nesting, as short-hand for producing white-space for leading indents.  As a \
programmer, you have to decide how to use indentation, and how or whether tab \
characters map to your indentation scheme.

Ideally, tab characters map directly to the amount of indent that you use to \
distinguish nesting levels in your code.  Unfortunately, the Unix standard for \
interpretation of tab characters is eight characters (probably dating back to \
mechanical capabilities of the original teletype), which is usually too coarse \
for a single indent. __APP__ allows you to change the interpretation of the tab \
character by setting the hardware tab distance in %%%Edit->Preferences->\
Editor->Tab Width%%%. 

Changing the meaning of the tab character makes programming much easier while \
you're in the editor, but can cause you headaches outside of the editor, \
because there is no universal way to pass along the tab setting as part of a \
plain-text file.  Other tools which display, print, and otherwise process your \
source code might have a different notion of how the tabs are set, and might \
not be able to handle the change.  Non-standard tabs can also confuse other \
programmers, or make editing your code difficult for them if their text \
editors don't support changes in tab distance. 

Because of these limitations, some programming styles prefer not use ANY tab \
characters at all, and use only single-width space characters for indentation. \
To enable this behavior globally in __APP__, un-check the %%%"Use tabs for \
indent"%%% option under the %%%editor%%% panel of the %%%Preferences%%% \
dialog. It is also possible to tweak this setting on a per-language basis by \
adjusting the setting of %%%Use tabs%%% for a specific language under \
the %%%syntax%%% panel of the %%%Preferences%%% dialog. If you set this option \
to %%%"detect from content"%%% for a particular language, it will only use \
tabs for that language when you open a document that contains lines beginning \
with tabs, otherwise, it will fall back to your default setting. To enter a \
real tab character even when %%%Use tabs%%% is disabled, use %%%Ctrl+Tab%%%. 


###Syntax Highlighting###

Syntax Highlighting means using colors and fonts to help distinguish language \
elements in programming languages and other types of structured files. \
Programmers use syntax highlighting to understand code faster and better, and \
to spot many kinds of syntax errors more quickly. 

If __APP__ recognizes the computer language that you are using, it will highlight \
your text, and maintain the highlighting, automatically, as you type. If __APP__ \
doesn't correctly recognize the type of the file you are editing, you can \
manually select a language mode from the %%%Language%%% categories listed \
under the %%%View%%% menu.  You can also adjust the filenames that __APP__ \
associates with a particular language under the %%%syntax%%% tab of the \
%%%Preferences%%% dialog.

All of the lexical analyzers that __APP__ uses for highlighting are hard-coded \
into the application. Although this generally provides better performance and \
more precise parsing than regex-based pattern matching, unfortunately it also \
means that there is currently no way to define a new language without writing \
a new Scintilla lexer and re-compiling __APP__ itself. 

You can, however, adjust the sets of keywords for a particular language by \
editing the %%%keywords%%% lists under the %%%syntax%%% tab of the \
%%%Preferences%%% dialog. This dialog also allows you to change the colors \
and font attributes for the various styles used by a particular language. \
To toggle the italic or bold attributes, click the %%%"S"%%% or %%%"B"%%% \
buttons (resp) next to that style. To change the foreground or backgound \
color for a style, double-click the %%%FG/BG%%% color wells next to the \
style, or drag-and-drop a color from another style, or from one of the \
pre-set color wells shown at the bottom of the dialog.

To turn off syntax highlighting for the active document, select:
%%%View->Languages->Other->none%%%



###Using CTAGS and calltips files###

__APP__ can process tags files generated using the Exuberant Ctags program. \
Ctags creates index files correlating names of functions and declarations with \
their locations in the source code files for various languages including C, \
Fortran, or Pascal. (See the ctags manual page for more information).  Ctags \
produces a file (usually named "tags") which can be loaded by __APP__.  __APP__ can \
manage any number of tags files simultaneously.  Tag collisions are handled \
with a popup list to let the user decide which tag to use. Once loaded, the \
information in the tags file enables __APP__ to jump directly to the declaration \
of a highlighted function or data structure name with a single command.  To \
load a tags file, select %%%"Load Tags File"%%% from the %%%File%%% menu and \
choose a tags file to load, or specify the name of the tags file on the \
__APP__ command line: 

===    __EXE__ -t tags ===


To unload a tags file, select %%%"Unload Tags File"%%% from the %%%File%%% \
menu and choose from the list of tags files.  Note that __APP__ re-reads the tag \
files each time it needs to find a tag defnition. This can cause some slowdown \
when accessing huge tag files, but it has the advantage of keeping the tags \
up to date even when the tags file changes, and it also means that __APP__ does \
not need to constantly maintain an in-memory cache of the tag data.

To find the definition of a function or data structure once a tags file is \
loaded, select the name anywhere it appears in your program (see "Selecting \
Text") and choose %%%"Find Definition"%%% from the Search menu.

Calltips are little yellow boxes that pop up to remind you what the arguments \
and return type of a function are.  To display a calltip from the information \
contained in the tag files, select some text and choose %%%"Show Calltip"%%% \
from the %%%Search%%% menu.  To kill a displayed calltip, press the \
%%%[Esc]%%% key. 

__APP__ can acquire its calltip information from two different types of files: the CTAGS \
file described above, and its own "calltips" file format. The calltips files can be \
loaded and unloaded in the same way as tags files. \
The __APP__ calltips file format is extremely simple. The file is organized in blocks \
of lines, with each block separated by a single blank line. The first line of a block \
is the function name only, with no whitespace or parenthesis. The remaining line(s) \
in the block form the actual text displayed in the calltip. Note that only the \
first matching function name in the file is returned, but a block with multiple lines \
can be used for displaying overloaded function signatures. 

If a function appears in more than one file, the tip texts are concatenated into a single tip. \
In order to determine which format a file is in, the parser looks at the first few bytes of \
the file - tags files must begin with the string ==="!_TAG_FILE_FORMAT"=== - \
calltips files must ///not/// begin with that text!


###Bookmarks###

Many other popular editors have an advanced "bookmarking" system that allows you \
to assign several bookmarks at various locations in your documents, and then you \
can try to remember which bookmark is which when you want to return to some location.

But usually I just want to jump to another spot for a moment, and then return right back \
to where I was. That's all, nothing complicated - no names, no numbers. Because of this, \
__APP__ has a somewhat elementary approach to bookmarking - select %%%Search->Bookmark->Set%%% \
to mark your current location, then go wherever you want. When you are ready to return to \
your original location, select %%%Search->Bookmark->Return%%%.


###Regular expressions###

Regular expressions (regex's) are useful as a way to match inexact sequences \
of characters.  They can be used in the %%%Find%%% and %%%Replace%%% search \
dialogs.

A regex is a specification of a pattern to be matched in the searched text. \
This pattern consists of a sequence of tokens, each being able to match a \
single character or a sequence of characters in the text, or assert that a \
specific position within the text has been reached (the latter is called an \
anchor.)  Tokens (also called atoms) can be modified by adding one of a number \
of special quantifier tokens immediately after the token.  A quantifier token \
specifies how many times the previous token must be matched (see below.) 

Tokens can be grouped together using one of a number of grouping constructs, \
the most common being plain parentheses.  Tokens that are grouped in this way \
are also collectively considered to be a regex atom, since this new larger \
atom may also be modified by a quantifier. 

A regex can also be organized into a list of alternatives by separating each \
alternative with pipe characters, `|'.  This is called ///alternation///.  A match \
will be attempted for each alternative listed, in the order specified, until a \
match results or the list of alternatives is exhausted (see Alternation \
section below.) 


%%%The 'Any' Character%%%

If a dot (`.') appears in a regex, it means to match any character exactly \
once.  By default, dot will not match a newline character, but this behavior \
can be changed (see help topic Parenthetical Constructs, under the \
heading, Matching Newlines). 


%%%Character Classes%%%

A character class, or range, matches exactly one character of text, but the \
candidates for matching are limited to those specified by the class.  Classes \
come in two flavors as described below: \

     [...]   Regular class, match only characters listed.
     [^...]  Negated class, match only characters NOT listed.

As with the dot token, by default negated character classes do not match \
newline, but can be made to do so. 

The characters that are considered special within a class specification are \
different than the rest of regex syntax as follows. If the first character in \
a class is the `]' character (second character if the first character is `^') \
it is a literal character and part of the class character set.  This also \
applies if the first or last character is `-'.  Outside of these rules, two \
characters separated by `-' form a character range which includes all the \
characters between the two characters as well.  For example, === [^f-j] === is the \
same as ===[^fghij]=== and means to match any character that is not \
===f, g, h, i,=== or ===j===. 


%%%Anchors%%%

Anchors are assertions that you are at a very specific position within the \
search text.  __APP__ regular expressions support the following anchor tokens: \

     ^    Beginning of line
     $    End of line
     \<   Left word boundary
     \>   Right word boundary
     \b   Word boundary
     \B   Not a word boundary

Note that the ===\B=== token ensures that neither the left nor the right \
character are delimiters, or that both left and right characters are \
delimiters.  The left word anchor checks whether the previous character \
is a delimiter and the next character is not.  The right word anchor \
works in a similar way. 


%%%Quantifiers%%%

Quantifiers specify how many times the previous regular expression atom may \
be matched in the search text.  Some quantifiers can produce a large \
performance penalty, and can in some instances completely lock up __APP__.  To \
prevent this, avoid nested quantifiers, especially those of the maximal \
matching type (see below.) 

The following quantifiers are maximal matching, or "greedy", in that they \
match as much text as possible (but don't exclude shorter matches if that \
is necessary to achieve an overall match). 

     *   Match zero or more
     +   Match one  or more
     ?   Match zero or one

The following quantifiers are minimal matching, or "lazy", in that they match \
as little text as possible (but don't exclude longer matches if that is \
necessary to achieve an overall match). 

     *?   Match zero or more
     +?   Match one  or more
     ??   Match zero or one

One final quantifier is the counting quantifier, or brace quantifier. It \
takes the following basic form: 

     {min,max}  Match from `min' to `max' times the
                previous regular expression atom.

If ///min/// is omitted, it is assumed to be zero.  If ///max/// is omitted, it is \
assumed to be infinity.  Whether specified or assumed, ///min/// must be less \
than or equal to ///max///.  Note that both ///min/// and ///max/// are limited to \
65535.  If both are omitted, then the construct is the same as ===*===.   Note \
that ==={,}=== and ==={}=== are both valid brace constructs.  A single number \
appearing without a comma, e.g. ==={3}=== is short for the ==={min,min}=== construct, \
or to match exactly ///min/// number of times. 

The quantifiers ==={1}=== and ==={1,1}=== are accepted by the syntax, but are \
optimized away since they mean to match exactly once, which is redundant \
information.  Also, for efficiency, certain combinations of ///min/// and ///max/// \
are converted to either `*', `+', or `?' as follows: 

     {} {,} {0,}    *
     {1,}           +
     {,1} {0,1}     ?

Note that ==={0}=== and ==={0,0}=== are meaningless and will generate an error \
message. 

Brace quantifiers can also be "lazy".  For example {2,5}? would try to match \
2 times if possible, and will only match 3, 4, or 5 times if that is what is \
necessary to achieve an overall match. 


%%%Alternation%%%

A series of alternative patterns to match can be specified by separating them \
with vertical pipes, `|'.  An example of alternation would be  ===a|be|sea=== . \
This will match  ===a===,  or  ===be===,  or  ===sea=== . Each alternative can be an \
arbitrarily complex regular expression. The alternatives are attempted in \
the order specified.  An empty alternative can be specified if desired, e.g.  \
===a|b|=== .  Since an empty alternative can match nothingness (the empty string), \
this guarantees that the expression will match. 


%%%Literals%%%

In a regular expression, most ordinary characters match themselves. \
For example, ===ab%=== would match anywhere ===a=== followed by ===b=== followed by ===%=== \
appeared in the text.  Other characters don't match themselves, but are \
///metacharacters///. For example, backslash is a special metacharacter which \
'escapes' or changes the meaning of the character following it. Thus, to \
match a literal backslash would require a regular expression to have two \
backslashes in sequence. __APP__ provides the following escape sequences so \
that metacharacters that are used by the regex syntax can be specified as \
ordinary characters. 

     \(  \)  \-  \[  \]  \<  \>  \{  \}
     \.  \|  \^  \$  \*  \+  \?  \&  \\ 


%%%Special Control Characters%%%

There are some special characters that are  difficult or impossible to type. 
Many of these characters can be constructed as a sort of metacharacter or \
sequence by preceding a literal character with a backslash. __APP__ recognizes \
the following special character sequences: 

     \a  alert (bell)
     \b  backspace
     \e  escape character
     \f  form feed (new page)
     \n  newline
     \r  carriage return
     \t  horizontal tab
     \v  vertical tab


%%%Octal and Hex Escape Sequences%%%

Any ASCII character, except null (ASCII value zero), can be specified by using \
either an octal escape or a hexadecimal escape, each beginning with \0 or \x \
(or \X), respectively.  For example, \052 and \X2A both specify the ===*=== \
character.  Escapes for null (\00 or \x0) are not valid and will generate an \
error message.  Also, any escape that exceeds \0377 or \xFF will either cause \
an error or have any additional character(s) interpreted literally. For \
example, \0777 will be interpreted as \077 (a `?' character) followed by `7' \
since \0777 is greater than \0377. 

An invalid digit will also end an octal or hexadecimal escape.  For example, \
\091 will cause an error since `9' is not within an octal escape's range of \
allowable digits (0-7) and truncation before the `9' yields \0 which is \
invalid. 


%%%Shortcut Escape Sequences%%%

__APP__ defines some escape sequences that are handy shortcuts for commonly \
used character classes. 


\w	Word character [a-zA-Z_0-9].
\W	Non-word character.
\l	Letter [a-zA-Z].
\L	Non-letter.
\s	Whitespace. (Tab, Space, New Line, etc.)
\S	Non-Whitespace.
\d	Digit [0-9].
\D	Non-digit.
\h	Hex digit [0-9a-fA-F].
\H	Non-hex digit.
\u	Single uppercase character.
\U	Single lowercase character.
\p	Punctuation (not including '_').
\P	Non punctuation.


These escape sequences can also be used within a character class.  For \
example, ===[\l_]=== is the same as ===[a-zA-Z_]===, extended with possible \
locale dependent letters. The escape sequences for special characters, and \
octal and hexadecimal escapes are also valid within a class. 


%%%Capturing Parentheses%%%

Capturing Parentheses are of the form ===(=== ... ===)=== and can be used to group \
arbitrarily complex regular expressions.  Parentheses can be nested, but the \
total number of parentheses, nested or otherwise, is limited to 50 pairs. \
The text that is matched by the regular expression between a matched set of \
parentheses is captured and available for text substitutions and \
backreferences (see below.)  Capturing parentheses carry a fairly high \
overhead both in terms of memory used and execution speed, especially if \
quantified by `*' or `+'. 


%%%Non-Capturing Parentheses%%%

Non-Capturing Parentheses are of the form ===(?:=== ... ===)=== and facilitate
grouping only and do not incur the overhead of normal capturing parentheses. \
They should not be counted when determining numbers for capturing parentheses \
which are used with backreferences and substitutions.  Because of the limit \
on the number of capturing parentheses allowed in a regex, it is advisable to \
use non-capturing parentheses when possible. 


%%%Positive Look-Ahead%%%

Positive look-ahead constructs are of the form ===(?= ===... ===)=== and implement a \
zero width assertion of the enclosed regular expression.  In other words, a \
match of the regular expression contained in the positive look-ahead \
construct is attempted.  If it succeeds, control is passed to the next \
regular expression atom, but the text that was consumed by the positive \
look-ahead is first unmatched (backtracked) to the place in the text where \
the positive look-ahead was first encountered. 

One application of positive look-ahead is the manual implementation of a \
first character discrimination optimization.  You can include a positive \
look-ahead that contains a character class which lists every character that \
the following (potentially complex) regular expression could possibly start \
with.  This will quickly filter out match attempts that can not possibly \
succeed. 


%%%Negative Look-Ahead%%%

Negative look-ahead takes the form ===(?!=== ... ===)=== and is exactly the same as \
positive look-ahead except that the enclosed regular expression must NOT \
match.  This can be particularly useful when you have an expression that is \
general, and you want to exclude some special cases.  Simply precede the \
general expression with a negative look-ahead that covers the special cases \
that need to be filtered out. 


%%%Positive Look-Behind%%%

Positive look-behind constructs are of the form ===(?<= ===... ===)=== and implement \
a zero width assertion of the enclosed regular expression in front of the \
current matching position.  It is similar to a positive look-ahead assertion, \
except for the fact that the match is attempted on the text preceding the \
current position, possibly even in front of the start of the matching range \
of the entire regular expression.

A restriction on look-behind expressions is the fact that the expression \
must match a string of a bounded size.  In other words, `*', `+', and `{n,}' \
quantifiers are not allowed inside the look-behind expression. Moreover, \
matching performance is sensitive to the difference between the upper and \
lower bound on the matching size.  The smaller the difference, the better the \
performance. 

Positive look-behind has similar applications as positive look-ahead. 


%%%Negative Look-Behind%%%

Negative look-behind takes the form ===(?<!=== ... ===)=== and is exactly the same as 
positive look-behind except that the enclosed regular expression must 
NOT match. The same restrictions apply. 

Note however, that performance is even more sensitive to the distance 
between the size boundaries: a negative look-behind must not match for 
any possible size, so the matching engine must check every size. 


%%%Case Sensitivity%%%

There are two parenthetical constructs that control case sensitivity: 

   ===(?i=== ... ===)===   Case insensitive; `AbcD' and `aBCd' are the same.
   ===(?I=== ... ===)===   Case sensitive;   `AbcD' and `aBCd' are different.

Regular expressions are case sensitive by default.  All regular expression token \
types respond appropriately to case insensitivity including character classes and \
backreferences.  There is some extra overhead involved when case insensitivity is \
in effect, but only to the extent of converting each character compared to lower case. 


%%%Matching Newlines%%%

__APP__ regular expressions by default handle the matching of newlines in a way \
that should seem natural for most editing tasks.  There are situations, \
however, that require finer control over how newlines are matched by some \
regular expression tokens. 

By default, __APP__ regular expressions will NOT match a newline character for \
the following regex tokens: dot (===.===); a negated character class (===[^...]===); \
and the following shortcuts for character classes: 

     \d  \D  \l  \L  \s  \S  \w  \W

The matching of newlines can be controlled for the dot token, negated \
character classes, and whitespace shortcuts by using one of the \
following parenthetical constructs: 

     ===(?n=== ... ===)===  `.', `[^...]', `\s', `\S' match newlines

     ===(?N=== ... ===)===  `.', `[^...]', `\s', `\S' don't match newlines (default)


%%%Notes on Parenthetical Constructs%%%

Except for plain parentheses, none of the parenthetical constructs capture \
text.  If that is desired, the construct must be wrapped with capturing \
parentheses, e.g. ===((?i<=== ... ===))===. 

All parenthetical constructs can be nested as deeply as desired, except for \
capturing parentheses which have a limit of 50 sets of parentheses, \
regardless of nesting level. 


%%%Back References%%%

Backreferences allow you to match text captured by a set of capturing \
parenthesis at some later position in your regular expression.  A \
backreference is specified using a single backslash followed by a single \
digit from 1 to 9 (example: ===\3=== ).  Backreferences have similar syntax to \
substitutions (see below), but are different from substitutions in that they \
appear within the regular expression, not the substitution string. The number \
specified with a backreference identifies which set of text capturing \
parentheses the backreference is associated with. The text that was most \
recently captured by these parentheses is used by the backreference to \
attempt a match.  As with substitutions, open parentheses are counted from \
left to right beginning with 1.  So the backreference ===\3=== will try to match \
another occurrence of the text most recently matched by the third set of \
capturing parentheses.  As an example, the regular expression ===(\d)\1=== could \
match `22', `33', or `00', but wouldn't match `19' or `01'. 

A backreference must be associated with a parenthetical expression that is \
complete.  The expression ===(\w(\1))=== contains an invalid backreference since \
the first set of parentheses are not complete at the point where the \
backreference appears. 


%%%Substitution%%%

Substitution strings are used to replace text matched by a set of capturing \
parentheses.  The substitution string is mostly interpreted as ordinary text \
except as follows. 

The escape sequences described above for special characters, and octal and \
hexadecimal escapes are treated the same way by a substitution string. Any of \
the first nine sub-expressions of the match string can also be inserted into the \
replacement string.  This is done by inserting a ===\=== followed by a digit from \
1 to 9 that represents the string matched by a parenthesized expression \
within the regular expression.  These expressions are numbered left-to-right \
in order of their opening parentheses. 

Regular expression substitution can be used to program automatic editing \
operations.  For example, the following are search and replace strings to find \
occurrences of the `C' language subroutine `get_x', reverse the first and \
second parameters, add a third parameter of NULL, and change the name to 
`new_get_x': 

     Search string:   ===get_x *\( *([^ ,]*), *([^\)]*)\)===
     Replace string:  ===new_get_x(\2, \1, NULL)===


%%%Ambiguity%%%

If a regular expression could match two different parts of the text, it will \
match the one which begins earliest.  If both begin in the same place but \
match different lengths, or match the same length in different ways, life \
gets messier, as follows. 

In general, the possibilities in a list of alternatives are considered in \
left-to-right order.  The possibilities for `*', `+', and `?' are considered \
longest-first, nested constructs are considered from the outermost in, and \
concatenated constructs are considered leftmost-first. The match that will be \
chosen is the one that uses the earliest possibility in the first choice that \
has to be made.  If there is more than one choice, the next will be made in \
the same manner (earliest possibility) subject to the decision on the first \
choice.  And so forth. 

For example, ===(ab|a)b*c=== could match ===abc=== in one of two ways.  The first \
choice is between `ab' and `a'; since `ab' is earlier, and does lead to a \
successful overall match, it is chosen.  Since the `b' is already spoken for, \
the `b*' must match its last possibility, the empty string, since it must \
respect the earlier choice. 

In the particular case where no alternations ===|=== are present and there is only one ===*===, \
===+===, or ===?===, the net effect is that the longest possible match will be \
chosen.  So  ===ab*=== , presented with  ===xabbbby=== , will match  ===abbbb=== .  Note that \
if  ===ab*===  is tried against  ===xabyabbbz=== , it will match  ===ab===  just after  ===x=== , due \
to the begins-earliest rule.  (In effect, the decision on where to start the \
match is the first choice to be made, hence subsequent choices must respect \
it even if this leads them to less-preferred alternatives.) 


%%%Examples%%%

The following are regular expression examples which will match: 

    * An entire line.
        ===^.*$===

    * Blank lines.
        ===^$===

    * Whitespace on a line.
        ===\s+===

    * Whitespace across lines.
        ===(?n\s+)===

    * Whitespace that spans at least two lines. Note minimal matching `*?' quantifier.
        ===(?n\s*?\s*)===

    * IP address (not robust).
        ===(?:\d{1,3}(?:\.\d{1,3}){3})===

    * Two character US Postal state abbreviations (includes territories).
        ===[ACDF-IK-PR-W][A-Z]===

    * Web addresses.
        ===(?:http://)?www\.\S+===

    * Case insensitive double words across line breaks.
        ===(?i(?n<(\S+)\s+\1>))===

    * Upper case words with possible punctuation.
        ===<[A-Z][^a-z\s]*>===


###Shell Commands and Filters###

The %%%Tools%%% menu provides some items which allow you to execute shell commands \
from within __APP__. These items allow you to use external programs like awk, sed, etc... \
and shell scripts to filter selected text or insert new text into the current document. \
You can also run external commands such as compilers or syntax checkers and send their \
output to the "Output Pane", which can then be used to navigate to specific error locations \
within the files.

The %%%Filter Selection%%% menu item prompts you for an external command to be used in \
processing the currently selected text.  The contents of the selection are piped into the \
command's input, and the output from the command replaces the selection. 

The %%%Insert Command%%%  menu item prompts you for an external command and replaces the \
current selection with the output of the command.  If there is no  selection, it deposits \
the output at the current insertion point. 

The %%%Execute Command%%%  menu item prompts you for an external command and deposits \
the output into a message window ( called the "output pane" ) below the current document. 

By default, __APP__ uses  '===/bin/sh -c==='  to execute external commands, this can be \
changed via:
  %%%Edit->Preferences->general->Shell command%%%

__APP__ also exports the following environment variables to the external commands:
    ===$f===  = Full path and filename of the active document.
    ===$l===  = Current line number.
(On MS-Windows, these variables can be referenced as  ===%F%===  and  ===%L%===  respectively.)

In the event that an external command becomes "stuck" (e.g. an caught in an infinite loop, \
or waiting for input that never arrives, etc.) you can usually cancel the command by \
pressing %%%Ctrl+.%%% on the keyboard (that is, hold the [Ctrl] key down and press the "period" key). \
(In some cases you may need to continue holding down this key combination for a few seconds.) \
This key sequence can be customized under:
%%%Edit->Preferences->Keybindings->KillCommand%%%.

Note that on MS-Windows, external command execution is performed using "blocking" input and output functions, \
so if a Windows command becomes blocked, your only recourse might be to press Ctrl+Alt+Del and terminate \
the hung process!


 
###Macro Recording and Playback###

Selecting %%%Record macro%%% from the %%%Tools->Macro recorder%%% menu puts \
__APP__ in "recording" mode.  In this mode, keystrokes and certain menu commands \
are recorded, to be played back later, using the %%%Play macro%%% menu, or \
opened into a new, untitled document via the %%%Show macro%%% menu. To finish the \
recording session, choose %%%Stop recording%%% from the menu.

Note that only basic editing commands are recorded. Mouse clicks, mouse movements, \
document switching, etc. are not recorded, since these have no absolute point of \
reference, and attempting to record this information could become quite complex and \
error-prone. 

Recording mode can also be the quickest and easiest method for writing macros.  \
When you create a new document using the %%%Show macro%%% menu, its contents \
can then be edited and pasted into a new menu command created as described in the \
%%%Customizing the Tools Menu%%% section of this help document.


###Customizing the Tools Menu###

You can add your own items to the %%%Tools%%% menu to extend __APP__'s command set by incorporating \
shell commands and/or editing languages like awk and sed, or to run external tools like compilers, or \
inserting "boilerplate" text snippets, or creating your own %%%Lua%%% macro scripts.

To add a new shell command item to the menu, select: 
%%%Tools->Customize Menu->Commands->New Tool%%%.

Choose the %%%Open in editor%%% button to open your newly-created script in the editor \
and insert the desired shell commands. Likewise, you can use a similar procedure to create \
new filters, snippets, and macros. ( ///Commands/// and ///filters/// behave similar to the \
%%%Execute command%%% and %%%Filter Selection%%% menus. \
///Snippets/// can either be a text file whose contents are inserted directly into the current document, \
or a shell script whose output is inserted into the document. ///Macros/// are interpreted by __APP__'s \
embedded %%%Lua%%% scripting engine. )

To help organize your custom commands, you can also create new "groups" or sub-menus to contain \
the items. To create a new sub-menu, choose the %%%New Group%%% button from the dialog. The dialog \
also provides for renaming or deleting menu items and moving items from one submenu location to another.

To edit one of the commands after adding it to the menu, right-click the menu item, or select it \
with the keyboard and press %%%Ctrl+Enter%%%.

Any menu group named  ==="Hidden"===  is considered special. If you create a group with that name, \
its items will be accessible via their assigned shortcut key, but the group will not be visible \
on the tools menu. This allows you to associate keyboard shortcuts to custom commands without \
cluttering up the menu.

If you find managing your tools from the dialog is a bit too awkward, the items are stored in a \
directory hierarchy under your  ===$HOME/.foxrc/__EXE__/<config-name>/tools/===  directory, and can be \
manipulated using your favorite file manager or terminal. The filenames stored there might look \
a bit strange, since __APP__ uses the names as a sort of "metadata" for creating the menus and \
executing the commands. In a nutshell, the syntax for the filenames goes something like this:

* A two-digit index number, followed by a dot.

* The name of the menu command, in lowercase, with spaces converted to hyphens.

* If the name contains an underscore, the next letter is underlined in the menu.

* An optional ===@=== sign, followed by a hotkey sequence.

* An optional file extension, like ===.sh=== or ===.lua=== or ===.txt===

(The naming scheme for subdirectories is similar, but without the \
optional hotkey sequence notation and file extension.)

Additionally, for files in the ===commands=== folder, if the filename matches the widlcard \
pattern "===*.save.*===" then __APP__ will attempt to save any unsaved changes in all open documents \
before the command is executed. For files in the ===snippets=== folder, files matching the wildcard \
"===*.exec.*===" will be executed and their output inserted in the document, otherwise, the file's \
contents are inserted. And of course, files must have the necessary permissions in order to be executed! 

Note that if you modify any of these items externally, you can have the changes reflected \
in your current editing session by choosing the %%%Rebuild menu%%% command from the %%%Tools%%% menu.

As an example, if you wanted a shell script to invoke the "make" command, as the first item \
under the %%%Commands%%% menu, with the letter "k" as its menu accelerator key, and with the hotkey \
sequence %%%Ctrl+F9%%%, and you also wanted it to save your open files before running, this strange-looking \
filename would do it:

===00.ma_ke@Ctrl+F9.save.sh===

(The contents of the script file might simply be the word "make")


###Hook Functions###

Hook functions are Lua scripts that execute whenever a certain event occurs in __APP__.

The configuration directory contains the subdirectory:
  ===$HOME/.foxrc/__EXE__/<config-name>/tools/hooks/===

The ===hooks=== subdirectory can contain the following files:

  === startup.lua  ===
    Runs immediately after __APP__ starts, before files open.

  === saved.lua===:
    Runs immediately after a file is saved.

  === opened.lua===:
    Runs immediately after a file is opened.

  === closing.lua===:
    Runs before a file is closed (but after its final save).

  === shutdown.lua===:
    Runs when __APP__ exits (after confirm, before files close).



###Custom Keybindings###

Keybindings are the association between a keyboard action and an editor command. \
By default, __APP__ comes with keybindings that should be familiar to most users, \
but individual preferences, usage requirements, and experience with other \
editors may vary widely. For example, __APP__ uses %%%Ctrl+R%%% to display the \
Find/Replace dialog, while several other editors use %%%Ctrl+H%%% for the same \
command. To modify the keybindings to suit your particular needs, go to:
%%%Edit->Preferences->keybindings%%%

The names in the %%%action%%% column of the dialog refer to the various menu \
commands and should be more-or-less self-explanatory. To modify a keybinding, \
double-click the item,  or select it with the up/down arrow keys and press %%%[Enter]%%%. \
A small popup window will appear where you can enter the new keybinding specification \
as a single text string similar to the ones displayed in the menus. Examples might be \
%%%Ctrl+Alt+X%%%  or  %%%Alt+Shift+U%%%  or simply  %%%F4%%% .  __APP__ will try to warn you \
if you enter an invalid string or something that conflicts with an existing assignment, \
but it might not always detect all conflicts or errors.



###The Toolbar###

The toolbar is a row of multi-colored buttons that sits below the main menu bar. By default, these buttons \
provide access to some commonly-used menu commands, but you can alter this configuration from the %%%toolbar%%% \
tab of the %%%Preferences%%% dialog. From there, you can remove unwanted commands, add commands \
that you use more often, and re-arrange the commands to suit you own taste. You can also add buttons to access \
any custom menu commands you may have added to the %%%Tools%%% menu. 

One thing some users might find strange is that the labels for the toolbar buttons are text-only, there are no \
fancy icons. But if you consider that there are over 80 pre-defined menu commands, and possibly a large number of \
custom commands, you can see why drawing a tiny little picture to describe each one could quickly become \
impractical. So instead, each button's label holds a very brief description of the command. If you hover the \
mouse pointer above a button, it will display a "tooltip" showing the complete menu path of the command \
to help clarify what the button does. These same tooltips are also displayed when you hover the mouse over \
the lists in the %%%toolbar%%% tab of the %%%Preferences%%% dialog. 

Note that when you add buttons for user-defined menus, the button labels are derived from your command name \
by taking the first two words of the command name and truncating those two words to a maximum of five letters each. \
This is something you should consider when naming a custom menu if you intend to access it from the toolbar. That is, \
if you have a command named ///"This Will Show the Clock"/// and another named ///"This Will Erase the Hard Drive"/// \
you would end up with two buttons labeled ///"This Will"/// which might not be an ideal description. So you might \
want to choose names like ///"Show Clock"/// and ///"Erase Drive"/// instead.

The toolbar is limited to a maximum of 24 buttons, which should be adequate for most users. The buttons are normally \
displayed in a single row, but depending on the window size and screen resolution, this row can be "wrapped" into \
two rows as needed. If you dislike this wrapping behavior you can turn it off by un-checking the %%%Wrap buttons%%% \
option from the %%%Preferences%%% dialog. The dialog also allows you to choose whether to have small, medium, or \
large buttons. For users who would rather not see the toolbar at all, you can hide it by toggling \
the %%%Toolbar%%% option from the %%%View%%% menu.



###Crash Recovery###

__APP__ is able to maintain periodic backups of the files you are editing so that you can \
recover the file in the event of a problem such as a system crash, network failure, \
X server crash, or even if __APP__ itself crashes.  These files are saved along with \
their directory structure under the ===$HOME/.foxrc/__EXE__/backups.d/=== directory. To enable \
this feature, check the "%%%Backup files%%%" option under the %%%general%%% tab of the \
%%%Preferences%%% dialog, where you can also choose a backup interval between 15 seconds \
to 15 minutes. Under most circumstances, the backup files are removed automatically whenever the \
original file is saved or closed. Since the backups are saved under the user's home directory, \
there won't be any conflicts between backups of two users editing the same file, but if \
a single user is running two instances of __APP__ editing the same file at the same time, you \
might not get back the copy you expected in the event of a crash. The algorithm used to \
save and remove the backups tries to strike a balance between simplicity, efficiency, and \
reliability, but you may notice some decline in performance when editing files across a slow \
network connection, etc. There are currently no provisions for automatically restoring the \
files, but you should be able to browse the backup directory to recover them manually. \
In the case of untitled documents, the backups are saved using a numeric filename created \
from __APP__'s process ID and the XWindow ID of the document's editor widget.



###Multiple documents and multiple views###

__APP__ is able to open several files in the editor at the same time, with a familiar "notebook tabs" interface. \
The base filenames are displayed in a row of "tabs" above the documents. You can change  \
the location of these tabs to the top, bottom, left or right side from the %%%View->Tabs->Position%%% menu.

To switch from one document to another, you can click the desired tab, or use the %%%Ctrl+PageUp%%% and \
%%%Ctrl+PageDown%%% keys to switch to the previous or next document. In the event that you have more documents open \
than can be displayed across the tabs, you can click on the outermost left or right tab to scroll some of the \
other tabs into view, or select a document from the %%%Documents->Select%%% menu.

Document tabs can be re-ordered from the %%%Documents->Move%%% menu, but it is often easier to simply drag the tab \
with the mouse and drop it near the edge of another tab.

Documents can be closed from the %%%File->Close%%% menu command, or by pressing %%%Ctrl+W%%% on the keyboard, or by \
right-clicking on a tab and choosing %%%Close%%% from its popup menu.

There may be times when you need to view two different areas of the same document at the same time. You can do \
this using the "%%%View->Split View%%%" menu. Choosing this command will create a new "view" of the active document \
directly below the current view. Choosing the command again will switch to a side-by-side view, and once more will \
revert back to single-view mode. You can control how this view-cycling effect behaves from the 
"%%%Edit->Preferences->editor->Split views%%%" option.
 
In order to protect the editor from excessive memory and processor usage in the event that you \
accidently do something silly from the command line, like:
===  __EXE__ * ===
in a directory containing thousands of files, __APP__ has a limit on the number of documents that can be \
open at one time. By default the limit is 128, which should be more than enough for most uses, but you \
can adjust this (up to a maximum of 999) from the 
"%%%Edit->Preferences->general->Maximum open files%%%" option.



###Named Instances and Configurations###

Normally, when __APP__ is started it creates a single instance (or "server") \
named %%%default%%%. When __APP__ is invoked again (e.g. from the command line) \
the requested command is sent to the currently running instance. To create \
additional servers, you can invoke __APP__ with the ===-s=== command line \
option, for example:

  ===__EXE__ -s myserver file_one.txt===

Now, when you issue an additional command line:

  ===__EXE__ -s myserver file_two.txt===

The second file ===file_two.txt=== will be opened in the running instance \
named ===myserver===. Note that each separate instance of __APP__ \
created this way will share the same default configuration directory. To create \
a completely separate configuration of __APP__, you can use the  ===-c===  command line \
option, for example:

  ===__EXE__ -c myconfig===
  
To re-use the settings you made in your original configuration, you could first make a copy \
of the existing configuration from the command line:

  ===cp -a ~/.foxrc/__EXE__/default ~/.foxrc/__EXE__/myconfig===


With some clever use of symbolic links, you should be able to share some aspects \
of your configurations (like tools menu items, for instance) while maintaining \
separate copies of other confguration files.

Also note that X11's %%%WM_CLASS%%% string is set according to the server name. \
This allows you to specify different window manager hints for different instances, or \
to manipulate specific __APP__ windows using tools like %%%wmctrl%%% and %%%devil's pie%%%.

Server names should contain only ASCII alphanumeric characters and underscores, any other \
characters will be converted to underscores. The names are not case sensitive, that is:  \
%%%MYSERVER%%%,  %%%MyServer%%% and %%%myserver%%% are all considered as the same name.

Configuration names must consist of only lowercase alphabet (%%%a-z%%%) and numbers (%%%0-9%%%). 

To help distinguish between multiple configurations running on the same desktop, it is possible \
to have a distinct window icon for each configuration. To do this, create a 32x32 XPM \
image named ==="icon.xpm"===  and place it in the configuration directory, for example:
   ===~/.foxrc/__EXE__/myconfig/icon.xpm===


###Embedded Scripting Engine###

__APP__ features a built-in script interpreter using the %%%Lua%%% programming language. \
Lua scripts may be written from scratch or recorded using the editor's macro recording feature. \
These scripts can then be added to the %%%Tools%%% menu for easy access, or used as an event \
hook that is triggered when certain actions occur in the editor. Lua code can also \
be executed directly from the command line, using the ===-e=== option followed by a \
properly-quoted string of Lua source code. The core Lua language offers some powerful \
functions for general purpose programming, string matching and manipulation, mathematics, \
file I/O, etc. and can also be extended using third-party libraries or "modules". \
 And of course __APP__ offers its own set of Lua functions, allowing the interpreter \
to interact with the editor itself. These functions are described in detail under \
the "%%%Help->Macro help%%%" menu.

Although a complete discussion of Lua is outside the scope of this document, there is a \
vast amount of information available online. For starters, here are a few links:

///The main Lua website:///
===    http://www.lua.org/===
///The Lua users wiki:///
===    http://lua-users.org/wiki/LuaDirectory===
///The official reference manual:///
===    http://www.lua.org/manual/5.1/===
///The "unofficial" Lua FAQ:///
===    http://www.luafaq.org/===
///The Lua short reference "cheat sheet":///
===    http://lua-users.org/wiki/LuaShortReference===
///The slightly outdated (but still excellent) online book:///
===    http://www.lua.org/pil/===
///You can also find a large selection of add-on modules here:///
===    http://luaforge.net/===

Please be warned that although the scripting interface makes some effort to avoid common pitfalls such as \
endless loops, infinitely-blocking I/O, and memory access errors, it can't possibly anticipate \
every situation, and there is still some chance that these things will happen. \
If they do, it may result in a frozen application, a crash, or a complete meltdown of the universe. \
Therefore I would recommend that you don't try any new and exciting scripting tricks while you \
have important unsaved changes!

In the event that the interpreter becomes "stuck", you may be able to cancel the running script using the \
same method described in the "Shell Commands and Filters" chapter of this document.



###Support and Contact Information###

Questions or comments regarding __APP__ should be directed to the %%%fxscintilla-users%%% mailing list. \
For more details, visit:
  ===http://lists.nongnu.org/mailman/listinfo/fxscintilla-users===

Bug reports may be submitted at:
  ===http://savannah.nongnu.org/bugs/?group=fxscintilla===

You can also contact the primary author (Jeff Pohlmeyer) directly via email at:
  ===yetanothergeek@gmail.com===

