This is the X Desktop Manager Help file. Version 1.3 for Version 2.5 of xdtm. Edward Groenendaal, January 1992. Lionel Mallet, June 1994. 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 four pull down menu's, File, Options, View and Selection. 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. All the programs of the application manager should be seen as general purpose applications that could be applied to many kind of files. On the opposite, each type of file can be attached a menu of more specific operations. This menu, if any, can be displayed by clicking the right mouse button with the cursor above the selected file icon. 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 Selection 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 'Selection' 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 %s | 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. Note that the ordering of files may be controled by the 'Dir first' option in the 'Options' menu. You can either display all your directories in the top of the directory view, followed by all other files (both lexically sorted). You can also control the way the `.' and `..' directories are displayed. This may be achieved by toggling on or off the 'Use dot spec' and 'Use dot dot spec' options in the 'Options' menu. If for instance you have defined that all directories ending by `.dir' would receive the 'Dir.xpm' icon, and that the `.' directory would receive the 'Dot.xpm' icon, playing with the 'Use dot spec' option will change one icon for the other and reversely. On systems that support them, symbolic links can be displayed differently according to the 'Follow Sym Links' option in the 'Options' menu. If it is set to 'True' (default), the symbolic link is followed and is displayed according to the file it points to. That means that if the symbolic link points to a directory, it would receive the directory icon. If set to 'False', then the description of symbolic links in the configuration file, if any, applies. In this case our symbolic link pointing to a directory would receive the symbolic link icon. Note that you also get the icon menu associated to the icon so directory actions are available in the former case, whereas you get only symbolic link ones in the latter. 7. Mapping a program over selected files ======================================== This option found in the 'Selection' 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. If you wish to, the output of the program can be redirected to an pseudo-terminal window. Click on 'OK in Term' in the Map dialog to select this option. Click on 'OK' if you just want to run the program without seeing its output. 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. When the selection list size does not match the application requirements, the default behaviour is to ring a bell and a display a dialog. This behaviour can be changed by playing with the 'Silent Selection' option in the options menu. The default value is false. When set to true, no bell is rung and no dialog displayed. Rather, depending on the selection list size expected, the action is either executed silently (the program expect no selection and there is one, or the program expect only one file to be selected and selection list contains more than one file - the program is executed with the first file in selection), or not executed at all (the program expect at least one file to be selected and none is). This option is also settable through an application resource (see section 11 below). 9. Configuration file ===================== When xdtm is executed it expects to read a configuration file. There are four places it will try: o Use the command line argument '-cf ' o Use the application resource 'Xdtm.configFile' to obtain a file name o Look in the users home directory for the file '.xdtmrc' o Look for the system xdtmrc in a system lib directory given by application resource 'Xdtm.systemLibDir' o Look for the system xdtmrc, in a public lib directory specified at compile time. 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 mostly inspired by the C language, 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. Any string in the configuration file can contain references to environment variables using the '${VAR}' form. Note that '${' and '}' are mandatory since '$' also have its own meaning in regular expression syntax. 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.icon"; if (type==dir) { set icon="folder.icon"; } } If the symbolic link points to a directory then show the icon for a directory, otherwise use the symbolic link icon. Another way to achieve this is to use the 'Follow Sym Links' option (followSymLinks resource). The latter allows you to avoid duplicating information, in directory specification and symbolic link one for instance. The 'Follow Sym Links' option provides you with some kind of inheritance. If set to True, symbolic links inherit their specification from the object they point to. 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.icon"; } set checkpath = True; if (name == "/man[1-8l]/") { set icon = "manpage.icon"; } The first rule will match any filename ending in .man. The second will set the icon to manpage.icon 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.icon"; if (name == "^\.\.$") { set icon = "dotdot.icon"; } } All directories will have the icon folder.icon unless they have the name ".." in which case they will have the icon dotdot.icon. 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 Specific programs that can be applied to a file ----------------------------------------------------- You may not only specify the icon associated to a particular file but also a list of programs that can be mapped to it. These programs are available through a menu attached to the icon representing the file. This menu is popped up when you click on mouse button 3 with the mouse cursor located above the file. Selecting one of the program listed in that menu will launch the program. The syntax used in the configuration file to describe the ``icon menu'' allows you to specify the complete command launched with its command line. This command line can contain references to components of the file name, i.e., the basename (%b) , the extension (%e) , the path (%p), the file name (%n = %b.%e) and the full name (%f = %p/%n). You can also specify whether that program requires a pseudo-terminal to display its output or not. Example: if (type==dir) { defappl "List" = { { "Ls" : "ls %n", TERM } { "Dir" : "emacs %f", NOTERM } } This will creates a menu containing two lines: `Ls' and `Dir'. When selecting `Ls', the command `ls foo' will be executed and the ouput will be displayed in a pseudo-terminal window. When selecting `Dir', an emacs window is opened with the dir command executed on the file. Omitting the terminal option (TERM or NOTERM) is like specifying NOTERM. Each `defappl' section is separated by a line inside the menu. Pseudo-terminal window is a rather simple interface to stdin, stdout and stderr of the program started. It contains a text widget to display stdout and stderr outputs, a line of text to enter single line input (the input is sent to the program when hitting or clicking on the `Input' label) and 2 buttons: `Interrupt' and `Quit'. The latter cannot be used until the program has been interrupted (by the `Interrupt' button) or has ended. The `Quit' button closes the pseudo-terminal window. 9.1.6 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.icon"; set cmd ="ar -tv %n", TERM; } You can also specify that double-clicking on a file is like using the first program of the icon's menu. the syntax is then: if (name=="\.a$) { set icon="archive.icon"; set cmd-first; defappl "Library" = { { "Contents" : "ar -tv %n", TERM } { "Symbols" : " nm -T %n", TERM } } } 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 "%s" (s like selection) 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 either use the predefined pseudo-terminal window (See 9.1.5) or execute an xterm then execute your program within that xterm. Example, prog = "sh -c 'make | tee Make.out'", TERM or prog = "xterm -T 'Test of Xdtm' -e sh -c 'make | tee Make.out | less'" This last 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 The delay between files being modified and the directory being updated. Number should be between 0 and 5 seconds -cf Use filename as the configuration file. -dmfont 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 termWidth 85 Width in characters of the pseudo-terminal window termHeight 10 Height in characters of the pseudo-terminal window mode icons Initial mode for directory list one of "icons", "short", "long" options 32 options setting for "long" listing mode (PERMS = 2, NLINKS = 4, OWNER = 8, GROUP = 16, SIZE = 32, MODTM = 64, ACCTM = 128) 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 dirFirst True Display directories first bellOnExit True Ring bell when a program terminates scrollOnExit False Rescroll up dir when a program terminates confirmAction True Ask for confirmation when exiting bellOnWarn True Ring bell in case of error useDotSpec False Use the dot specification for `.' instead of that used in the `..' directory useDotDotSpec False Use the dotdot specification for `..' instead of that used in the `../..' directory followSymLinks True Follow symbolic links to choose their icon silentSelection False Silently try to execute application even if selection list size mismatches systemLibDir NULL Relocatable Xdtm library directory configFile NULL Config filename viewFont 6x10 Font when viewing a file termFont 6x10 Font inside a pseudo-terminal window dmFont *-courier-bold-r-*-120-* Font in directory Manager These default values are those specified in the program. Look at the application default file to know the default values on your system. 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. Note that since '${VAR}' syntax is allowed in regular expressions to access environment variable VAR, a pattern containing '${' is hard to obtain. It could though by using an environment variable whose value is '${'. I can't see any case where such a pattern might be useful and hence don't see this limitation as a hard one. 13. Thanks ========== Thanks to the following people who sent me bug reports, suggestions, patches etc.. (not in any particular order) Didier Fort, David Byers, Andreas (the Imake man), Christos Zoulas, Brett McCoy, Bill McLean, Johan Vromans, Johan Widen, Gustaf Neumann, James Beal, Harald Vogt, Hugues Leroy, and Henry Thomas. And a special thanks to Alix Courtney for designing all the pretty icons in the directory alix. And Jean-Christophe Collet (jcc) for Porting xdtm to straight SYSV machines. Correcting loads of buggets Adding the 'set cmd' directive for the directory manager. & testing all releases of xdtm on system 5 machines.. And Frank Wuebbeling for Making the view file option terrific. Adding capability to use ~username Highlighted files are added to the cut buffer. And Jon-Abbey for Adding the process handling stuff Adding the file permissions stuff And other things here and there. And Ramon Santiago for Taking over maintenance of Xdtm. And Lionel Mallet for Adding the icon menu and pseudo-terminal stuff. Fixing so many xdtm-2.4 bugs. Integrating the Xpm support from R. Santiago's version. And myself for wading through all these patches and turning them into xdtm V2.0 - even if it did take nearly a year to do. And many others who have helped by reporting, fixing, suggesting, ... 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. $LIBDIR/xdtm can be overriden at run time using the 'Xdtm.systemLibDir' resource. This makes xdtm more ``relocatable''. 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. Addresses ============= Edward Groenendaal (no longer involved in Xdtm) BT Tymnet Europe. OR Ramon J. Santiago Pencom. Lionel Mallet Simulog.