Navigator creates and manages directory hierarchies. Navigator is similiar
in spirit to OpenLook/Macintosh/PCTOOLS/XTree/Norton Commander/ etc. 
It has proven to be very useful when working in large directory hierarchies. 
At least two archive managers are using this program on truly gigantic trees.

Navigator presents you with a directory tree. 
	root
	   child
               grandchild
           child
etc.
The current path is constructed from the contents of the lines,
e.g. root/child/grandchild etc.

Shells cd'ed to a directory can be created. Compiles and Debugs can then
take place in that directory. If you use Epoch, multiple compile/debug
sessions can be localized in screens.

The current directory can be ls'ed. From the listing, a file find or a shell
command with current file as last argument can be done. You can climb
up or down the tree within the listing.

Shell+Directory listing pair
can be created. Current directory for this pair can be changed from the navigator.
It is also possible to continuously track the navigator current
directory. The pair will also follow any directory changes within the
directory listing.

Shell commands  can be invoked on the navigator current directory. M-x
commands in the navigator window will make the buffer directory equal
to navigator directory. Thus, M-x add-change-log-entry will create
a change log in the current directory in the navigator tree.

Multiple navigator tree buffer/screens can simultaneously exist.

With Epoch, navigator can use the mouse for directory listings, file
finds and tree traversal.

Navigator simply constructs full paths from the string contents.
The string themselves can be paths, ange-ftp style names for remote
machines, or whatever else you choose, as long as find-file
understands the constructed path.

For its shells, Navigator uses 2 'cmushell' modifications.  The 'multi-shell'
creates multiple shell buffers. There is another modification called 
'tracking-shell' When invoked from a buffer,
tracking-shell cd's to that buffers directory. Only one instance
of the shell need be kept around - every time you invoke the shell
a "cd" gets sent to the shell.

Usage scenario:
       Use the directory listing/tree for quick find files. You no
       longer have to type full paths, or search for a file already in
       the required directory.
       At various places in the directory hierarchy, open 's' shells
       (With epoch, the 's' shells will be multiple windows)!!!
       Do compile - gdb etc. in these shells.
       In files, use 'tracking-shell' to quickly do something in that
       directory. 
       Keep a navigator tracking-shell around when trying to locate
       things by grepping. Navigator tracking is especially useful
       with vanilla emacs.

The directories can be expanded in place if you create additional
directories. The buffer can be edited to remove directories, or for
that matter to add them. 


Setup:

The first time:
     
     Set nav-hierarchy-dir to the directory you want the directory
     hierarchy files to reside in. 
     That it is the first time is determined by the non-existence of 
     nav-hierarchy-dir. If nav-hierarchy-dir is ~/tmp/foo, then ~/tmp
     must exist. That is, navigator will not create an entire path,
     only the last directory. Default for nav-hierarchy-dir is
     ~/emacs/hierarchy. ~/emacs should exist if you use the default.

     Type M-x navigator.

     You will be asked for the root directory of the directory tree, the 
     depth and a file to save the hierarchy in. After this a buffer in
     navigator mode will pop up with the tree.
     
     If you use Epoch, you will get a message telling you that screen has
     no size and position info. You may now move the screen with the directory
     to some convenient place and save using C-xC-s to remember the
     screen info. If you do not want this feature, set
     nav-remember-screen to nil.
     
     *NOTE* The directory hierarchy is created using find + awk. 'find' does
     not go through symlinks. The root, however, may be a symlink.
     This script is defined in nav-read-dir-tree-command.
     
     *NOTE* You may find it useful to simply create a one-level-deep
     tree and then manually edit it as you go along. See below.

     *NOTE* If the tree you set up is gigantic, the emacs limits such
     as max-specpdl-size, max-lisp-eval-depth etc. must be increased.
     The alternative is to create a small hierarchy by limiting
     the levels. Check the format used, and write a script to create a
     full directory listing in the correct format. If you do this, please
     send me the script.
     
Normal use:
	
	Type M-x navigator and specify the correct hierarchy file.

Editing:

	Type e in the navigator buffer to edit the listing. Any normal
	emacs editing may be done. The tab-to-tab-stop is set so that
	you set up a correct tree.

	I find it useful to create a 1 level deep tree, and then fill
	it manually as I go along over several days.

	The individual lines should be correctly indented - default 4
	spaces. They should not end in slashes (/), since navigator
	constructs paths by adding /'s to components. The navigator
	will chuck them away in any case. Only the root as / is allowed.
	
	Type C-c C-c to get back to navigator mode. One of these days
	I'll change it to use recursive edits.

File format:

The hierarchy file for

/
    usr/local
    	include
	man

Looks like

(setq nav-hierarchy
'(("/"(
    ("usr/local"(
        ("include")
        ("man")
        ))
    ))
))
(setq nav-screen-geometry "19x9+2+715")

i.e. ((root list-of-children)) recursively.

The screen stuff is for epoch.

Stuff from C-h m about usage, customization etc.:

   "Navigator creates and manages directory hierarchies. Navigator is similiar
in spirit to OpenLook/Macintosh and PCTOOLS. It has proven to be very useful 
when working in large directory hierarchies. 

The hierarchy is presented as
	root
	   child
               grandchild
           child
etc.
Currently, there must be one and only one root.

The cursor points to the current navigator directory. At the current directory:

Type f or C-xC-f   find file in current directory.
	( Dired can be popped by f RET ).
Type s to pop up a shell with cd set to the current directory.
Type t to pop up a shell + directory listing which can track the current directory.
Type t again on a different directory to track further.
Type c to run a shell command on the current directory. You may also
 use M-x shell-command.
Type d to get a quick directory listing.
Type x to expand the current directory in place.
Type e to edit the navigator buffer to quickly insert/remove directories.
Type C-xC-s to save the navigator data structure in a file
Type y to make navigator buffer directory same as current. Not terribly useful,
 since M-x commands will automatically change the current directory, as will
 the directory traversal commands.

Type j to traverse sibling upward .
Type k to traverse sibling downward.
Type l to go to children.
Type h to go to parent.

Type ? to get this message.
Type \\[navigator-introduction] for a detailed intro.

Type \\[tracking-shell] in a buffer to get a shell cd'ed to buffer dir.

In a directory window:
	Type f or C-xC-f to find file
	Type c to run a shell command on the current directory.
	Type k to run shell command on current directory with current file arg.
	Type C-xd to get dired window on current directory.
	Type d to go down the current directory
	Type u to go up, or go to the \"Parent\" and type d.
		The parent directory is most useful with a mouse.
        Type r to refresh, or type d on the refresh directory.
	
	If this directory buffer is a tracking shell/ls pair, the shell will
	also change directories with d,u etc.

If running epoch:
	Control-mouse-left to in navigator get quick directory listing.
	Control-mouse-middle in navigator to get tracked shell and ls
	Control-mouse-left in directory window to find that file.
	Control-mouse-middle in directory window to go down a directory.
	Use the parent directory to climb up, refresh to refresh current
        	listing.

Customisation variables: (default in parens)
navigator-mode-hook   (nil)
nav-indent-value      (4)
nav-hierarchy-dir     (~/emacs/hierarchy) ;; must set after (load \"navigator\")
nav-track-ls-and-sh   (t) ;; track directory listing and shell or just shell
nav-track-continually (nil) ;; track with every key movement
nav-ls-new-screen     (t) ;; separate screen for ls (epoch only)
nav-ls-file-separators ( \\t\\n@/*) ;; Unix specific
nav-remember-screen (t) ;; remember screens size and location. Long skinny screens
			can be used. (epoch only)
list-directory-brief-switches (\"-CF\") ;; Normal emacs variable for brief
			directory listing used by navigator-ls

Default keymap:

\\{navigator-mode-map}"