	       This is the X Desktop Manager Help file.

			Version 2.5 of XDtm

		   Copyright: Edward Groenendaal 1991, 1992
			      Ramon Santiago 1992


Warning: This file is outdated and will be replaced with a HyperText Help
	 widget in the not too distant future.

0. Introduction
===============

The X Desktop Manager is a graphical shell for the X Window system.
It provides facilities to list directories, view files, copy, move,
and delete files, and to launch programs.

A diagram representing the application window is shown below.  At the
top of the window are three pull down menu's, File, Options, and View.
Followed by the directory selector via which you may type in a new
current directory which will be viewed in the directory manager.

The directory manager may display a directory either as icons,
filenames or in a long listing similar to the output of ls -l.

Files maybe selected via the mouse and then operations applied to
them. For example to duplicate a file, the original file is selected
by pointing at it with the mouse. Duplicate File is selected from the
File pull-down-menu. You enter the name of the duplicate and select
File this new file will appear in the directory manager with the
contents of the previously selected file.

The application manager displays a set of programs which may be
launched by double clicking the mouse button while the pointer is over
the desired application. The selection menu lists the set of the sets
of programs available.

The Trash, Move and Copy buttons below the application manager are for
deleting files and directories, Moving files and directories to
another directory, and copying files and directories to another
directory.

 +--------------------------------------------------------------+
 | File  Options View  Goto: directory selector                 |
 |--------------------------------------------------------------|
 | selection menu |                                             |
 |----------------|                                             |
 |                |                                             |
 |                |                                             |
 |  application   |                                             |
 |    manager     |            directory manager                |
 |                |                                             |
 |                |                                             |
 |                |                                             |
 |                |                                             |
 |                |                                             |
 |                |                                             |
 |                |                                             |
 |----------------|                                             |
 |Trash Move Copy |                                             |
 +--------------------------------------------------------------+
                  Figure 1: X Desktop Manager


1. Selecting files
==================

When a file is selected the icon and/or filename representing it in
the filemanager is highlighted by inverting it. When a file is
selected it is available as an argument to another program or to be
moved, copied or deleted.

Files may be selected either via the mouse, regular expression, or all
the files via a key-press.

1.1 Selecting files via the mouse
---------------------------------

To select a file using the mouse, press the first mouse button down
while the pointer is over the file you wish to select. To select more
than one file at a time the modifier key SHIFT may be applied at the
same time as the mouse button in which case any files already selected
will remain so, and the file selected will also be selected.

1.2 Selecting files via a regular expression
--------------------------------------------

Using the 'Select files by template' option in the 'Options' menu the
user may enter a standard UNIX regular expression describing the set
of filenames to be selected. (See section 12 on regular expressions at
the end of this help file)

Example.

	The regular expression "\.c$" will select all C source files
	The regular expression "^#.*#$" will select all emacs auto-save
 	files, (#filename#).

1.3 Selecting files via the keyboard
------------------------------------

If you want to select all the files in the current directory, except
'.' and '..' you may use may press the key 'a' when in the directory
manager window.

1.4 Executing, and Viewing files
--------------------------------

If you double click on a file then depending on the type of file
one of four things will happen, if the file is a directory you will 
change to that directory, if the file is executable it will be executed, 
otherwise you will be prompted whether you want to view the file unless
a command has been linked with this file type in the configuration file,
in that case that command will be executed. 

For example,

If the command "xterm -e sh -c 'nroff -ms !@ | less'" has been associated
with files ending in .ms then whenever one of these files is double clicked
an xterm will appear with the selected file processed by nroff and paged 
by less.

NOTE. User specified commands may only be accessed when in either Long 
      listing or Icon mode. This is to prevent slow down of the Short listing
      mode.

1.4.1 Viewing files
-------------------

To view a file double-click on a plain file then answer View to the
query box. A large text-window with a scroll bar will appear in the
center of the application. Use the scroll bar to move through the
file. Text maybe highlighted using the mouse, then pasted into other X
applications. The text widget also understands some emacs commands:

Control V  - Next Page
Meta V     - Previous Page
Control S  - Forward Search
Control R  - Reverse Search

Look at the documentation for the Athena Text Widget for a full list
of the translations.

If the file being viewed is writable you will be allowed to edit the
it and save the changes via the Save button.

2. Deleting files
=================

To delete files, select the files (or directories) to delete, then
either select the TRASH button under the application manager, or
select the 'Delete files' option in the 'File' menu.

Before the files are deleted the user will be prompted, only if delete
is then chosen will the files actually be deleted.

After the files have been deleted, the directory listing will be
updated. It is possible using the application resource (or command
line option -delay) to set a delay period between the delete and the
update of the directory, this is for machines working over an NFS
network where the update of directories can be slow.

3. Moving files
===============

To move files from one directory to another, select the files (or
directories) to move, then either select the MOVE button under the
application manager or select the 'Move files" option in the 'File'
menu. The cursor will change to a move cursor (a smaller version of
the picture on the MOVE button), change directory to the file in which
you wish to place the files.

Before the files are copied the user will be prompted, only if move
is chosen will the files actually be moved.

After the files have been moved the directory listing will be updated.
It is possible using the application resource (or command line option
-delay) to set a delay period between the delete and the update of the
directory, this is for machines working over an NFS network where the
update of directories can be slow.

4. Copying files
================

The copying of files is exactly the same as the moving of files 
described above.

5. Changing Directories
=======================

To change directories you may either type a new directory in the
directory selector, double click on the directory you wish to enter,
or press the key 'u' on the keyboard to ascend to the above directory
(previous directory in the path).

5.1 Directory Selector
----------------------

To edit the directory in the directory selector move the pointer over
the directory selector text until the pointer changes into a text
insert cursor.

At this point you can do the following:

Press a mouse button - The caret will move to the position of the pointer
Press Control A      - The caret goes to the start of the text
Press Control E      - The caret goes to the end of the text
Press Return         - The directory manager will change directory to
                       the one in the directory selector. It will ring
                       the Bell on failure.
Press Escape         - Clear the text in the directory selector
Press Right Arrow    - Move caret right
Press Left Arrow     - Move caret left
Press Delete         - Delete character to left of caret
Press Backspace      - Delete character to left of caret
Press any other key  - Insert that letter

The input text is passed through the csh for expansion, therefore any
short-cuts available when specifing directories within the csh may also
be used here. For example:

To change directory to the user 'edward' home directory, you would enter
'~edward' in the directory selector followed by Return.

To change directory to a directory which is relative to that of a directory
contained within a shell variable:

where Xroot is equal to /usr/local/X11R4

to change directory to /usr/local/X11R4/bin you would enter '$Xroot/bin' in
the directory selector followed by a Return.

6. The Directory View
=====================

The directory list may show either:

 o Icons        - icons and filenames
 o No Icons     - filenames
 o Long Listing - filenames plus zero or more of permissions, 
   number of links, owner, group, size, modification time, and access time.

The different modes may be selected via the 'View' menu. To set
the long listing options select 'Options' in the 'View' menu.

Note: If you are using xdtm on a network using NIS (yellow pages) then
the lookup time for user name and group may be unbearably slow. If you
wish to fix this yourself look at the Enhancements file in the xdtm
source directory.

7. Mapping a program over selected files
========================================

This option found in the 'Options' menu will prompt you for a command
to execute with the selected files as parameters. The format of this
command should be the same as that used to specify commands for the
selection list (See section 9.2.1).

The program will be run in the background, therefore use of xdtm may 
continue. A bell will sound when the program terminates and if the
dirOnExit application resource is True the directory manager will 
refresh the directory listing.

8. Application Manager Selection Lists
======================================

The application manager controls a number of selection lists, each
selection list contains a number of icons which when pressed will
execute a specific command.

example,

The programming selection list would contain all the programs normally
used by yourself when developing a piece of software. In my case that
list contains, emacs - To edit files, Make All - To recompile files,
Make etags - To re-make the emacs TAGS database, Make clean - to remove
all unnecessary files from the current directory, and gdb - to debug
programs.

The Application manager can only display one selection list at a time
and so to switch between selection lists the selection menu is used. 
The selection menu lists all the available selection lists.

When a command is executed from the application manager it is run
in the background, therefore xdtm may be used in parallel. When 
a program terminates a bell is rung.

Some programs that may be in the selection list expect filenames as
arguments. To execute these commands the user must select one or more
files in the current directory BEFORE double-clicking on the selection
in the selection list. Conversely some commands do not expect
arguments, for these no files should be selected.

9. Configuration file
=====================

When xdtm is executed it expects to read a configuration file. There
are four places it will try:

 o Use the application resource 'Xdtm.configFile' to obtain a file name
 o Use the command line argument '-cf <filename>'
 o Look in the users home directory for the file '.xdtmrc'
 o Look for the system xdtmrc, in a public lib directory.

If all these methods fail the program will terminate.

The configuration file contains two important sections, the icon rules
for specifying which icons are mapped to which filenames and types,
and the selection lists.

The configuration language is a mix between C and csh, but is very
easy to learn even for someone without any previous computer
experience.

Before you can define either the icon rules or the selection lists
xdtm must know where to find the icon bitmaps. At the top of the file
should be a command setting the 'path' through which xdtm will search
for an icon with the specified name. The path should be a colon
delimited list of directories. E.g.

    set path = "/usr/local/lib/xdtm/icons:~/lib/icons";

would tell xdtm to search the directories, /usr/local/lib/xdtm/icons,
~/lib/icons (where ~ refers to my home directory). The
path my be reset at any point in the configuration file, but because
the icons are all loaded while parsing the config file on startup no
runtime speed increase will be noticed.  

Comments may be included anywhere in the file. They are started by a 
hash '#' preceded by either one or more spaces or tabs. The comments 
are terminated by the next newline.

9.1 Icon Rules
--------------

The mapping between files and their representative icons is performed
by a sequence of possibly nested if-then statements. Each 'if' statement
tries to limit the set of possible icons for that filename until there
are no more rules left to apply, in which case that icon will be used.

An if statement may test for the following characteristics of a file:

 1) Is it a directory?
 2) Is it a plain file?
 3) Is it block special?
 4) Is it character special?
 5) Is it a symbolic link?
 6) Is it a fifo?
 7) Is it a socket?
 8) Is it executable?
 9) Is it readable?
10) Is it writable?
11) Does it's filename match this regular expression?

Examples :

if (type==dir) {        if (type==file) {       if (type==block) {
  ...                     ...                     ...
}                       }                       }

if (type==character) {  if (type==slink) {      if (type==fifo) {
  ...                     ...                     ...
}                       }                       }

if (type==socket) {     if (type==exe) {        if (type==read) {
  ...                     ...                     ...
}                       }                       }

if (type==write) {      if (name=="\.tar$") {
  ...                     ...
}                       }

These rules may be nested to any depth. Note. that when checking a
filename the rules in a block are NOT executed top-down they are
executed in the same order as the numbered list above. 

9.1.1 Symbolic Links
--------------------

After a successful match on a symbolic link any rules within that
block refer to the file that the link points to. Note: You *cannot*
nest checks for symbolic links.

Example:

    if (type==slink) {
      set deficon="slink.xbm";
      if (type==dir) {
        set icon="folder.xbm";
      }
    }

    If the symbolic link points to a directory then show the
    icon for a directory, otherwise use the symbolic link icon.

NOTE: System V machines do not have symbolic links, and so this feature
      is not available on these machines.

9.1.2 Checking the path or just filename
----------------------------------------

When checking the name of a file against a regular expression the
match can be applied over the full path of the file or just the file.
This may be set at any point in the file by setting the variable
'checkpath' to either 'True' to check the whole path or 'False' to
check only the filename.

Example:

    set checkpath = False;
    if (name == "\.man$") {
      set icon = "manpage.xbm";
    }
    set checkpath = True;
    if (name == "/man[1-8l]/") {
      set icon = "manpage.xbm";
    }

    The first rule will match any filename ending in .man. The second
    will set the icon to manpage.xbm of any file within a manual page
    directory.

9.1.3 Setting the default icon
------------------------------

Within any block you may set the default icon which will be used if
no other icon has been set within that block. It is often used at
the top of the file in case no rules are matched.

Example:

    if (type == dir) {
      set deficon = "folder.xbm";
      if (name == "^\.\.$") {
        set icon = "dotdot.xbm";
      }
    }

    All directories will have the icon folder.xbm unless they have the
    name ".." in which case they will have the icon dotdot.xbm.

9.1.4 Ignoring files
--------------------
To ignore files you may use the ignore variable, if set within a block 
it takes the place of an icon. When viewing directories in Icon mode
any files that would be matched by that rule are not displayed. This
is useful for ignoring temporary and configuration files.

Example:

    if (name=="^#\.*#$") {
      set ignore;
    }

    Ignore all files which have a filename starting and ending in a 
    hash. (Emacs auto-save files)

9.1.5 Automatically executing programs on icon being double-clicked
-------------------------------------------------------------------
You may specify a program to be executed whenever a file is double-
clicked. The program is specified within the rule for that icon.

For example, to list the contents of an archive produced by ar the
following rule could be used:

     if (name=="\.a$) {
       set icon="archive.xbm";
       set cmd ="xterm -title 'archive contents' -e sh -c 'ar -tv !@ | less'";
     }


9.2 Selection Lists
-------------------

You may define as many selection lists as you like, each list may contain 
an unlimited amount of commands. The selection lists are defined 
using the following syntax:

define "selection name" = {
  {
    name = "Name in Selection List";
    icon = "filename of icon";
    prog = "program to execute";
    options = NSEL;
  }
  {
    ...
  }
  .
  .
  .
}

The name entry of a command is the title given to the icon in the 
selection list. 
The icon is the filename of the icon displayed.
The prog is the program and arguments to be executed when the icon
is double-clicked. 
The options specify whether the program can accept filenames as 
arguments, if it can then just one file, one or more files, or 
zero or more files.

9.2.1 Program specification
---------------------------

The program line must start with an executable program, though it
doesn't have to be a binary (unless the exec on your machine 
doesn't understand the #! notation at the top of scripts). The 
rest of the program line may contain arguments to this program
arguments may be grouped together by inclosing them in single 
quotes. The filenames if allowed will by default be appended to
this program line. If you wish to have the filenames inserted 
at some other point then insert the characters "!@" where you
wish the filenames to be inserted.

Xdtm does NOT understand escaped characters.

When the program is executed it's standard input and output are
redirected to /dev/NULL. This prevents interactive programs from
grabbing the terminal from which you executed xdtm, they will receive
a EOF character as soon as they try to read. You also don't want to
see any output messages from these programs unless they are error 
messages in which case they will be displayed. The program is run 
in the background, this means that you can carry on using xdtm. When
this program terminates a bell will be sounded and if the application
resource dirOnExit is set to True the directory list will be updated.

If you wish to use an interactive program which does NOT have an X
front end you should execute an xterm then execute your program 
within that xterm. 

Example,

prog = "xterm -T 'Test of Xdtm' -e sh -c 'make | tee Make.out | less'"

This command line will execute an xterm with the title Test of Xdtm 
within that xterm a bourne shell will be executed which will in turn
execute make piping the output to tee which will save a copy in the
file Make.out and pipe the rest to less (which stops the xterm dyeing 
as soon as make terminates).	

9.2.2 Options
-------------

NSEL - No filenames may be supplied as arguments. If any files are 
       highlighted when this program is launched an error message
       will be displayed.

OSEL - One filename must be supplied as an argument. If there isn't
       one and onely one file selected when the program is launched
       an error message will be displayed.

MSEL - One or more filenames must be supplied as arguments. If no 
       files are selected when the program is launched an error message
       will be displayed.

ASEL - Zero or more filenames must be supplied as arguments.


10. Command Line arguments
==========================

Xdtm understands all the normal X Toolkit command line arguments, plus

-delay 	<number> The delay between files being modified and the directory 
		 being updated. Number should be between 0 and 5 seconds
-cf <filename>   Use filename as the configuration file.
-dmfont <font>   Use font for in the directory list.

11. Application Resources
=========================

Resource Name   Default         Description
-------------   -------         -----------

viewWidth	85		Width in characters of the view window
viewHeight	25		Height in characters of the view window
mode		icons		Initial mode for directory list 
				one of "icons", "short", "long"
delay		0		Delay between files being modified
				and the directory being updated.
				In seconds, range 0 to 5.	
dirOnExit	False		Refresh dir when a program terminates
configFile	NULL		Config filename
viewFont	6x10		Font when viewing a file
dmFont		*-courier-bold-r-*-120-*   	Font in directory Manager


12. Regular Expressions
=======================

dot '.' 
	matches any single character

asterisk '*' 
	matches any number (including zero) of any single character
	(including a regular expression meta character) preceding
	it.

square brackets '[ ]'
	match any one of the characters inclosed within the brackets.
	A range of characters may be specified by separating the first
	and last character of the range with a hyphen. A circumflex (^)
	as the first character in the list negates the match; i.e. match
	any character NOT in the list.

escaped braces '\{n, m\}'
	matches a range of occurrences of a single character (including
	any regular expression meta character) preceding it. n and m
	are cardinals between 0 and 256 that specify the minimum and 
	maximum number of occurrences to match. e.g. [0-9]\{4,6\} will
	match any number of 4 to 6 digits in length.

caret '^'
	A caret requires that the rest of the expression be matched at
	the beginning of the string.

dollar sign '$'
	A dollar sign requires that the preceding expression be matched 
	at the end of the string.

backslash '\'
	A backslash escapes the meaning of any regular expression meta 
	character so that it has the meaning of a normal character.

14. Files
=========

$LIBDIR/xdtm/help      - This help file
$LIBDIR/xdtm/perm.help - The permissions help file
$LIBDIR/xdtm/xdtmrc    - The system configuration file
$LIBDIR/xdtm/icons     - The system icon bitmaps
~/.xdtmrc              - User configuration file
$BINDIR/xdtm           - executable.

where $LIBDIR and $BINDIR are defined in the imake config files to
be the local library and binary directories.

15. Changes
===========

If you modify part of xdtm and would like this change to be included 
in the next distribution, please send the patch to me. 

If you have an wishes for the future direction of xdtm, please send them
to me and I will add them to the Wishes list.

Also - if you design any new icons (32x32 X bitmaps) for use with xdtm 
please send them to me, I'll be glad to include them in the next
distribution, or if enough are received maybe a seperate distribution of 
their own.

16. Address for maintenance and support.
=======================================

<xdtm@cogs.sussex.ac.uk> or <santiago@fgssu1.sinet.slb.com>

