not A Commander -
a better (and this time graphical) rip-off of Norton Commander (tm)
===================================================================
by Sergey Babkin <babkin@users.sourceforge.net>

Philosophy
==========

This project is using the technology of Natural Stupidity for development:
first get something working at all, then gradually improve it. My primary
targets are the features that I personally would use. The features that
I won't use anyway are not planned to be implemented at all (though if
someone would contribute an implementation I would gladly accept it - as
long as it does not break any of the things that I use).

Download
========

I have discovered that there are many sites on the Web that carry links
to the packages with the old releases of Not A Commander. So please look
at the official Not A Commander site at http://nac.sourceforge.net
and check for the new releases.

Build
=====

Run `make'. That should build all the binary parts. The X11 headers are
required for build. You may need to modify the Makefile for peculiarities
of your particular system (directory names, libraries etc.).

Installation
============

Run `make install'. By default the `nac' binary is instaled into 
/usr/local/bin and the rest of files is installed into
/usr/local/lib/nac (which is referred further as "the NAC directory").
These directory names can be changed in the Makefile. If the configuration
file nac.sysrc was present in the NAC directory before installation,
it will be moved into nac.sysrc.old.

Starting
========

Run
    nac [options] &

Most systems have the default limit for the number of open files set to
at least somewhere around 60. This should be enough for all the situations
into which NAC can get. If you have a smaller limit, increase it. If
you can't increase this limit, then limit your use of the background
operations in NAC.

The supported options are:

  -display <display-name>
  -colormap new
  -sync
  -use <window-id>
  -visual <visual-type>

The usual Tcl/Tk options, see the wish(n) man page for description.

  -name <name>

Makes NAC use the specified name (instead of the default "nac") for
reading the X11 resources. Also makes NAC read the configuration file
$HOME/.nacrc-<name> after $HOME/.nacrc (if this file is present).
This option does not affect the NAC window title shown in the window
manager frame.

  -title <title>
  -shorttitle <title>

Set the NAC window title shown in the window manager frame. NAC uses
two forms of the title: the normal title (by default "Not A Commander")
most of the time and the short title (by default "NAC") when it has some
additinal message to display. If only one of these options is specified,
it sets the same value for both the normal and short titles. If both options
are specified, each to its form of title.

  -term <terminal-program>

Choose the terminal emulator program, for example:
	nac -term dtterm
would run dtterm as the terminal emulator. The default value is xterm.

  -termopt <terminal-options>

Give arbitrary options to the terminal emulator. The default value is
"-bg black -fg peachpuff". In addition to the options specified here
NAC always adds the options -iconic -b and -e which are neccessary to
connect the terminal to NAC, do not redefine them.
For example:
	nac -termopt "-fg yellow -bg gray -font 8x13"
will run xterm within NAC with these colors and font. Another example:
	nac -term dtterm -termopt ""
will use dtterm instead of xterm and run it with the native colors.

  -geometry <geometry-spec>

Specify the geometry for the NAC window. The format of the geometry is the
usual [<width>x<heigth>][+-<x>+-<y>] (+- means "+ or -") with a little
twist: if "term" stands instead of <width>x<heigth> then NAC will base its
window size on the terminal emulator's window size. For example:
	./nac -geometry term+10-100 -termopt "-geometry 80x40"

What's new ?
============

See the CHANGES file.

What works, what does not ?
===========================

Only the more basic things work now. The list of generally working and working 
well things will increase over time.

Currently the main development platform for NAC if FreeBSD 4.0 (with
fvwm and tk8.0). I also test it time to time on OpenUNIX 8.0 (A.K.A
UnixWare)/CDE/tk8.2 and OpenLinux 3.1.1/KDE/tk8.0.  Dtterm can be used 
instead of xterm but it does not handle the window resizing as good as xterm.

Fvwm2 (2.4.8) is known to screw up the focus handling in the xterm window
when it's uncovered. Fvwm1 does not have this problem (but tends to 
mysteriously lose focus after exit from Tk applications). For now the 
workaround is that if NAC gets any characters when xterm is supposed to
receive, NAC passes the focus to xterm again, so that xterm will get the
next characters. However these misdirected characters are lost. The root
of the problem is that Tk does not fully comply with ICCM and fvwm2 does
not handle this Tk brokenness gracefully.

The graceful error handling is partially missing.

Only a minimal set of the file manager operations.

There is only one mode (multicolumn) of directory panels (it's the only one 
I use).

Only Bourne-style shells are supported (sh, ksh, bash etc.). Although support
for csh is possible (that would require a different shell helper program)
none is planned because I don't use csh.

The mouse support is very minimal yet but more is planned.

The type-ahead does not work when the dialogs are being posted.

For now NAC is quite tough to configure: the only way to do it is to look up
the names of tunables inside the source code of tune.tcl and put their new
values into the NAC rc scripts. 

There is no support for the XKB extension, though its compatibility mode
should work OK.

Some parts of this manual are out of date, they may describe the bugs which
have been fixed since then.

The job control is slightly brittle yet.

The editing and viewing is somewhat primitive yet. The Midnight Commander's
file mc.ext is only partially supported and probably is parsed somewhat
differently than MC does it.

There should be a better way to do the preview of commands' execution.

There still are races with focus assignment after a command completes, 
especially when working over a busy network.

There is a report that NAC works very slowly on Mandrake Linux with Tcl/Tk 8.3
but the details are unknown, possibly the build was done wrong.

The viewer `naciew' is in the prototype stage and breaks on many things.

Bug reporting
=============

If you find a bug in NAC, please let me know, send me an e-mail to 
<babkin@users.sourceforge.net> . Please describe exactly how to reproduce the
problem. If you get a window with the Tk stack trace, please include this stack
trace as well. To copy this stack from the Tk window to your favorite text
editor use the usual X11 selection mechanism: select the text in the Tk
window by dragging the left mouse button then paste it into the editor window
by pressing the middle mouse button (for 2-button mice the middle button
is usually simulated by pressing both buttons at once). If you use a modal
editor like vi, don't forget to enter the insert or append mode before
pasting the data. Disabling the auto-indenting is usually also a good idea.

Configuration
=============

The default configuration of NAC can be changed with rc files.
There are two rc files:

per system - nac.sysrc in the NAC directory
per user - .nacrc in the user's home directory

These files are common Tcl scripts that can be used to change the tunable
values. NAC first sets the built-in values, then loads the system-wide
rc file (if present), then loads the user's rc file (if present). Thus
the system-wide script can examine the built-in values and modify them
as neccessary, and the user's script can do the same thing with the result
of the system-wide script.

Be careful with the syntax, in case of an error in the rc scripts NAC
won't start.

The list of the supported tunables and their values can be found at the top 
of tune.tcl. For now (the alpha phase of development) it's expected
to be quite liquid and change between snapshot releases. Probably some
sort of versioning will be added after it stabilizes.

The sample system rc file included in a release contains only one setting -
the name of font to use (most probably you don't have the font "koi9x16"
which is the built-in default).

The default initial size of the window is defined by panel dimensions,
variables named set panel:filespercolumn (number of rows in panels),
panel:ncolumns (number of columns in panels), panel:columnwidth (width of
a column in dots). The internal xterm is automatically resized to fit
these dimensions. Alternative size in pixels or xterm characters can be
selected with command line options.

Use
===

The look-and-feel is generally close to the Norton Commander(tm) but
a few differences are already present. They are specially noted.

Just like NC the window consists of two directory panels, the command
line and xterm beneath them. The directory panels may be closed to see
the terminal window. Unlike NC the panels can't be resized (yet).

Panels
------

Because there are more file types in Unix than in MS-DOS the type of file is 
indicated differently from NC: the directories have raised relief, common
files have flat relief, executable files have rigde relief, and various
special files have flat relief with a file type letter (like in ls) on
the left in different color and sunken relief. The symbolic links are
normally shown with the type of file they refer to, and only if that
file does not exist they are shown as special files with letter "l".

The current file is indicated by changed background color. More detailed
information about it is shown at the bottom of the panel. For symbolic
links this detailed information includes their targets, like in the
output of "ls -l". If some files are selected, then the summary information
about the selected files is prepended at the bottom of the panel: the
number of files selected and their total size. The subdirectories are not
counted in this total size, only the regular files are.

Because the file names may be very long in Unix, the file list in the
panel is scrollable, as well as the information about the current file.
The scrolling may be done with mouse by using the horizontal scrollbars
in the panel. The scrolling may also be done with keyboard:

* Shift-Left/Shift-Right - moves both scrollbars left or right

To change only the file info scrollbar from keyboard the focus can be set
to it and then it may be moved with arrow keys:

* Shift-Down - change focus to the file info scrollbar
* Shift-Up - return the focus back to the panel

The panel scrollbar reflects the width of the longest file name and shifts
all the names in the panel at once. If the space allows, NAC tries to keep
the width of this scrollbar's slider equal to the width of a column, then
the width of the scrollbar's trough reflects the actual width of the longest
name. But if that would cause the scrollbar to be wider than the panel width, 
the whole scrollbar is kept at the panel width and the slider shrinks 
proportionally.

The usual panel navigation works as in NC:

* Up - move one file up
* Down - move one file down
* Left - move one column to the left (or to the first file if that was the 
  leftmost column already)
* Right - same thing but one column to the right
* PgUp - one page up
* PgDn - one page down
* Home - to the first file
* End - to the last file
* Tab - switch to another panel (if it's visible)
* Enter - if a command is present in the command line then execute it, or
  if the current name in a panel is a directory, go into that directory
  (if unable to, it would show an error message and remain in the current
  directory), or if the current file is executable, execute it
* Shift-Enter - the same thing but execute the command in background
* Ctrl-Enter - copy the name of the current file to the command line
* Ctrl-Shift-Enter - copy the list of selected files (or if none selected then
  of the current file) to the command line
* Ctrl-P - copy the current working directory (as in pwd) to the command line
* Ctrl-F1 - hide/show the left panel
* Ctrl-F2 - hide/show the right panel
* Ctrl-O - hide/show whatever panels were shown last time. The command line
  is never hidden.
* Ctrl-R - reload directory in the current panel
* Insert - select/deselect the current file (this has no relation to the 
  X11 selection) and move down
* Keypad_Plus - select the files with matching names (see the section "Select 
  matching files" in "Dialogs")
* Alt-Shift-Plus - same, for keyboards without keypads
* Keypad_Minus - deselect the files with matching names
* Ctrl-Shift-U - exchange panels
* Ctrl-B - hide/show the function keys help line
* Alt-Minus - quickly find a file by name

Some control keys (such as Ctrl-U) have different meaning in NC and in the 
Unix shell. In these cases the preference is usually given to the Unix meaning
and the NC meaning is achieved with Shift.

If some file has an LF character (also known as \n) in its name then
only the first line of such name is visible. All the operations on such
file should work normally.

If multiple commands are typed on the command line (separated by ";") when
Shift-Enter is pressed, then all the commands except the last one will
be executed in foreground and only after that the last command will be
executed in background. This happens because Shift-Enter just simple-mindedly
adds " &" to the current command line before passing it to the shell.
It's intended primarily to start easily the windowed commands from the panel 
in background.

When the name of the current file is copied to the command line with
Ctrl-Enter, it does special handling of the name if the command line is 
currently empty: it adds "./" in front of the name and quotes all the
dangerouns characters in the name. This is done because empty command line
means that this file name will probably be used as a command name.
If the command line is not empty then proper quoting of the names is
up to the user. In any case a space (" ") is inserted after the name.

The whole list of currently selected files, separated by space, can be copied
to the command line with Ctrl-Shift-Enter. For this key combination, no
special treatment is given for the currently empty command line, quoting
of all the strange characters in file names is always up to the user.
Due to strange ideas of the Tk text widget, after inserting a long list
of files the command line sometimes looks like empty. But it actually
is not, try moving the cursor to the left and you'll be able to see the
inserted text.

The files in the panels may be sorted in many ways, selected by the menus.
The sort modes are mostly self-explanatory, so only more non-obvious things
are described here:

"by suffix" - order the files by the last suffix ("extension" in DOS terms)
of their names, and the files with the same suffix are ordered by their
base name. If sa file name starts with a dot, this dos is not considered
beginning of a suffix, but rather a part of the base name. If a name contains
more than one suffix (such as "file.c.b" or "file.tar.gz") then all suffixes
but the last one are considered as parts of the base name. So for example
the files a.b.c and b.a.c will be ordered:

 a.b.c
 b.a.c

"by all suffixes" - the sorting is done by all the suffixes starting from
the last one and only then by the base name. So for example the files 
a.b.c and b.a.c will be ordered:

 b.a.c
 a.b.c

"by type" - sort by the Tcl-style file type, such as "file", "directory",
"blockSpecial" etc.

Also there are options to place the entries of special interest, directories
and/or executable files up front. These options work with any sort mode.
If both of them are selected, the executable files are placed after
the directories.

Independently of the sort modes and the "up front" options, the entry
".." (the parent directory) is always placed first.

The Quick Find mini-dialog is posted by pressing Alt-Minus. When this dialog
is posted, the navigation and selection within the panel works as usual, 
however the other commands don't. All the typed input is interpreted as a 
pattern of the file name to find. As the pattern is typed, NAC automatically 
moves the current position in the panel to the next matching file. Or if the 
current file matches the new input too, then the position is not moved. 
The position is also not moved if there is no matching file.
To emphasize, the text typed in the Quick Find entry is interpreted NOT as a 
plain text (as in the Norton Commander) but as a pattern. 

The format of the pattern is the usual Tcl glob pattern (essentially the same
as the shell glob pattern) with two exceptions: 

1. Normally NAC implicitly adds "*" (a star) at the end of the pattern, so 
that it won't get anchored at the end. To make it anchored at the end, add 
"$" (dollar sign) at the end of pattern. For example, the pattern "*.h$" will 
match the files ending with suffix .h. To enter the dollar sign as a proper
part of the pattern itself, precede it with backslash ("\$").

2. Enter a slash ("/") at the start of the pattern to search for directories
only.

The other special keys in the Quick Find mode are:

* Esc - exit from the Quick Find mode
* Enter - go to the next matching file (wrapping at the end)
* Shift-Enter - go to the previous matching file (wrapping at the start)
* Backspace - erase one character to the left
* Ctrl-U - clean the pattern completely
* Alt-Up - to the earlier value in the history stack (if available)
* Alt-Down - to the later value in the history stack (if available)

The pattern field is preserved between the invocations of Quick Find,
but is cleaned automatically if any characters are entered. Or press Enter
to continue with the existing pattern.  The pattern can also be cleaned at
any time by pressing Ctrl-U.

There is no editing with the arrow keys, just typing, backspace and Ctrl-U. 
When a character is erased by backspace, the position is returned to
where it was before that character was typed (of course, this works
only if the directory was not changed in the meantime, otherwise the position
is not moved). The position is not changed on Ctrl-U.

The history handling is a bit tricky. The patterns are entered into the
history on Esc or at any time the pattern field is cleaned, automatically
or by Ctrl-U (but not by pressing Backspace repetitively). The history
stack is shared between two panels, so it can be used for transferring the
patterns between them. The browsing in the history stack is done as usual,
by Alt-Up/Down. Press Enter or type any character to make a historical
pattern the current one.

Command line
------------

There is a certain difference from NC in handling of the command line:
most of the Unix commands end their output with a line feed, so that
the xterm cursor is standing in beginning of the line. So moving the whole
screen up and placing the command line widget under it would be a waste
of space. On the other hand, some commands don't put this last line feed,
so if the screen is not moved up, this last line would be covered by the 
command line widget. The solution used in NAC is that it does cover the lowest
line of xterm with its command line widget but the shell helper tries to
make sure that if there is something interesting in that last line, it
would be scrolled up. To achieve this it depends on the auto wraparound
enabled in xterm. But there is also way to see the whole xterm screen 
unobstructed:

* Esc - hide/show whatever obstructs xterm

When the panels/command line are displayed, xterm is shown behind
a transparent cover, so any mouse actions on it won't work (even though
they would work when some command is running in xterm). Xterm is fully 
accessible when it's uncovered by "Esc" - you can do selections,
change xterm configuration, move the scrollbar and even type (except the 
Esc key) though the stuff you type would go to the standard input 
of the next command so the typing probably is not something you want to do.

The control characters on it are shown preceded by a caret, like "^A", in
yellow color. The keys that are working like NC are:

* Ctrl-S - move one character to the left
* Ctrl-D - move one character to the right
* Ctrl-Left - move one word to the left
* Ctrl-Right - move one word to the right
* Backspace - delete one character to the left
* Delete - delete one character to the right
* Ctrl-Backspace - delete one word to the left

There is no key to delete one word to the right.

The cursor is shown as a non-blinking block. Also the following keys are
the NAC additions:

* Alt-Left - move one character to the left
* Alt-Right - move one character to the right
* Alt-Home - move to the beginning of the line
* Alt-End - move to the end of the line

In addition some of the traditional Unix control keys work as usual:

* Ctrl-U - clean the command line
* Ctrl-V - insert the next character verbatim
* Mouse Button 2 - paste the X selection

When both panels are closed, all the usual entry field keys work as
well (see the section "Entry fields"). When the command line has focus
(its cursor is shown as a block), the X selection is pasted into
the command line, no matter where the mouse cursor is.

The command history keys are:

* Ctrl-E - to the earlier command in the stack
* Alt-Up - same
* Up - same thing if the panels are closed
* Ctrl-X - to the later command in the stack
* Alt-Down - same
* Down - same thing if the panels are closed

When the line is edited, it's automatically placed at the latest command
position. If the previous command is repeated unchanged, it is not saved
in the history for the second time.

An important difference from NC (and its other copies) is that NAC passes 
the commands to a constantly running shell instead of starting a new
shell for every command. That means that values of all the shell variables 
are remembered, just as if they would be entered into a normal shell.
Also if a command changes the current directory of the shell, this gets
reflected into NAC too (and infact NAC does no special treatment of
the "cd" command, it's just passed to the shell like anything else).
After completion of each command NAC remembers the current directory of
the shell and all of its expoetrd variables. Before passing a command
to the shell NAC prepends it with "cd" to the NAC's idea of the current
directory (which may diverge from the shell's idea due to the panel
operations).

Unlike usual shell, pressing the INTR key (usually Ctrl-C or Del 
depending on the terminal configuration) in the xterm window kills not 
only the current executing process but the shell itself as well. NAC 
detects that, restarts the shell and restores the current directory and 
the exported variables from what it remembered after completion of the 
previous command.  Alas, the non-exported variables are lost. So be
careful with killing.

Also if the shell dies over 10 times in 1 second, NAC considers it a
technical problem and stops restarting the shell (in future it will
also give some dialog with an option to continue but for now it just
fails disgracefully). That's one more reason to be careful with killing.

Function keys
-------------

Various actions are invoked like NC, by function keys. NAC takes
advantage of the fact that the most widely used keyboards now have 12
function keys. But because some keyboards have only 8 function keys,
the actions corresponding to F9...F12 are also mapped to 
Shift-F5...Shift-F8. Currently only the following actions are supported:

* F1 - help
* F5 - copy files
* F6 - move files
* F7 - make directory
* F8 - delete files
* F9 (also Shift-F5) - main menu
* F10 (also Shift-F6) - exit
* F11 (also Shift-F7) - change file attributes
* F12 (also Shift-F8) - rename files by regular expression

A short help for function keys is displayed at the bottom of the window
(if enabled, use Ctrl+B to toggle). It changes the labels to the ones 
corresponding to the Shift-F* when the Shift key is pressed. When this 
happens the color of the line also changes.

Pop-ups in general
------------------

There are two kinds of pop-up windows in NAC, the menus and dialogs. To
reduce the startup time, these windows are not created when NAC starts.
Instead they are created when they are posted for the first time. Because
of this, the first time a menu or dialog is displayed, there may be a small
delay while it is created.

Menus
-----

The menus are menus as usual. There are horizontal menus and vertical
menus. Unlike typical X applications, the NAC menus do not grab the whole 
screen: even if a menu is displayed in NAC, you still can switch to
another application and do something with it. The NAC menus are always
contained within the NAC window. If the NAC window size is too small
to display the whole menu, a scrollbar will be automatically displayed.

A special feature of the horizontal menus is that when scrolling,
the items will be displayed only if they fit fully into the window.
For now this feature does not seems annoying at all and is quite cute.
Maybe I'll change my opinion in future.

The scrollbars are intended primarily for the display purpose. Even 
though they can be used to scroll through the window, the keyboard
navigation is recommended.

The current item in the menu is highlighted with color. Most of the
items have some letter underscored. This letter (either lowercase or
uppercase) may be used as a local accelerator: pressing it would
invoke this item. The common keys for the menus are:

* Esc - unpost the menu
* any mouse button press outside the menu but inside NAC - same thing
* Enter - select the current item
* mouse button 1 press on an item - select this item
* letter that is underscored in an item - select this item

The navigation in the horizontal menus:

* Left - move one item to the left
* Right - move one item to the right

The navigation in the vertical menus:

* Up - move one item up
* Down - move one item down
* Left - move to the next vertical menu left from this one
* Right - move to the next vertical menu right from this one

Some items in the vertical menus have a checkbutton (square) or radiobutton 
(diamond) symbol on their left. These items represent on/off or multiple 
choice. When they are selected, usually just the choice changes but the menu 
is not unposted. They have an additional key:

* Space - select a check- or radiobutton

Some items in the vertical menus have a key combination (accelerator) written 
at their right. Such key combinations work only when no menus nor dialogs
are posted. They do not work from the menus themselves but are displayed
there for informational purposes only. For quick selection in the menus,
use the underscored letters.

Entry fields
------------

There are many entry fields in NAC, mostly in the dialog windows but not
only: for example, the command line is also an entry window. All these
entry fields share the key commands:

* Left - move one character to the left
* Right - move one character to the right
* Ctrl-Left - move one word to the left
* Ctrl-Right - move one word to the right
* Backspace - delete one character to the left
* Delete - delete one character to the right
* Ctrl-Backspace - delete one word to the left
* Ctrl-U - clean the entry
* Ctrl-V - insert the next character verbatim
* Mouse Button 2 - paste the X selection into the current (focused) entry
* Alt-Up - to the earlier value in the history stack (if available)
* Alt-Down - to the later value in the history stack (if available)

There is no key to delete one word to the right.

In some situations the control characters are not acceptable, so some entry
fields won't accept them and would beep if attempted. In these entries
Ctrl-V won't work as well. The control characters are displayed in different
color, as "^" and the canonical character.

When an entry has focus, its cursor is displayed as an inverse block. When
an entry loses focus, its cursor is displayed as underline (which is lower
yet than the "_" character). 

The entry that has focus always receives the text pasted from the X selection
by clicking the mouse button 2, no matter where the mouse cursor points. This
is like the behavior of xterm.

In some cases the entries are provided with default values. These values may
be edited. But if a new character is entered right away, before any editing
or cursor movement key (such as delete or arrows) then the default value will 
be erased and the character would be entered into the empty field.

Some of the entry fields are provided with a history stack similar to the
command line history. An entry field may have a completely separate history
stack or share its stack with the other entry fields that are used to
enter similar values. In this case the stack can be browsed with the
keys Alt-Up/Down.

Scrolled views
--------------

On a few occasions the contents of some file or log is displayed. Such
views can be scrolled with scrollbars or with the following keys:

* PgUp - one page up
* PgDn - one page down
* Up - one line up
* Down - one line down
* Left - one character left
* Right - one character right
* Ctrl-Left - 16 character left
* Ctrl-Right - 16 character right

Dialogs
-------

The dialog windows generally contain some (or none) entry fields and some
buttons. One of them has keyboard focus at a time. The button that
currently has focus is shown surrounded by a trough and hilighted with
color. The entry that that currently has focus is shown with raised relief
and a colored border and a block cursor. The entries without focus are
shown with a thin underscore cursor.

The general keyboard actions available in the dialog windows are:

* Tab - move the focus to the next button/entry field
* Shift-Tab - move to the previous button/entry field
* Enter - (for entries) move the focus to the next button/entry field
* Enter - (for buttons) press the button
* Enter - (for checkbuttons) toggle the selection
* Space (" ") - (for checkbuttons) toggle the selection
* Esc - same as presssing the "Cancel" button (if one is available)
* Left, Right, Up, Down - move the focus between the buttons/entry fields 
  in the specified direction. These keys work this way only if they are 
  not redefined by the current elements for other use. For example, the
  entry fields use the Left and Right keys to move cursor within the field.

A special case is that the last entry field may have focus at the same time
as the "Ok" button, so pressing <Enter> in that entry would invoke the
action. In this case the "Ok" button is shown surrounded by a through but
only the entry field is hilighted with color.

Help
----

The help dialog is simple-minded now: it just shows the README file.
The usual file scrolling keys apply.

File operations in general
--------------------------

These are all operations which do something with the files, for example:
copy, move, delete and others. They have a few common properties discussed
in this section. The words "operation" and "command" are used as synonyms.

Some operations are accessible with functional keys, some are accessible
only from the "Files" menu.

If these operations take a list of files as arguments, they get
this list from the current panel. If some files are selected in this panel,
these files are taken as arguments. If no files are selected, then the
current file in the panel is taken. The entry ".." denoting the parent
directory generally is not allowed to be used as an argument. If no
files are specified (for example, when both panels are closed or when
no files are selected in the current panel and its current file is ".."),
then the operation just silently won't run.

The destination entry fields of the file commands have a history stack
(which is shared for all the types of operations). The stack is browsed
by the usual keys, Alt-Up/Down.

Operations on symbolic links need special consideration. Sometimes the
operations should be done on symbolic links themselves and sometimes
on the files to which they refer ("follow" the links to the actual files).
NAC allows to specify the desired behavior in the command dialogs. The
possible ways to follow the symlingks are:

- Always - follows all the symlinks encountered.
- Never - does not follow any symlinks.
- Top level - follow the symlinks only for the files (or directories) directly
  selected by the user, but do not follow any symlinks in subdirectories.

The default selection of the symbolic link following mode is set for
the value that makes sense and is the most typically expected for each 
particular operation. So if you don't understand what the symlinks mean,
just use the default setting.

If a symlink points to one of its parent directories, following it would
probably cause an infinite loop. So use the "follow always" mode carefully.

An operation may save the list of error and warning messages it produced,
to display the full list after the operation is completed. This is done
by enabling the checkbutton "Log all messages" in the dialogs. The log
is currently displayed in a simple-minded way, this will be improved
later. Be careful with this option: if many errors are encountered, the log 
may grow quite big and eventually run the system out of memory.

The progress of operation is displayed by a percentage bar. Usually the
name of the current file processed and the progress bar for this file
are shown as well when it makes sense. The progress bar for the whole
operation is non-linear. That is, each selected file gets equal piece
of the bar, independent on the file size. So for large files the bar will
grow slower than for small files. The directories also get an equal piece
of the bar, and this piece is divided into equal pieces for the files
in this directory. If there are subdirectories then the dividion repeats.
So the common progress bar is not quite accurate. The reason is to minimise
overhead which would be needed to calculate the progress more precisely.
I prefer faster progress to its more precise representation.

Usually the operations may be stopped by pressing the <Escape> key or
the "Stop" on-screen button in the progress dialog. After stopping the
operation may be abotred or continued, possibly with changed settings.
The operations themselves are done by a helper process while NAC itself
only displays the progress, with some amount of buffering in between.
So after hitting the <Escape> key there may be a small delay while NAC
displays from the buffer the progress that had already happened.

The file operations may run in two kinds of modes:

- Foreground/Background
- Interactive/Unattended

These kinds are independent of each other, and an operation is always running
in one mode of each kind.

When an operation is started it runs in the foreground mode, its progress
is displayed. No other actions can be done in NAC at this time. But it can
be moved to background mode where it would run by itself and not impede
any further activity. For example, this makes sense when copying a large
file to a slow device: there is not much fun in watching how the progress
indicator grows slowly, so just start the copying, move it to background
and do something else until the copy completes. NAC can run up to 10
operations in the background mode at the same time. The progress of 
background operations is still visible but with less detail. The thin line
(yes, the one with tiny numbers) at the top of the window is used to show
this progress. This line contains 10 slots, with each slot able to contain
a background operation. They are numbered 1 to 9 and 0 (with 0 being a
shortcut for 10). The keys to control background operations are:

* <Alt-1>...<Alt-9>,<Alt-0> - exchange the current foreground operation with 
  the one in the corresponding background slot

That includes a few degenerated cases:
 - if this background slot is empty and there is no foreground operation
   running, do nothing
 - if the background slot is empty but there is a foreground operation, put
   this operation into this slot and return to the browsing mode
 - if the background slot contains an operation and there is no foreground
   operation running, bring this operation to the foreground and free this
   slot

These keys are temporary disabled when the operation start dialogs or 
operation log dialogs or any non-operation dialogs are displayed. 

When the background slot is empty, it is black. When an operation runs in
the slot, the progress of operation by painting the completed percentage
of a slot in cyan. If the operation comes to a point where human interaction
is required, the slot becomes red. To continue such a stopped operation
it should be brought to foreground and told what to do (and possibly
returned to background afterwards).

If an operation is running in foreground its whole life (that is, it was never
sent to background), on completion it deselects all the files in the
panel that were successfully processed, leaves the files which encountered
some uncorrected problems selected and reloads the panel (and possibly
the other panel as well). But when a operation is sent to background,
it gets disconnected from its panel, all the selected files in the panel
are immediately deselected and the panel may be used for browsing or
starting other operations. Any changes done to the filesystem by the
background operations are not immediately reflected in the panels, instead
the panels must be reloaded with <Ctrl-R> to see the changes. Once
an operation has been disconnected from its panel, there is no way to
reconnect it back.

On the other hand, the operations may be started in either interactive
or unattended mode. In interactive mode all the errors and suspicious
conditions cause the operation to be stopped, and the user is prompted
for either confirmation (for uncorrectable situations) or directions on
what do to.  The interactive mode is started by the default operation
start or continue dialog button, such as "Copy" or "Continue".
In unattended mode the operation never stops and asks, it tries 
to resolve all the problems silently by itself. This resolution may be done 
in one of two ways: "safe" and "confident". The safe mode is started by
the buttons named like "Skip All". In this mode if NAC has any doubt
about any file, it will rather skip that file than cause damage (such
as delete it or overwrite another file). The confident mode is started
by a button named like "Overwrite All". In this mode NAC supposes that
the user knows what he does and proceeds with the operation even if it
has some doubts (this is like the option "-f" in many Unix commands).

To see the log of troubles encountered by an unattended operation, use
the error log option: the full list of erro and warning messages would
be displayed after the operation gets completed. In the log view dialog
the usual file scrolling keys apply.

The mode may be changed between interactive and unattended at any time,
by stopping the operation and then continuing it in the desired mode.

View and Edit commands
----------------------

These commandis show or allow to edit the contents of a file and are 
applicable only to the regular files. The exact command used to view or
edit a file is determined by examining the file according to the rules
described in what is traditionally called "the extention file". This term
goes from Norton Commander which determined the viewer by the file name
extension. NAC has no its own format for the extension file yet but
as a compatibility measure it can use this file from Midnight Commander
(mc.ext). This compatibility with Midnight Commander will be carried forward 
in NAC forever, even when NAC gets its own extension file.

The file mc.ext has a much more extensible format than the original Norton
Commander's extension file. The format is described in the file itself.
NAC looks for this file in two places, user's local and global:

- $HOME/.mc/ext
- /usr/local/lib/mc/mc.ext

If your have Midnight Commander installed with different paths, these
paths can be configured in the NAC rc file (look in tune.tcl for the
settings "fileprop:" to find the relevant settings). If the local
extension file is present, it completely overrides the global file.
Each time an Edit of View command is invoked, NAC checks whether the extension
files have changed, and if so then NAC re-reads them.

NAC might understand the mc.ext files slightly differently than Midnight
Commander. One possibility is that the Tcl regular expression syntax used
by NAC might be slightly different from the GNU regular expression syntax
used by Midnight Commander (though I don't know if these differences
really exist). Another notable thing is that when a certain rule specifies
multiple actions of the same type (directly or through the "Include" actions),
NAC takes the first of them and I don't know which the Midnight Commander
uses. There may be other minor differences too but for now the compatibility
seems to be pretty decent.

If NAC finds no specific rule in the extension file, it tries to find some
viewer or editor by itself.

For the viewer the rules are:
If the environment variable VIEWER is set, it calls the command $VIEWER with 
the file name passed as an argument. Otherwise if the environment variable
PAGER is set, then the command $PAGER is called likewise. But for PAGER
there is a little twist: if the pager is other than "pg", /dev/null is
passed as the second argument. This is done because the old implementations
of "more" and possibly other pagers too just exit after displaying the
last screen page of a file. Adding /dev/null makes them behave more properly.
If none of these environment variables are defined, "more" is used by default
as the most widespread pager.

For the editor the rules are:
If the environment variable VISUAL is set, it calls the command $VISUAL with 
the file name passed as an argument. Otherwise if the environment variable
EDITOR is set, then the command $EDITOR is called likewise. If none of these 
environment variables are defined, "vi" is used by default.

A different default viewer or editor can be specified in the NAC rc file.
Also the hex dump program used as a filter for mc.ext's clause %view{hex}
can be specified in the rc file. By default it's "hd" but the older
systems may not have it and may require "od -xc" or just "od" instead.

Both for the default selection and for the mc.ext's %var{} clauses
only the original evironment of NAC matters, any changes of the shell
environment withing NAC do not affect the choice of viewer or editor.

The viewer or editor is started in a new job.  The usual job control commands
are fully applicable to it.  After the viewer or editor exits, NAC 
automatically closes its job (but does not completely discard it).
To speed up the start of the viewers and editors, a job is cached for
this purpose between the view/edit commands. That is, when you start
a view/edit command for the second time, the same xterm will be reused
for it. Normally the clearing of the screen in this xterm between the
commands is enough. However if a viewer goes crazy and seriously 
misconfigures the xterm, it may be neccessary to reset the xterm manually -
either from the xterm menu (Ctrl-Button2 pressed with the mouse cursor
in the lower left corner of xterm) or by discarding the job from the
job menu (Alt-Z) and calling the viewer/editor again.

Copy command
------------

As the name says, the primary purpose of this command is copying of files
and directories (with all their contents). 

The first dialog prompts for the destination name for the copying.

If more than one file is selected as operands, the destination must
be a directory.

NAC does a simple check if a recursive copy of directory to itself is
attempted (and refuses to do that). However, that check can be easily
fooled by giving unusual target directory name, for example, containing
".." in its path. This check is designed as a convenient protection
against a typical error, not an attempt to inflict good on people. So if 
you REALLY need to do a recursive copy, now you know how to fool NAC.

Hard links are preserved during copying if possible: that is, if multiple
hard links to the same file are copied, in the resulting hierarchy multiple
hard links to one new file will be created. An exception is if the resulting
links would be located on different filesystems: in this case multiple
copies of the file are created instead of multiple links.

The files' attributes such as ownership, permissions and modification time
may be preserved during copying if the "Preserve Attributes" checkbutton
is enabled. This works like cpio or "cp -p". Otherwise only the file 
permissions are preserved, not including the set-user-ID and set-group-ID 
bits. If the user is not superuser then even with the "Preserve Attributes" 
option the user ID of the files is not preserved, and the set-user-ID
bit is preserver only for files originally owned by the same user.

Move command
------------

This command moves files and directories or renames them, like the "mv"
command does. Hard links are preserved if possible, just like the Copy
command. The files' attributes are always preserved.

The symlink following modes other than "Never" usually make no sense for
the Move command. But they still can be used for special cases.

Make directory command
----------------------

This command creates a directory. If the checkbutton "create intermediate
directories" is checked then all the missing intermediate directories
are created as well (like "mkdir -p"). The permissions of the created 
directories are set to 0755 (minus umask as usual).

If a directory was created successfully and its name was specified
without slashes (/) then the current position in the panel is set to
this new directory.

Delete command
--------------

This command deletes files and directories (with all their contents).
So be careful around it. A confirmation dialog is displayed before NAC
starts deleting anything.

The symlink following modes other than "Never" usually make no sense for
the Delete command. But they still can be used for special cases.

Change File Attributes command
------------------------------

This command allows to change the attributes of the files: identities
of the file owner and group and permissions (also known as mode). If 
some field is left empty, it won't be changed.

The changes to the permissions may be specified in one of two ways:
by entering a value in the field like a chmod argument (both octal
and symbolic formats are supported) or choosing the exact bits
to set or reset as checkbuttons. NAC automatically keeps the values
shown in the text field and in the buttons synchronized with each
other.

If only one file is selected then the initial value of its permissions
field (and buttons) is set to the current permissions of the file.

All the text fields have history stacks associated with them.

Pressing Enter in the text field moves the focus to the next text
field, and after the last one to the start button.

Rename by Regular Expression command
------------------------------------

This command allows to rename files (and directories) using the regular
expressions, like the option -s of pax(1). Up to 3 substitutions can
be done in one pass. The substitutions are performed sequentially, that
is, the second substitution is applied to the result of the first
substitution etc. If the entry fields for some substitution are left empty,
this substitution does nothing. The regular expression and substitution
syntax is the usual Tcl syntax, see regexp(n) and regsub(n) man pages.
Two checkbuttons for each substitution may be used to augment the meaning
of the regular expressions:

Chg All - change all the occurences of the regular expression (in other words,
  do a global substitution), equivalent to the option -all of regsub(n)

Ign Case - ignore the case when matching against the regular expression
  (however no case conversion is done during the substitution itself), 
  equivalent to the option -nocase of regsub(n)

All the regular expression text fields (marked with "Change:") have a common
history stack and all the substitution fields (marked with "To:") have
another common history stack. The empty values are not saved in the stacks.
 
Pressing Enter in the text field moves the focus to the next text
field, and after the last one to the start button.

The Preview button allows to see what would the result of substitutions be
without actually changing anything. Since for the more complex regular
expressions it's not always easy to predict how they are going to work out,
preview is a convenient way to experiment. The list of changes that would
be made by rename is reported in the error log dialog after completing the
operation. Note that this information is reported independently of the
state of the "Log all messages" checkbutton. Since the preview does not
change the actual files, it does not deselect any files. So if the
preview results are satisfactory, you may immediately call the Rename
command again, get the expressions from the history and actually run
the command. This procedure is a bit awkward, but for now it's better
than nothing.

Similarly to the symlink following mode, for this command you can specify
when to descend into directories:

- Always - descends into all the directories encountered.
- Never - never descends into any directories (but may rename the 
  directories themselves).
- Top level - descends only into the directories directly selected by 
  the user, but not into their subdirectories.

The default value is set to "Never".

Also it is possible to rename only files or only directories (or both).
This is controlled by the checkbuttons "Apply rename to", marked as
"Directories" and "Files". By default they both are selected. Please
note that this choice is independent of the directory descent mode:
the descent mode tells whether something should be done to the directory
contents, while the "Apply to" selection tells whether something should
be done to the names of the directories themselves.

One of the typical uses of this command is to mimick the MS-DOS ability to
change the file name extensions (suffixes in Unix terms). In MS-DOS a
command like:

  ren *.aaa *.bbb

would change the extensions of all the files ending in .aaa to .bbb. To get
the same affect with NAC, select the files with pattern

  *.aaa

and then do the Rename by Regular Expression. Enter

  \.aaa$

into the regular expression ("Change:") field and

  .bbb

into the substitution ("To:") field. But this command allows to do much
more than just change suffixes.

Select matching files
----------------------

This dialog provides a fast way to select in a panel multiple files with
the names matching a pattern. The files may be selected, deselected or
toggled: the action is chosen by the radiobuttons in the dialog. For
convenience there are two ways to invoke this dialog: Keypad_Plus presets
the action to "Select", Keypad_Minus prsets the action to "Deselect".
There is no special key for "Toggle", just invoke the dialog either way
and then select the radiobutton "Toggle" in it. For the people whose
keyboard does not have a keypad, the alternative way to get to this dialog
is by pressing Ctrl-Shift-Plus. Shift is neccessary because the "+" symbol
is generated on the US keyboard by the same key as "=" when it's pressed
with Shift. In a keyboard mapping that does not require shifting to get it,
just Ctrl-Plus will be enough.

The pattern may be either a shell-style glob pattern or a regular expression,
selected by a radio button. The glob patterns are matched agains the whole
file names. On the other hand the regular expressions are not anchored,
so for them the match is considered successful if it matches any part of
the file name. The regular expression anchor symbols are the usual "^" 
and "$". See the regexp(n) man page for description of the Tcl regular 
expressions.

By default the directories are excluded from the selections by pattern. But
they may be included by enabling the checkbutton "Directories too".

The type of the pattern and the directory inclusion checkbutton are remembered
between the activations of this dialog. The entry field for the pattern
has a history stack associated with it (can be browsed as usual, by 
Alt-Up/Down).

Job Control
-----------

NAC runs the shell in a somewhat weird mode. The shell thinks that it's not
interactive and does not allow the traditional job control (Ctrl-Z etc).
To compensate for this NAC offers its own sort of job control. In its
model each job gets its own terminal window (xterm, dtterm, hpterm or whatever
you have configured - further collectively referred as "xterm"). So the
whole xterm windows are brought to background and foreground. The switching
is similar to the background file operations (see the section "File operations
in general", you are highly recommended to read that section first):

* <Alt-1>...<Alt-9>,<Alt-0> - exchange the current foreground job with 
  the one in the corresponding background slot

From the user standpoint there is no difference whether there is a shell job
or a file operation in a particular background slot: the switch happens
absolutely similarly and without any special limitations (yes, it's perfectly
legal to exchange a shell job with a file operation in a slot).

The background jobs that have commands running in them, are displayed in the
status line with a 50% progress bar. Those which have their commands competed,
are shown with a 100% progress bar. Unlike the file operations, after a
command is completed in a job, the job does not disappear.

One job is designated as "the main job". The other jobs are called "the other
jobs". The main job is connected to the file panels and the command line.
When a command is started, it's started in the main job. When the panels are
visible, the job shown under them is always the main job. Switching to
an other background job does not automatically make it a main job: even
though it gets to the foreground, it's still just an other job. The commands
running in a foreground other job can be killed as usual (typically by
"Ctrl-C" or "Delete" depending on the system, provided that the terminal
is in the canonical mode). Killing a command does not make its job (xterm
and underlying shell) disappear.

When a background job (or file operation - remember, they are fully equivalent
from the switching standpoint) is brought to the foreground and the main
job has no command running it it, the main job is not shown on the background
status line. In a similar situation but when the main job has a command
running, the main job is placed on the status line and shown in the red
color (the same as a file operation with an error), so that you can identify
and bring it back easily.

If you bring a background file operation to foreground and wait until it
completes (or abourt it), you get automatically switched to the main job.
The same thing happens when you decide to discard (see below on how) an
other job. But if you send a job or operation to a free slot in background
the situation gets a bit more interesting. If the main job is not running,
you get switched back to it as well. But if it's running, you get a dialog
with a choice whether to switch back to the old main job or start a new job 
(then the old main job will become just another "other" job). If you think 
on this choice too long and the command in the main job completes before you 
make a decision, this decision gets ignored and you get back to the old main 
job. 

All this business with a dedicated "main job" may seem silly at first, but in 
reality it greatly simplifies the tracking of the shell environment and
allows to avoid starting extra xterms.

One more important thing is being able to tell if you see the main job or
an other job. This can be told from the NAC window's title (shown in the
window manager's frame around the window). When the main job is at foreground,
the title says "Not A Commander". When an other job is in foreground,
the title is different: it says "NAC:", then the first few characters of the
running (or completed) command, then in parentheses "running" or "DONE" 
depending on whether the command is still running or completed, and
a little help "Alt-Z for menu" (this key sequence was chosen for a mental
association with Ctrl-Z which is usually the job control key).

* Alt-Z - post the other shell dialog

This dialog presents a few actions that can be done on an other job (but
can not be done on the main job, so for the main job Alt-Z won't work).
These actions are:

- Make this job Disappear:
Kills the other job's xterm with whatever is running inside it. After that
switches to the main shell.

- Make this job The Main job (carry its environment):
The current job becomes the main job. The old main job either becomes demoted
to an other job if it has a command running in it, or is discarded if it
has no command running in it. The environment variables are preserved just
as they were in this job (in other words, they are carried with this job
to become the main environment).

- Make this job The Main job (keep the current main environment):
(available only when the command in this job is completed)
Almost the same as the previous action but with one difference: the
environment variables are taken from the old main shell. 

- Make this job Copy environment to the main job:
(available only when the command in this job is completed)
The environment variables from this job are passed to the main job. This
actually works only if the main job has no command running in it.

- Make this job Accept commands from keyboard
(available only when the command in this job is completed)
Gives this job a bit of independency: starts a shell in it. This shell
is completely independent of the panels and the NAC command line. Since
this shell is truly an interactive shell, the traditional job control
works in it. Still the job is controlled by NAC and after you exit from
that shell, another command may be started in it.

- Make this job A separate window
Releases the NAC's control over xterm and restores it back into its separate
window. If currently a command is running in this xterm, xterm will close
automatically after it completes.

If no action is selected before pressing the "OK" button in the dialog,
nothing happens (just as if pressing the "Cancel" button or the <Esc> key).
The idea behind this two-step selection is to avoid doing irreversibe
actions by occasion.

Viewer
======

The viewer `naciew' (that's right, no `v' in it) is presently a rather
experimental prototype. Because of this it's not called anywhere from
NAC, but may be called manually just for fun.

Run

	naciew [options] file

The supported options common with NAC are: -display, -colormap, -use, 
-visual, -sync, -name, -title, -geometry, -font. The geometry is specified 
in pixels.  See the description of these options in the section on
NAC options.

The options specific to naciew are:

	-hex

Enable the hexadecimal dump mode on start-up.

	-wrap

Enable the line wrap mode on start-up.

The main idea behind this viewer is that it must start up fast even on
large files. So it reads the data from the file on demand. That means that
if the underlying file changes, the visible data may change or appear
strange.

Due to the Tcl arithmetic limitations, the viewable file size is limited
to 2 gigabytes. Bigger files may cause naciew to go crazy.

The file name "-" means "read the data from standard input",
this way naciew can be used to view data piped from other programs.
In this "sequential" mode naciew tries to read only a few kilobytes 
ahead of the user-visible part rather than gulping down as much data 
as possible.  Jumping to the end of file with the End key actually jumps 
to the end of this read-ahead buffer but then naciew reads more data ahead,
so that the next jump to the end will jump to the end of the new
buffered data and so on.

Naciew can display the special files (devices) too. The character devices are
always opened in sequential mode. For the block devices naciew tries to 
guess the device size and show them as normal files. This guessing involves
reading the device multiple at varying offsets, so you better don't try
to run naciew directly on a block tape device (though swithing the standard 
input from it is OK). Because the arithmetic in Tcl is pretty much
limited to 32 bits, naciew can show only the contents up to 2G-512 bytes
long, the rest of the file would be invisible.

The users of systems that don't have block device files even for the
fundamentally block devices (such as FreeBSD 4.7) are out of luck for
now. Maybe I'll find some way of dealing with it in the future.

Display modes
-------------

Naciew can display data as either text (ASCII) lines or hexadecimal dump.
The hex mode is enabled and disabled by F8. In the hex mode naciew displays
a multiple of 16 bytes per line, as much as fits within the window. If the 
window is too narrow, naciew reduces the number of bytes per line to 8
or 4. If even 4 bytes don't fit within the width of the window, scrolling
is enabled.

When in ASCII mode, naciew can display the lines either naturally (default 
mode) when each line in the file is displayed as one line on the screen, 
possibly extending past the visible width of the naciew window, or in the
line wrap mode, when the long lines are wrapped at the right end of the 
naciew window and displayed as multiple lines. The wrapping mode
is enabled and disabled by F2. Naciew works slower in the wrap mode.
Even in the non-wrap mode naciew splits the very long lines
(over about 5-10Kbytes). The splitting of the very long lines may vary
between runs.

When switching between the modes, the viewing position is always returned 
to the beginning of the current line.

Line extension markers
----------------------

Naciew displays the line extension markers, with dirrefent meaning
in no-wrap and wrap modes. In the no-wrap mode
if the line does not end withing the right edge of the text window,
the bright character ">" is shown at the right edge of the window.
It's referred to as "the right extension marker".
Similarly, if the line ends beyond the left edge of the screen
(unless the line is empty), the bright character "<" (the left
extension marker) is shown at the left edge of the window. 
Note that the spaces at the end of line count a real characters, 
so if only these spaces are currently visible, then the marker 
won't be displayed even though the line would appear empty. This
is somewhat confusing and should be fixed in future.
In the wrap mode the bright character ">" is shown at the end of each line
that is being wrapped. The bright character "<" is shown in the beginning
of each continuation line.

The position in file
--------------------

Naciew does not calculate the line numbers when opening a file,
but instead does it lazily when the file is actually displayed. So if
the displayed area is jumped to the middle or the end of file, naciew
does its best and shows the line numbers relatively to the offset
of the jump, in format "@byteoffset [+-]line". If when browsing a file
naciew finds that all the files between the current position and the
start of file have been counted, it switches to the absolute line numbers.

The bytes, lines and columns are counted starting from 0.  

In the wrap mode naciew also shows the sub-line number (each physical 
line may be split into many on-screen lines). The sub-line numbers also 
start from 0, and are displayed only when sub-line number is not 0, 
in format "@byteoffset [+-]line.subline".

In the hex mode naciew naturally shows the position in file as an
offset.

Currently if the file changes slightly, naciew may not notice it and 
will not recalculate the line boundaries, so the display will be a bit 
strange. If the file changes seriously, naciew will discard the old
cached contants and load the new contents. When a reload is done, 
naciew tries to keep the present position in the file but may not
always succeed. If the file is removed, naciew switches to treating its
open (and hopefully still valid) file handle as a sequential file
with all the consequences similar to reading from a pipe.

Scrolling
---------

When displaying the scrollbars, naciew tries to do the best guess. 

If the number of lines in the file is known, it calculates the visible
part for the vertical scrollbar as a percentage of the file size in lines. 
If the number of lines in the file if not known, it calculates the visible 
part of the vertical scrollbar as a percentage of the file size in bytes. 
So when naciew finally learns the total number of lines in the file, the
position and size of scrollbar may change a bit suddenly.

When reading a file from standard input, naciew shows the vertical scrollbar 
relatively to the currently read part of the file. 

The vertical scrollbar in the wrap mode (and naturally in the hex mode)
is always calculated by bytes, not lines.

For the purpose of the horizontal scrollbar naciew determines the full 
width of the file as the length of the longest line that was ever displayed 
on the screen.  So as the file is viewed, this width may change and be 
reflected in the new state of the horizontal scrollbar. Single-clicking
on the horizontal scrollbar arrows moves the visible position by 16
columns.

In the wrap mode the horizontal scrollbar does not work since the
wrapped lines always fit within the window width. 

In the hex mode the horizontal scrollbar becomes useable only when the
window is too narrow to display a dump of at least 4 bytes per line. In
this case the clicking on the scrollbar arrows or pressing the Left and 
Right arrow keys moves the screen by one column only.

Keys
----

The keys are:

* F2 - switch between wrap and no-wrap mode
* F8 - switch between hexadecimal and ASCII mode
* F10 - exit
* Home - move to the first line
* End - move to the last line
* Up - move one line up
* Down - move one line down
* PgUp - move one page up
* PgDown - move one page down
* Left - move 16 columns to the left
* Right - move 16 columns to the right
* Ctrl-Left - move one screen to the left
* Ctrl-Right - move one screen to the right
* Alt-Home - move horizontally  to the start of the line
* Alt-End - move horizontally to the end of the longest known line
* Ctrl-L - forcibly reload the file

The other functional keys are marked on the help line but don't work yet.
The keys used for selections are described in the Selectios section.

Selections
----------

For now the selection works very primitively, and don't work in the hex 
mode. No selection with mouse yet, only with keyboard. The keys used to do 
the selctions are:

* F4 - switch the selection states
* Esc - forget the selection
* Up - move the active point one line up
* Down - move the active point one line down
* PgUp - move the active point one page up
* PgDown - move the active point one page down
* Left - move the selection one character to the left
* Right- move the selection one character to the right

The selection starts by pressing F4. A cyan marker appears in the top left
corner of the window. This marker points to the start of the selection. It can
be moved around with the arrow keys. When the marker is positioned at the
desired start of selection, press F4 again. Now the end point of the selection
can be moved around with the arrow keys (it's OK for the end to textually
precede the start of selection), and the selected text is marked wyth cyan
background. Esc switches the state back to positioning the start of selection.
To complete the selection, press F4 again. The selected text gets the
white background, and now it can be pasted with the usual X commands
(such as the right mouse button). Press F4 again to discard the selection.
Pressing Esc in any other state will discard the selection too.

It's OK to switch between the no-wrap and wrap modes in the middle of creating
a selection. Switching to the hex mode will reset the selection.

The current controls for the selections are purely experimental and will be
changed in the future.

Bugs
----

Currently naciew may produce debugging output on stderr.

Debugger
========

The bright yellow dot in the top right corner of the NAC window is the
debugger activation button. It may be not present if the debugger is
turned off. If it is present, the debugger window can be called up
by clicking the right mouse button over that yellow dot (the cursor
shape over it is "right mouse button"). The debugger window allows to
execute any Tcl/Tk commands and see their results, so the understanding
of the NAC internals is required to use it. The results are displayed
in the text widget and the commands are intered in the entry field
at the bottom. The usual history keys work in this entry field.
The debugger window is normally posted over the NAC window, the usual 
window manager controls can be used to switch between them. The debugger
window may be closed and then called up again. The contents of the
results window is lost when the debugger window is closed, but the
history of the commands is preserved. The scroll bars and the keys
PgUp, PgDn, Shift-Left, Shift-Right may be used to scroll the results.
A limited number (currently 1000) of last lines of the results is
visible, the older lines are automatically discarded. A few
special convenience commands are defined for use in the debugger:

echo <args> - write args to the results window (\n is not added)
closedebug - close the debugger window

The same debugger works in naciew too, and is activated by Ctrl-Button3.


A few important things
======================

Don't forget to read the section about broken things.

To exit from NAC press F10 or Shift-F6.

See Also
========

http://nac.sourceforge.net
The home page of the NAC project.

http://sourceforge.net/projects/nac
The NAC page on SourceForge with usual SourceForge services: mailing lists,
CVS (not working yet due to problems with permissions on the CVS server),
organised releases with support of e-mail alarms on new releases, download 
statistics.

http://www.daemonnews.org/199902/fvwm.html
Article on a configuration of FVWM like a text console.