
QTREE Version 1.15   -  User's Guide
------------------------------------

OVERVIEW
--------

QTREE is a simple text-mode file manager for QNX 4.x. Its main
uses are browsing the file system tree, and acting as a front end
to certain common shell commands, such as cp, mv and rm.

QTREE will run on either a QNX console (QNX or ANSI emulation, 25 or
50 lines), or a QNX Windows/Photon/X terminal window. A serial terminal
should also work, provided it is in the terminfo database and it has
cursor keys and an Alt key.

The user interface is along the lines of XTree Gold for DOS. There are
two main screens. The Tree Display shows a graphical representation of
the file system tree which you can move up and down using the cursor
keys. Branches can be expanded ("logged") or collapsed as required.

Selecting a directory leads to the File Display screen. This shows
a scrollable "ls -al" style listing of all files in the directory or
branch.

A limited number of basic file management functions can be performed,
either on individual files or groups of "tagged" files. These functions
include copying, moving, deleting, viewing, archiving and editing. You
can also start a shell from within QTREE.

These functions are implemented using the standard QNX utilities,
which QTREE calls via a shell script (qtree.sh). This script
provides a measure of configurability in that it can be edited to
include your favourite editor or file copier program.

QTREE is controlled by the cursor keys and a series of single-key
commands. Press F1 at any time to display a quick reference guide.


STARTING QTREE
--------------

QTREE consists of two components: the executable (qtree) and a
shell script (qtree.sh). Both should be installed in an appropriate
directory (eg. /usr/bin) so they are accessible via the PATH.

The QTREE usage message is as follows:

qtree [options] [root dir]

    -s{n|s|d|e|u} default file sort criterion (name/size/date/ext/none)
    -d            descend beyond device boundaries when logging
    -cN,N,N,N,N   set colours

For example:
    qtree -sd -d //3/
specifies that the root of the displayed tree is to be "//3/" (default
is "/"), and that the default sort criterion is by date (default is by
name). See the L command below for a description of the -d option.

QTREE uses five different display colours. The -c option allows these
to be customised. Each of the N's above represent a hexadecimal
number - the upper nybble is the background colour and the lower nybble
is the foreground (0=black, 1=blue, 2=green, 3=cyan, 4=red, 5=magenta,
6=yellow, 7=white).

The first colour is the main display colour (default green), the second
is used for filenames and various other data fields (default white), the
third is for headings and some prompts (default cyan), the fourth is
for error messages (default red) and the fifth is for various other
little indicators (default yellow).

The default colours would therefore be specified by -c2,7,3,4,6 whereas
blues fanciers might prefer -c17,13,17,14,16.

Options can also be set using the QTREE environment variable, eg:
  export QTREE='-se -c6,4'
  
  
TREE DISPLAY
------------

The Tree Display screen is divided into 4 separate windows:

1.  The main window contains a graphical representation of the file
    system tree, starting at the root you specified on the command
    line (by default, "/").
    
    For speed, QTREE initially examines, or "logs", only the root
    directory. The tree display will therefore initially consist of
    just the directories immediately under the root.
    
    In normal usage, only that part of the tree in which you are
    interested will be logged. This saves QTREE having to thrash the
    disk getting details on each and every file, and makes it easier
    to move up and down the tree without having to wade through
    dozens of directories.
    
    A cursor can be moved up and down the tree using the arrow keys
    (and PgUp, Home etc.) See below for other commands.
    
    Various symbols may be displayed next to each directory name:
        "+"  - the directory has not been logged yet
        "!"  - you don't have write permission to the directory
        "!!" - you don't have read or write access to the directory
        "[Error]" - some kind of error occurred reading the directory.
            If you move the cursor on to the directory the actual
            error message will be displayed at the bottom of the screen.
        "[sym link]" - the directory is really a symbolic link to
            another directory
    
2.  To the right of the Tree Window is the File Window, which lists
    the names of all files (or all that will fit on screen) in the
    currently selected directory. If the current directory has not
    been logged yet, nothing is displayed here.
    
3.  Along the top of the screen are some statistics on the tree as
    a whole. These include:
        - Total number of files logged so far (of any kind, except
        directories)
        - Total number of bytes occupied by all *regular* files logged
        so far. Note that the space taken up by symbolic links,
        directories, special files etc. is not included in this
        figure. Nor is the "slack space" - the allocated but unused
        space on the end of the last 512-byte allocation unit of each
        file.
        This figure may also not be totally accurate due to files with
        hard links being counted more than once.
        - Total number of "tagged" files.
        - Total space occupied by the aforementioned tagged files.
        - Name of the device associated with the current directory
        (eg. //1/dev/hd0t77).
        - Amount of free space on this device.
        - Total space on this device.
        
4.  The bottom of the screen is used for prompts, and to display
    details about the currently selected directory:
        - Its full name
        - Number of files, and the space they occupy
        - Number of tagged files, and the space they occupy
        
        
The available commands on the Tree Display screen are mostly to
do with logging bits of the tree. The keys chosen are similar
to Xtree, with a few annoying exceptions :-)

NOTE: Although these keys are listed in upper-case here, all commands
      must in fact be entered in lower-case.


ENTER   - LOG/SHOW DIRECTORY
        This performs two functions: If the currently selected
        directory has *not* yet been logged, then log it. If the
        directory has subdirectories, add them to the tree; if it
        has files, show them in the file window.
        
        If the currently selected directory *has* been logged, then
        switch to the File Display screen (see below).
        
        The Right arrow also performs this function, a bit like
        the tin newsreader.
        
L       - LOG BRANCH
        This logs the currently selected *branch*, ie. the
        currently selected directory, and all of its
        subdirectories. If you press L with the cursor on the
        root directory, this will log the entire disk, which
        may take several seconds (or minutes, for slow filesystems
        such as Dosfsys with lots of files.)
        
        This is equivalent to Alt-L, B (log branch) in Xtree Gold.
        
        Note that the recursive logging will not, by default,
        continue down past device boundaries. That is, branches
        handled by a different device to that of the tree's
        root directory will not be automatically logged. Thus if
        you are running Dosfsys and press L on the root directory,
        QTREE will not automatically log the /dos branch.
        
        The -d command line option can be used to override this
        behaviour.
        
        Directories which are symbolic links will also not be
        automatically logged. You can still manually log a symlink,
        but note that if the "real" directory is also logged, the
        statistics displayed at the top of the screen may be inaccurate,
        as some files will be being counted twice.

U       - UNLOG BRANCH
        This "unlogs" the current branch. All information about
        the current directory and its subdirectories is discarded.
        Equivalent to Alt-R, B (release branch) in Xtree.

+       - RELOG BRANCH
        (easier if you use the grey "+" key) This "relogs" the
        current branch. That is, the stored details for each previously
        logged directory in the branch are updated. This is useful if
        you execute a command which changes the state of the filesystem
        behind QTREE's back.
        
        Some file management commands (eg. delete file) do
        automatically relog the current directory, but some don't.
        If you go shuffling files around in a QTREE shell, it would
        be polite to do a '+' on your return, to let QTREE know.
        
B       - SHOW BRANCH
        This switches to the File Display screen, but shows all
        files in the current *branch*, not just those in the
        current directory.
        
        Note that only files in directories which have been logged
        will be shown. Thus if you wanted to see a list of all files
        under /home *except* those in /home/skippy, you would go to
        /home, press L to log the entire branch, then go to
        /home/skippy, press U, then go back to /home and press B.

Alt-L   - LOG TREE
        This logs a whole new tree (initially just the directory at the
        root of the tree), which is kept in memory in addition to the
        current tree. This is handy if you want to look at another node.
        Sort of equivalent to L (log disk) in Xtree.
        
< >     - SELECT TREE
        (actually , and .) These keys switch between different
        trees.
        
Alt-U   - UNLOG TREE
        This unlogs an entire tree, if more than one has been
        logged.

M       - MKDIR
        Creates a directory under the current one.
        
D       - RMDIR
        Deletes current directory, which must be empty.
        
R       - RENAME
        Renames the current directory, using mv.
        
Q       - QUIT
        Does just that.
        
        
FILE DISPLAY
------------

The layout of the File Display screen is similar to that of the
Tree Display. The windows at the top and bottom of the screen show
the same statistics. In the middle is a scrollable list of files,
listed in a way similar to ls -l.

From left to right, the following information is shown for each file:
    - "!" or "!!" flags, with the same meaning as for the Tree Display.
        A red "**" symbol indicates an error.
    - the type of file:
        (blank) - a regular file
        "exe"   - a regular file which has one or more "x" permission bits set
        "link"  - a symbolic link; the file pointed to is shown at the
            bottom of the screen
        "fifo"  - a FIFO (named pipe)
        "char"  - a character device
        "blk"   - a block device
        "spec"  - a named special file
        "sock"  - a socket
    - the number of hard links (if more than one)
    - the file's permission bits, ls -l style
    - the owner of the file (note that to save space the group is not shown)
    - the file's size in bytes
    - date and time of last modification
    - a diamond shaped symbol if the file has been tagged
    - and even the name of the file, too.

Note that if a branch is being displayed (ie. you pressed B rather than
ENTER to get to the File Display), then the statistics at lower right
refer to the *branch*, and are displayed in a different colour to
emphasise the fact that you are looking at a whole branchful of files,
rather than just a directory.


The following commands are available:

ENTER   - RETURN TO TREE
        (also Q or Esc or LeftArrow) Returns to the Tree Display.
        
T       - TAG
        "Tag" or "mark" the current file.
        
U       - UNTAG
        Untag the current file.
        
Ctrl-T  - TAG ALL
        Tag all files in the displayed list, ie. all files in the
        current directory, or all logged files in the current branch.
        
Ctrl-U  - UNTAG ALL
        Untag all files in the displayed list.


The remaining File Display commands are all implemented using the
qtree.sh script. The idea is that after you have selected a file, or
tagged a group of files, QTREE passes the filename(s) and the name
of the command to qtree.sh. The script interprets the command and
calls the appropriate shell command. Thus the qtree executable forms
the front end, and qtree.sh the back end.

There is a slight perfomance penalty here, but the advantage of the
script file is that it can be customised by the user to include
your favourite file viewers, cp options, or even replaced entirely
by a super-duper compiled back-end.

NOTE: All commands are executed from within the currently selected
      directory. When QTREE prompts for a destination file/dir name,
      this may be specified relative to the current directory
      (eg. ../hippo). Note that if a branch is being displayed, the
      "current directory" is the root of the branch, *not* the
      directory of the currently highlighted file.
      
Note also that the shell "~" or "~user" notation may also be used when
specifying a destination file/directory name.
                                               

The commands, and their default qtree.sh implementation, are described
below:

V       - VIEW FILE
        This allows browsing of the selected file. Qtree.sh looks at
        the file extension and runs an appropriate viewer. The following
        extensions are recognised:
            *.tar, *.tar.F, *.tar.gz, *.pax, *.pax.F, *.pax.gz
                - runs pax/melt/gzip
            *.gif, *.bmp, *.jpg, *.pcx
                - runs pv (Photon image viewer) which will only work if
                you're running in a pterm.
            otherwise
                - runs vedit -b (browse mode); you could change this
                to less/more if you prefer

E       - EDIT FILE
        This runs vedit (or whatever you specify in qtree.sh).
        
D       - DELETE FILE
        Deletes the file (using rm) after prompting for confirmation.
        
Ctrl-D  - DELETE ALL TAGGED
        Deletes all tagged files in the displayed list, after prompting
        for confirmation.
        
C       - COPY FILE
        Prompts for a destination (may be a directory or file), prompts
        for confirmation if the destination file exists, then copies the
        selected file using cp.
        
Ctrl-K  - COPY ALL TAGGED
        (Ctrl-C was taken!) Prompts for a destination (must be directory),
        then asks whether you want existing files to be automatically
        overwritten (if not, cp -i is used).
        
M       - MOVE FILE
        Moves/renames a file, using mv.
        
Ctrl-V  - MOVE ALL TAGGED
        (Ctrl-M = ENTER, unfortunately). Moves all tagged files to the
        specified destination directory.
        
Alt-C   - COPY ALL TAGGED, WITH PATHS
        This copies all tagged files to the specified destination, 
        duplicating the directory structure. This is a bit like cp -r
        (recursive copy) except that you can select which files are
        included.
        
        The directories can either be absolute or, if a branch is being
        displayed, branch relative. For example, suppose branch /home is
        being displayed, and you have tagged one file: /home/wally/zippo,
        and you enter "//2/users" as the destination. If you select the
        "absolute" option, the file will be copied to
        //2/users/home/wally/zippo. If you select "branch relative", the
        file will end up as //2/users/wally/zippo.

Ctrl-A  - ARCHIVE ALL TAGGED
        Prompts for the name of an archive file, prompts for confirmation
        if it already exists, then archives and/or compresses the files
        based on the extension of the archive file name. Qtree.sh currently
        recognises the following extensions:
            *.tar, *.tar.F, *.tar.gz, *.pax, *.pax.F, *.pax.gz
        and will run pax, freeze or gzip as appropriate.
        
        Note that the files are stored without pathnames.
        
Alt-A   - ARCHIVE ALL TAGGED, INCLUDING PATHS
        As above, except that full or branch-relative paths are stored in
        the archive, rather than just filenames.
        

Note: Commands which operate on tagged files only affect files which
are (a) tagged and (b) part of the currently displayed file list (ie.
in the currently selected directory or branch). The "Tagged" indicator
at the *bottom right* of the screen shows the number of files which will
be affected.
        

OTHER COMMANDS
--------------        
        
There are a few other commands which work on either the Tree or File
Display screens:

F1      - HELP
        Displays a quick reference guide.
        
F2      - TOGGLE FILES/DIRS
        Normally, directories are specifically excluded from display in
        the file window of the Tree Display, or on the File Display screen.
        
        The F2 command causes this to be reversed: *only* directories (except
        . and ..) are displayed. This allows you to see the permissions etc.
        of directories.
        
        Note that currently most of the File Display commands (tag, copy,
        delete, etc.) are disabled when directories are being displayed.
        
S       - SORT CRITERION
        This command allows you to select one of 5 possible sort orders
        for the Tree and File displays:
            N - sort by name (default)
            S - sort by size, largest first
            D - sort by date, latest first
            E - sort by file extension
            T - sort by tag status, tagged first
            P - sort by pathname (only relevant when a branch is displayed)
        The default sort criterion can be specified using the -s command
        line option, -sd to sort by date. If an invalid letter follows the
        -s, the initial display will be *unsorted* (like ls -f), which may
        be useful in some cases.
        
Shift-A..Z
        An upper-case letter moves the cursor forward to the next
        file/directory whose name starts with the specified letter. This can
        be useful if there's a great long list of files displayed.

Alt-Z   - SHELL
        This starts up a shell, with the current directory set to the
        currently selected directory. Type "exit" or Ctrl-D to return to
        QTREE.

Alt-V   - SHOW VERSION
        This displays the version number of QTREE.



11-May-96
