# The jbrowser File Browser

## Note

This document has been converted with minimal editing from the documentation for version 3.6/2.0 of the `jbrowser` file browser, so it's a little out of date, and it's not organised the same way as current documentation for the other jstools applications. Not much has changed since that version, however. (In the near future, I anticipate a major rewrite of `jbrowser`, supporting multiple windows and multiple directory columns in each window in the style of the NeXTSTEP file manager.)

## Introduction

The `jbrowser` application is a configurable directory browser. It lets you navigate through directories and manipulate files in various ways. It has a mechanism for distinguishing different kinds of files based on their names, so that for instance it will use different underlying Unix commands to print a DVI file and a plain text file.

It is written in `wish`, an X Windows scripting language based on the Tk toolkit and the Tcl scripting library (all three by John Ousterhout of Berkeley), and this makes it extremely easy to customise. You can tell it what tools to use to work with various types of files, and you can change the user interface (e.g. adding new menus) if you like. Nevertheless, the default behaviour is reasonably flexible - you don't need to configure it to use it.

The `jbrowser` directory browser is distributed as part of the jstools package.

This help file describes `jbrowser` version 3.6/2.0.

## Invocation

Usage:

`jbrowser` [directory]

To start the browser, just type ``jbrowser`' at the shell prompt, assuming it's in your path. The browser will start up displaying the current directory. You can also specify a particular directory on the command line, if you want the browser to start up somewhere else. For instance, if you type ``jbrowser /`', the browser will start up in the root directory.

## Working with Directories

### Viewing Directories

The main browser window lists the files in a particular directory. This starts out being the directory you were in when you started the browser (or a directory you specified on the command line). If there are more files in that directory than you can see at once, you can use the scrollbar to scroll up and down.

Subdirectories in the current directory are listed with slashes following them. To move into a subdirectory, just doubleclick it. The browser listing will update to show the contents of the subdirectory - now the new current directory.

### Moving Among Directories

To move up a level - back to the parent directory of the current directory - you can either doubleclick on the two dots (``..`') that appear at the top of each directory listing, or choose `Up' from the `Browser' menu.

The `Browser' menu also has two other directories listed - your home directory, and the root directory (``/`'). You can choose either of these to move quickly to the given directory.

The `Change Directory...' command under the `Browser' menu puts up a panel asking you for a directory name and goes to that directory.

While you're typing a directory name for the `Change Directory...' command, you can use the Tab key to expand the directory name you've started typing as much as unambiguously possible. Essentially, you can abbreviate directory names by pressing Tab at the end of the `abbreviation'. (The Tab key works this way in the panel for the `Move' command, as well.)

### Creating Directories

To create a new subdirectory in the current directory, use the `Create Directory...' command from the `File' menu. You will be prompted for a name for the new directory.

## Viewing and Editing Files

### Viewing Files

To view a file, doubleclick on it. (Doubleclicking on a directory moves to that directory, but doubleclicking on a file lets you see the contents of a file. (Alternatively, you can select a file in the browser listing and choose `View' from the `File' menu.) Normally, this will pop up a text window that shows the contents of the file. Some kinds of files can't be viewed by the browser, however - for instance, if you doubleclick on a tiff image file, whose name ends in ``.tiff`', you'll get an alert message telling you the browser doesn't know how to deal with image files. (You can, however, view compressed files.)

You can customise the browser so that it knows how to display different kinds of files - you might want to use one program to display text files, for instance, and another to display graphics data. This is described under Customising the Browser.

### Editing Files

To edit a file, select it in the browser (singleclick on it) and choose `Edit' from the `File' menu. The file will normally be opened with the `jedit` text editor (also part of the jstools package). As above, there are some kinds of files that the browser doesn't know how to edit by default, and you can customise the browser's behaviour to your liking.

## Processing Files

To process a file, choose `Process' from the `File' menu.

Processing a file means performing some sort of action on it appropriate to the type of file. (This only works with certain types of files.) For compressed .Z files, this means uncompressing them; for files that end in .tex or .latex this means running the `tex`(l) or `latex`(l) commands on them, and for files that end in .tar, this means extracting their contents with the `tar`(1) command. For files named Makefile or makefile (or Makefile.sun, etc.) this means using them to run the make(l) command. As with other commands, you can customise what the browser does to process different kinds of files, as described under Customising the Browser.

The keyboard equivalent for `Process' is Meta-u; you can remember this by thinking that it means to use the file for something.

## Printing Files

To print a file, select it in the browser and choose `Print' from the `File' menu. This will normally use the `lpr`(1) command to print the file. (For .dvi files - TeX output files - it will use the `dvips`(l`)` command, if it is installed at your site.) As with other commands, you can customise the behaviour of the `Print' command as described under Customising the Browser.

You can select a printer using the Global Preferences panel, described under Preferences; the default printer is `lp`.

## How the Browser Knows What To Do with a File

In general, the browser distinguishes different kinds of files based on their extensions - the part after the last period in the name (if any). For instance, it knows to treat compressed files differently from normal files because the names of compressed files end in .Z. By default, the browser doesn't know about very many different kinds of files, but you can customise it to distinguish the kinds of files you normally work with. For instance, you can have it use two different editors to edit Fortran code and C code, or different programs to view PostScript images and TeX output.

(Actually, you can have the browser recognise file types based on any pattern in the pathname, not just the extension. For instance, by default the browser knows that any file whose name starts with Makefile or makefile should be processed with the `make`(1) command.)

## The Browser Menu

In addition to the commands for changing directory mentioned in Working With Directories, the `Browser' menu includes the following commands:

### Help

The `Help' command displays this help file. (It uses the `jhelp` command, so in order for it to work that command must be installed on your system and in your path. The help file must also be installed, or be in the current directory.)

### About the Browser...

The `About the Browser...' command displays an information panel with copyright and redistribution information. The panel also lets you get more information about the author, and about the Tk/Tcl scripting environment.

### Global Preferences...

Browser Preferences...

These commands bring up Preferences panels, described under Preferences.

### Issue Tcl Command...

This brings up a panel that prompts you for a Tcl command to be executed. This is an advanced feature intended primarily for use in designing and debugging configuration files; it's not normally useful for editing files.

### Issue Unix Command...

This brings up a panel that prompts you for a Unix command to be executed. If the command produces any output, it will be displayed; otherwise you'll see a notice to that effect. If there are any errors in the execution of the command, you'll see an error dialogue box with the error message returned by the command.

### New Browser

If you choose `New Browser' from the `Browser' menu, a new browser will be started. (This is a separate process, not just another window of the same process.) You may find it convenient to have more than one browser on the screen at once if you're working simultaneously in more than one directory.

### Refresh

If you choose `Refresh' from the `Browser' menu, the browser will reread the contents of the current directory, and redisplay them. This is useful, for instance, if you've created or deleted some files in the directory using some other application, so that what the browser is displaying no longer corresponds to the current contents of the directory.

The keyboard shortcut for `Refresh' is Control-l (lowercase L), by analogy with the Emacs and `vi`(1) refresh commands.

### Quit

To quit the browser, choose `Quit...' from the `Browser' menu. (By default, you're asked to confirm; you can turn this off from the Preferences panel.) If you have multiple browsers on the screen at once, this only quits one of them - you have to quit each one separately.

## Getting Information about Files

If you choose `Get Info...' from the `File' menu, you'll see some information about the selected file or directory. This includes the output of the command ``ls -l`', which tells you the size, ownership, and permissions of the file, and the output of the `file`(1) command, which tells you what kind of file the system thinks it is. For text files, you'll also see the first few lines of the file.

## Deleting, Copying, Renaming, and Moving Files

### Deleting Files

You can use the `Destroy' command under the `File' menu to delete the selected file or directory. (By default, you're asked to confirm that you really want to destroy it; clicking `OK' or pressing Return will do the deed; you can click `Cancel' if you think better of it. You can change this using the Global Preferences panel.)

### Moving Files

You use the `Move...' command under the `File' menu both to move a file (or directory) into another directory. It pops up a dialog box asking you to move into the directory you want to put the file in. When you have done so, click `Here' to move the file. (By default, you're asked for confirmation. As with `Destroy', you can turn that off through the Global Preferences panel).

### Renaming Files

You use the `Rename...' command under the `File' menu to rename files (and directories). It pops up a dialog box asking you to type a new name. (By default, you're asked for confirmation. As with `Destroy', you can turn that off through the Global Preferences panel.)

Both the `Rename...' and the `Move...' command use the Unix `mv`(1) command, so they can both be used to move files. (The `Move...' command can't be used to rename a file because it only lets you specify directories.)

### Copying Files

To make a duplicate copy of a file, select it and use the `Duplicate' command under the `File' menu. The new copy will be called `copy_of_`filename. You can then select the new copy and use the `Move...' command to name it whatever you like.

## Miscellaneous Commands

The `Misc.' entry under the `File' menu is a submenu that lets you process files in some particular ways.

The `TeX File' and `LaTeX File' entries let you run TeX or LaTeX on a file; this is useful because LaTeX files are usually named with just a .tex extension, so the browser can't tell from the extension whether to use TeX or LaTeX to process a file.

The `Edit with ``jedit''', `Edit with ``xedit''', and `Print with ``lpr''' commands serve a somewhat similar function. They let you open a file with `jedit` or `xedit`(1X11), or print it with `lpr`(1), no matter what the extension of the file is. So if you have a file that happens to end in .Z, but it's really a text file and not a compressed file, you can read it into `jedit` using the `Edit with ``jedit''' command. These commands also let you override customised ways of editing or printing particular kinds of files that you may have added.

`Compress File' lets you run the Unix `compress`(1) command to compact the selected file. The file will then need to be uncompressed (typically by using the `Process' command) before you can work with it again.

`Tar Directory' lets you use the `tar(`1) command to make an archive of the selected directory. (Note that it archives the selected directory, not the current directory.)

`Run ``make'' in This Directory' lets you run the `make`(1) command; it's a shortcut for processing the makefile.

## Keyboard Shortcuts

Many of the commands have keyboard shortcuts, which normally appear in brackets beside the menu entry. To invoke such a keyboard shortcut, hold down whatever the Meta key is on your keyboard, and press the key in brackets. (The Meta key is labelled differently on different keyboards; it may be marked `Meta', `Alt', `Mod', or something else. On current Sun keyboards, it's marked with a little diamond.)

A few of the keyboard shortcuts don't use the Meta key. For instance, the Tab key (to go to a typedin directory) and the Return key (to browse the current file or directory) don't require the Meta key. Another special shortcut is Control-L for the `Refresh' command, indicated as ^l.

The arrow keys can be used to navigate in the browser. The up and downarrow keys move the selection up or down. (If there is no selection already, they will select the last or first file in the browser, respectively, not counting the `../' at the top). The leftarrow key moves up one directory level, and the rightarrow key moves into the selected directory (or views the selected file).

A few keystrokes have special functions in dialogue boxes. Generally, pressing Return will do the same thing as clicking the default button, often `OK' . (To remind you of this, the default button is displayed with a little sunken rectangle around it.) Pressing Control-c, Control-g, Meta-q, or Meta-period will normally do the same thing as clicking the `Cancel' button.

In the dialogue boxes that ask for a file name, pressing Tab will complete a partiallytyped filename as much as possible, as in Emacs and the `tcsh`(l) shell.

## Preferences

Two preference panels, available under the `Browser' menu, allow you to change the lookandfeel of the file browser.

The Global Preferences panel lets you set preferences that apply to all the jstools applications (such as `jedit` and `jdoc`), and any other Tk applications that choose to honour them. The Browser Preferences panel lets you set preferences that only apply to the `jbrowser` application itself

On both panels, clicking `Save' will save the currentlydisplayed preferences, so they'll be used the next time you start up `jbrowser` (or another application), while clicking `Done' won't save them for future use, but will apply them to your current editing session.

### Browser Preferences...

The Browser Preferences panel lets you customise the appearance of the scrolling list that lists the contents of the current directory, and the amount of information displayed in it.

If `Long file listings' is selected, you will see some of the permissions on the file and its size, as well as its name. (If you do this, you may want to make the browser wider than the default 20 columns.) I owe this option to Paul Raines `<raines@bohr.physics.upenn.edu>`. His version was more versatile, also displaying the modification date of the file; I removed that part because it depended on extensions to the Tcl package that aren't part of the standard Tk distribution.

The `Font:' field lets you choose what font is used to display the contents of the browser's file list. You can type in an X font specification, or click the `Choose...' button to select a font visually using the `xfontsel`(1X11) application. (Use `xfontsel`'s menus to choose a font based on its various attributes, such as size and weight, and click `xfontsel`'s `Quit' button to enter the font you have chosen into the browser's `Font:' field.) You can click the `Default' button to set the font field to ``default`', which means to use the X default font (using the X default specification ``Tk*Font:`'), or 12point Courier if there is no X default. See the man page for the X server for more information about X font specifications and X defaults.

The `Width:' and `Height:' fields let you change the default width (in columns) and height (in characters) of the browser.

Browser preferences are saved in the file ~/.tk/jbrowser-defaults.

## Customising the Browser

The `jbrowser` application is built on the Tk application toolkit, a wonderful X Windows scripting toolkit by John Ousterhout of Berkeley, and that in turn is built on his Tcl scripting language.

In addition to the lookandfeel customisation you can do through the preferences panels, described under Preferences, you can customise the way the browser works by creating a configuration file called jbrowserrc.tcl in a subdirectory named .tk in your home directory, and putting appropriate Tcl code in it. Although you have access to the full power of Tcl in your configuration file, and you can change the behaviour of the browser in arbitrary ways, the most common thing to do in a configuration file is to redefine one or more of the following four procedures:

`jbr:cmd:view`

jbr:cmd:edit

jbr:cmd:process

jbr:cmd:print

These procedures are called whenever the browser tries to view, edit, process, or print a file. The default versions of these procedures don't know how to distinguish very many kinds of files; by redefining them, you can both change what the browser does with a particular type of file and add new behaviours for new file types.

There's a certain amount of Tcl code that has to be in any of these procedures; the central part is a table that lists patterns to match the file name against, and corresponding actions to take. This is the part you can customise.

Here's an example:

`##################################################`

# jbr:cmd:view - view contents of a file

##################################################

proc jbr:cmd:view {} {

foreach i [getfiles] {

if {![file isdirectory $i]} {

case $i in {

{*.dvi}

{exec xdvi $i &}

{*.tiff}

{exec xtiff $i &}

{*.tar.Z}

{tkb_more {Uncompressed archive contents} \

[exec zcat $i | tar tvf -]}

{*.Z}

{tkb_more {Uncompressed file} [exec zcat $i]}

{*.tar}

{tkb_more {Archive contents} [exec tar tvf $i]}

{default}

{tkb_more "Contents of `$i'" [exec cat $i]}

}

} else {

j:alert "`$i' is a directory."

}

}

}

(This example assumes that you have X applications `xdvi` and `xtiff`, which can display DVI and TIFF files, respectively.)

The part you can change is the listing of file types (shelltype filematching patterns enclosed in braces) and corresponding actions (Tcl commands, also enclosed in braces). Note the way you execute an X application, like `xdvi` in the first pair:

`{exec xdvi $i &}`

The `$i` will be replaced with the file name. You need an ampersand at the end to put the `xdvi` in the background so you can continue to work in the browser. Otherwise you'd need to kill `xdvi` before the browser would respond to the mouse again.

The last pair, matching the pattern `{default}`, will match if no other pattern does. This example demonstrates how to display the output of a terminaloriented Unix command, using `tkb_more`. Note the funny syntax.

You can also define a procedure `jbr:userhook`. If you create it, this procedure will be called after the browser window is created. This is where you should ad menus or buttons or otherwise alter the userinterface. (The file ~/.tk/jbrowserrc.tcl itself is read very early on, before the window is created, so you can't add to the userinterface directly there.)

If `jbrowser` was installed properly at your site, the directory /usr/local/lib/jstools/samples should contain some example files which you can copy and rename appropriately and modify. You may also find it useful to look at the `jbrowser` script itself, and for information about Tcl syntax you should consult the Tcl and Tk man pages.

(Another, comparatively minor, way you can customise the browser is through the file `~/.textbindings.tcl`. If it exists, this file will be read after your preferred keyboard bindings are set according to the Global Preferences panel. This file lets you modify keyboard bindings for text widgets and entry fields. Since the file browser doesn't have large text areas you can edit, though, this won't affect it much.)

## Changes, Bugs, and Future Directions

### Note

This section, like the rest of this document, hasn't been updated for the current version of `jbrowser`.

### Known Bugs and Misfeatures

* When you use the arrow keys to navigate a large directory, the browser won't scroll to keep the selected file visible.

* The text bindings configuration file should be in the ~/.tk directory, like all the other configuration files.

Feel free to report bugs to `js@aq.org` (Jay Sekora), and I will try to deal with them. Also, feel free to fix them on your own and let me know how you did it.

### Future Directions

Aside from making the browser more robust, I'd like to modify it so it can be used as a frontend to `ftp`, and as a news and MH mail browser. I also intend to implement some mechanism for selecting a group of files, possibly from different directories, and working with them as a unit. Also, I'd like to make it multicolumn, displaying the contents of the current directory's parent as well as the current directory. (My earliest prototypes were like that.)

### Changes since Version 3.2/1.0

* Almost all procedure names have changed, so configuration files will need to be redone.

* The name has changed to `jbrowser`.

* Configuration files have changed their names.

* Some code has been moved to the libraries.

* The preferences panel has been split in two, and more preferences are supported. The preferences mechanism has been redone; it now relies on the X Windows defaults mechanism.

* The browser now scrolls when you're selecting files with the arrow keys and you move off the edge of the (visible part of the) listbox.

* `jedit` rather than `xedit` is now the default editor.

* Issue Unix Command... is new.

### Changes since Version 0.8a

The following changes have been made since version 0.8a of `browser.tk`:

* There is a new (browserlike) dialogue box for selecting file and directory names.

* A number of the procedures used by the browser, the help viewer, and the editor have been consolidated into the library jlibrary.tcl, and their names (and in some cases their arguments) have changed. This has significant implications for .tk/browsertkrc.tcl files which use those routines under their old names. (There will soon be a help file for jlibrary itself; type `help.tk jlibrary' to see it.) [This help file now exists, but the command to view it is `jhelp jlibrary.tcl'.]

* The browser is now able to deal with files with unusual characters in their names.

* The preferences panel has new options for the font used in the listbox and the appearance of active userinterface items.

* The `Move...' command has been split into a `Move...' and a `Rename...' command, with slightly different capabilities.

* The `Issue Tcl Command...' command is new.

* Typing ``..`' now moves you up one directory.

* The scrollbar no longer jumps to the top sometimes as you work with files.

### Changes since Version 0.7

The following changes have been made since version 0.7 of `browser.tk`:

* `browser.tk` now works under versions 3.0 through 3.2 (and possibly beyond) of Tk.

* The mechanism for getting the currently selected file has changed, and that has implications for configuration files. Instead of `[selection get]`, use `[getfiles]`.

* The main configuration file browsertkrc.tcl must now be in the directory .tk in your home directory; it can no longer be in the top level of your home directory. (And browsertkrc.tcl can't start with a period, while the .tk directory has to.)

* There is now a preferences panel. See the Preferences section for more information.

* The `About the Author' box has been updated.

* Some additional key bindings have been added. Notably, you can now use the arrow keys to navigate the browser.

``