(2) This document has been converted with minimal editing from the documentation for version 4.1/4.4 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.
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.
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.
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.
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.)
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.
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.
You can select a printer using the Global Preferences panel, described under Preferences; the default printer is lp.
(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 keyboard shortcut for `Refresh' is Control-l (lowercase L), by analogy with the Emacs and vi(1) refresh commands.
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.)
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.
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.
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.
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.
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.)
* 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.
* 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.
* 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.
* 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.