implemented in John Ousterhout's Tcl 7.5/Tk 4.1, icon drawn by Rei Shinozuka
Compatible with Sun Solaris, SunOS, Hewlett-Packard HP-UX, OSF/1, DEC
Ultrix, AT&T System V, SGI IRIX, Linux, SCO, IBM AIX, FreeBSD, BSDI
-- each of which, believe you me, is in some way different from all the others
Copyright © 1993-1996 Thomas A. Phelps
All Rights Reserved.
University of California, Berkeley
Department of Electrical Engineering and Computer Science
Computer Science Division
The latest version of TkMan is always available by anonymous
If you send me bug reports and/or suggestions for new features, include your MANPATH, the versions of TkMan, Tcl, Tk, X, and UNIX, your machine and X window manager names, the edited Makefile, a copy of your ~/.tkman file, and the first few lines of the tkman executable. Otherwise don't waste my time.
A graphical manual page browser, TkMan offers two major advantages over
Other features include:
* full text search of manual pages (with Glimpse; optional)
* when multiple pages match the search name, a pulldown list of all matches
* regular expression searches for manual page names
* a list of recently added or changed manual pages
* a "history" list of the most recently visited pages
* a preferences panel to control fonts, colors, and other system settings
* compatibility with compressed pages (both as source and formatted)
* diagnostics on your manual page installation
* elision of those unsightly page headers and footers
* and, when attempting to print a page available only in formatted form,
reverse compilation into [tn]roff source,
which can then be reformatted as good-looking PostScript.
This help page is shipped with the distribution in HTML form for easy printing.
There are several ways to specify the manual page you desire. You
can type its name into the entry box at the top of the screen and
press Return or click the man button. The name may be just the name of
the command or may end with .n or (n),
where n specifies in which section to look. Man pages are
matched using regular expressions, so you can use . to match
any single character, * to match any (zero or more) of the
previous regular expression, [ .. ] to match any
single character in the enclosed class; see
Usually TkMan searches the directories in your
apropos information is available by typing the name and clicking apropos or hitting Shift-Return. The output of apropos is piped through sort and uniq to remove duplicates. To pass the matches through additional filters, simply give the pipe as in a shell, e.g., `search | grep ^g' (each space character is significant) returns all the search-related commands which begin with the letter g. The results of the last apropos query are available under the Volumes menu.
You may also
see a button for glimpse, a full text search program that
requires only small index files ("typically 2-5% the size of the
original text" but larger percentages for smaller amounts of text),
written by Udi Manber, Sun Wu, and Burra Gopal of
the University of Arizona's Department of Computer Science. In their
performance measurements, "a search for Schwarzkopf allowing two
misspelling errors in 5600 files occupying 77MB took 7 seconds on a
SUN IPC". For example, one may search for the string `WWW' anywhere in any manual page
by typing in `WWW' in the entry line at the top of the
screen and clicking on the glimpse button
or typing Meta-Return (for meta-information, of course).
Escape and C-g can interrupt a search after the
current directory is done.
To employ glimpse's command line options, simply
place them before the search pattern in the entry box, or add them to
the default options by editing the man(glimpse) variable in
your ~/.tkman startup file (see Customizing TkMan, below).
For instance, to search for "perl" as a word and not part of another
word (as in "properly"), glimpse for -w perl.
Glimpse supports an AND operation denoted by the symbol
`;' and an OR operation denoted by the symbol
`,'.
Refer to the
The Paths pulldown gives you complete control over which directory hierarchies of
your
Whenever you have a man page name in the text display box, whether from apropos, a volume listing or a reference within another man page, you can double-click on it to hypertext-jump to it. Pressing shift while double-clicking opens up a new viewer box to display the page.
The last few man pages you looked at can be accessed directly through the History pulldown menu. The list is sorted top to bottom in order of increasing time since that page was last visited. Shortcuts lists your personal favorites and is used just like History, with the additional options of adding the current man page (by clicking +) or removing it (-) from the list. A shift-click on - removes all shortcuts.
(Man pages specified as above are processed through an nroff filter. TkMan can also read raw text from a file or from a command pipeline, which can then be read, searched and highlighted same as a man page. To read from a file, make the first character in the name a <, as in <~/foo.txt. To open a pipe, make the first character a | (vertical bar), as in `|gzcat foo.txt.gz' or `|cat ../foo.txt | grep bar' (that's no space after the first |, a space before and after any subsequent ones). After reading a file in this way, the current directory is set to its directory. Commands are not processed by a shell, but the metacharacters ., .., ~ and $ (for environment variables), are expanded nonetheless. Typing is eased further by file name completion, bound to Escape. Lone files (i.e., not part of a pipe) are automatically uncompressed--no need to read compressed files through a zcat pipe. It is not expected that reading raw text will be done much; it is included so the occasional non-man page documentation, say, a FAQ or RFC, may be read from the same environment.)
The full pathname of the current manual page is shown at the top of
the screen. Via the Preferences dialog, this can be changed to the
To the extent it follows conventional formatting, a manual page is parsed to yield its
section and subsection titles (which are directly available from the
Sections pulldown) and references to other man pages from throughout the page
including its
Within a man page or raw text file or pipe, you may add ad hoc highlighting, as though with a yellow marker (underlining on monochrome monitors). Highlighted regions may then be scrolled to directly through the Highlights pulldown menu. To highlight a region, select the desired text by clicking button 1, dragging to the far extent of the desired region and releasing the button, then click on the + next to Highlights. To remove any highlights or portions thereof in a region, select it as before but then click on -. A shift-click on the menu title tours through all the highlights on the page. A shift-click on - removes all highlights on the page. A complete set of pages with highlighting is available under the Volumes menu.
Highlighting information is robust against changes to and reformatting of the page. Here's how highlight reattachment works. When you highlight a region, the starting and ending positions are saved along with some the content of the highlighted region and context. When that page is viewed again, if those positions still match the context, the highlight is attached there (this is an exact match). If not, the context is searched forward and backward for a match, with the closer match chosen if there are matches in both directions (a repositioned match). If no match is found with the full context, gradually less and less of it is tried, reasoning that perhaps the content of the context has been changed (repositioned, but with less confidence, triggering a warning dialog). If still no match is found (an orphan), the highlight is reported at the bottom of the page, where it must be reattached manually before leaving the page or it will be forgotten. (Before TkMan v1.8b4, highlights were attached by positions only, and when the page modification date changed, the user had the choice of applying highlights at those same positions regardless of the text there now or throwing out the highlights wholesale. Old style highlights are automatically updated to the new style that can be automatically and robustly repositioned. The next time an old style page is viewed, the old style highlights are applied as before, and from those postions new style highlights are composed.) The annotation reattachment mechanism is inspried by Stanford's ComMentor system.
You can move about the man page by using the scrollbar or typing a number of key combinations familiar to Emacs aficionados. Space and C-v page down, and delete and M-v page up. C-n and C-p scroll up and down, respectively, by a single line (vi fans will be happy to hear that C-f and C-b also page down and page up, respectively). M-< goes to the head and M-> to the tail of the text. One may "scan" the page, which is to say scroll it up and down with the mouse but without the use of the scrollbar, by dragging on the text display with the middle mouse button pressed. Like Emacs, C-space will mark one's current location, which can be returned to later with C-x, which exchanges the then-current position with the saved mark; a second C-x swaps back.
C-s initiates an incremental search. Subsequently typing a few letters attempts to find
a line with that string, starting its search at the current match, if any,
or otherwise the topmost visible line.
A second C-s finds the next match of the string typed
so far. (If the current search string is empty, a second C-s retrieves the
previous search pattern.) C-r is similar to C-s but searches backwards.
Escape or C-g cancels searching.
Incremental search can be used to
quickly locate a particular command-line option or a particular command in
a group (as in csh's long list of internal commands).
At the bottom of the screen, type in a regular
expression to search for (see Tcl's
The Tab key moves the focus from the man page type-in line to the text view of the man page to the search line and back around. Shift-Tab jumps about in the opposite direction.
The Occasionals menu holds commands and options which you probably won't
frequently. Help returns to this
information screen. Although virtually made obsolete by TkMan, Kill Trees
makes a printout of the current man page on dead, cut, bleached trees, helping to starve the
planet of life-giving oxygen. A list of printers appears in the cascade menu; this
list may be edited in Preferences/Misc. (Even if only one printer is available,
it placed in the cascade menu, rather than being directly available. This is a feature.)
(If the [tn]roff source is not available, TkMan
asks if it should try to reverse compile the man page. If successful, this
produces much more appealing output than an
As with xman one may instantiate multiple viewers. When there is more than
one viewer you may choose man pages in one viewer and have their contents
shown in another. Use the Output pulldown (which appears and disappears
as relevant) to direct one viewer's output destination to another. With
this feature one may easily compare two similar man pages for differences,
keep one man page always visible, or examine several man pages from a
particular volume listing or a
At the bottom right corner of the screen, Mono toggles between the proportionally-spaced font and a monospaced one, for use in those man pages that rely on a fixed-width font to align columns. Quit exits TkMan, of course, after saving some state information (see below). To exit without saving status information, select the Quit option from the Occasionals pulldown.
The Preferences... choice in the Occasionals pulldown menu brings up a graphical user interface to setting various attributes of TkMan, including fonts, colors, and icons. Click on a checkbutton at the top of the window to bring up the corresponding group of choices. After making a set of choices, the Apply button reconfigures the running application to show these changes, OK sets the changes for use now and in the future, Cancel quits the dialog and sets all choices to their settings as of the time Preferences was called up, and Defaults resets the settings in the current group to those set by TkMan out of the box.
The first line in the Fonts group specifies the font to use for the general user interface, which amounts to the labels on buttons and the text in menus. The first menu in the line labeled Interface sets the font family, the next menu sets the font size, and the last the font styling (normal, bold, italics, bold-italics). Text display makes these settings for the text box in which the manual pages contents are displayed. For listings of all man pages in a particiular volume (as chosen with the Volumes menu), you may wish to use a smaller font so that more names fit on the screen at once. Screen DPI specifies the right set of fonts to use for your monitor.
Colors sets the foreground and background colors to use for the manual page text display box, the general user interface, and the buttons of the user interface. In addition it sets the color (or font) in which to show various classes of text in the text box, including manual page references, incremental search hits, regular expression search hits, and highlighted regions.
The See group specifies what information to display. Usually manual page headers and footers are uninteresting and therefore are stripped out, but a canonical header and footer (along the date the page was installed in the man/mann directory or formatted to the man/catn directory) to be shown at the bottom of every page can be requested. Solaris and IRIX systems come with many "subvolumes"--that is volumes with names like "3x" and "4dm" that form subgroupings under the main volumes "3" and "4", respectively--and you make use tkmandesc commands to add your own subvolumes. You can reduce the length of the main Volumes menu by placing all volumes in such groups as cascaded menus. When a highlighted passage is jumped to via the Highlights menu, some number of lines of back context are included; the exact number of lines is configurable. The information bar at the top of the window can display either the short, one-line description from a manual page's NAME section or the pathname of the page. Around the man page display area runs a buffer region, the exact width of which is configurable. Tk deviates from Motif behavior slightly, as for instance in highlighting buttons when they're under the cursor, but you can observe strict Motif behavior.
The Icon group sets all the options relating to iconification. The pathnames of the icon bitmap and icon mask should be the full pathnames (beginning with a `/').
If a man page has not been formatted by nroff, TkMan must first pipe the source text through nroff. By turing on Cache formatted (nroff'ed) pages in the Misc(ellaneous) group, the nroff-formatted text is saved to disk (if possible), thereby eliminating this time-consuming step the next time the man page is read. The on & compress setting will compress the page, which saves on disk space (often substantially as much of a formatted page is whitespace), but will make it unavailable to other manual pagers that don't handle compression. By default man page links are activated by double clicking. The first click puts the name in the entry box so that it can be used as the apropos or glimpse pattern as well. This click once to select, twice to launch follows the Macintosh convention. Since TkMan was written, some hypertext browsers have popularized a click-once-to-launch practice. The Mouse click to activate hyperlink switch chooses between the two. TkMan can extract section headers from all manual pages, but only some manual page macros format subsection headers in a way that can be distinguished from ordinary text; if your macros do, turn this option on to add subsections to the Sections menu. The History pulldown must balance depth of the list against ease of finding an entry; set your own inflection point with this menu. Volumes' (recent) choice will show all manual pages that have been added or changed n days, where n is set with this next menu. Glimpse works best when searching for relatively uncommon words; guard against getting too many hits by setting the maximum number reported. By default Glimpse indexes are placed at the root of the corresponding man hierarchy, where they can be shared. For the case when an individual may not have write permission there, a single, unified index can be created and stored locally (though you lose control of it from the Paths settings). Unified indexes are much faster that distributed. In this latter case and also for "stray cats" (i.e., directories not part of a set of man hierarchy directories), you should specify an auxiliary directory to hold the index. Proportional spacing wrecks the spacing used to set tables in columns, hence the Mono(space) button on the bottom line of the main screen.
There are four levels of configuration to TkMan.
(1) Transparent. Simply use TkMan and it will remember your window size and placement, short cuts, and highlights (if you quit out of TkMan via the Quit button).
(2) Preferences editor (see Preferences above).
(3) Configuration file. Most interesting settings, like the command(s) used to print the man page and some key bindings, can be changed by editing one's own ~/.tkman. Thus, a single copy of TkMan (i.e., the executable tkman) can be shared, but each user can have his own customized setup. (The file ~/.tkman is created/rewritten every time one quits TkMan via the Quit button in the lower right corner. Therefore, to get a ~/.tkman to edit, first run and quit TkMan. Do not create one from scratch as it will not have the proper format used for saving other persistent information, and your work will be overwritten, which is to say lost.) Be careful not to edit a ~/.tkman file only to have it overwritten when a currently-running TkMan quits.
Options that match the defaults are commented out (i.e., preceded by a #). This is so that any changes in the defaults will propagate nicely, while the file still lists all interesting variables. To override the default settings for these options, first comment in the line.
The ~/.tkman save file is the place to add or delete colors to the
default set, which will subsequently become menu choices in
Preferences, by editing in place the variable
man(colors). One may also edit the order of Shortcuts
in the man(shortcuts) variable.
Other interesting variables include
man(highlight), which can be edited to change the background
in place of the foreground, or both the foreground and
background, or a color and the font as with the following
setting:
set man(highlight) {bold-italics -background #ffd8ffffb332}
Arbitrary Tcl commands, including tkmandesc commands (described below), can be appended to ~/.tkman (after the ### your additions go below line).
To set absolutely the volume names for which all directories should be
searched, edit the parallel arrays on these existing lines:
set man(manList) ...
set man(manTitleList) ...
Changing the order volumes in these lists (make sure to keep the two lists
in parallel correspondence) changes the precedence of matches when two or
more pages have the same name: the page found in the earlier volume in this list
is show first.
Additional useful commands include
(4) Source code. Of course, but if you make generally useful changes or have suggestions for some, please report them back to me so I may share the wealth with the next release.
Key bindings related to the text display box are kept in the sb
array in ~/.tkman (for more information on Tcl's arrays, refer to
the
Like xman, TkMan gives you directory-by-directory control over named volume contents. Unlike and superior to xman, however, each individual user controls directory-to-volume placement, rather than facing a single specification for each directory tree that must be observed by all.
By default a matrix is created by taking the product of directories in the
The interface to this functionality takes the form of Tcl commands, so you
may need to learn Tcl--particularly the commands that deal with Tcl lists
(including
Directory titles and abbrevations are kept in lists. Abbreviations MUST be unique (capital letters are distinct from lower case), but need not correspond to actual directories. In fact, volume letters specified here supercede the defaults in identifying a volume in man page searches.
The following commands are appended to the file ~/.tkman (see Customizing TkMan, above).
To recreate a cross product of current section lists:
manDescDefaults
This cross product is made implicitly before other tkmandesc commands.
Almost always this is what one expects. If it is not, one may supress the
cross product by setting the variable manx(defaults) to a non-null, non-zero
value before other tkmandesc commands are invoked.
To add "pseudo" sections to the current volume name list, at various positions including
at end of the list, in alphabetical order, or before or after a specific volume:
manDescAddSects list of (letter, title pairs)
or manDescAddSects list of (letter, title) pairs sort
or manDescAddSects list of (letter, title) pairs before sect-letter
or manDescAddSects list of (letter, title) pairs after sect-letter
In manual page searches that produce multiple matches, the page found
in the earlier volume is the one shown by default.
To move/copy/delete/add directories:
manDescMove from-list to-list dir-patterns-list
manDescCopy from-list to-list dir-patterns-list
manDescDelete from-list dir-patterns-list
manDescAdd to-list dir-list
The dir-patterns-list uses the same meta characters as man
page searching (see above). It is matched against
Adding directories with manDescAdd also makes them available to Glimpse for its indexing.
Warning: Moving directories from their natural home slightly impairs searching speed when following a reference within a man page. For instance, say you've moved man pages for X Windows subroutines from their natural home in volume 3 to their own volume called `X'. Following a reference in XButtonEvent to XAnyEvent(3X11) first searches volume 3; not finding it, TkMan searches all volumes and finally finds it in volume X. With no hint to look in volume 3 (as given by the 3X11 suffix), the full volume search would have begun straight away. (Had you double-clicked in the volume listing for volume X or specified the man page as XButtonEvent.X, volume X would have been searched first, successfully.)
To help debug tkmandesc scripts, invoke manDescShow to dump to stdout the current correspondence of directories to volumes names.
(1) To collect together all man pages in default volumes 2 and 3 in all
directories into a volume called "Programmer Subroutines", add these lines
to the tail of ~/.tkman:
manDescAddSects {{p "Programmer Subroutines"}}
manDescMove {2 3} p *
To place the new section at the same position in the volume pulldown list
as volumes 2 and 3:
manDescAddSects {{p "Programmer Subroutines"}} after 2
manDescMove {2 3} p *
To move only a selected set of directories:
manDescAddSects {{p "Programmer Subroutines"}}
manDescMove * p {/usr/man/man2 /usr/local/man/man3}
(2) To have a separate volume with all of your and a friend's personal man
pages, keeping a duplicate in their default locations:
manDescAddSects {{t "Man Pages de Tom"} {b "Betty Page(s)"}}
manDescCopy *phelps* t *
manDescCopy *page* t *
(3) To collect the X windows man pages into two sections of their own, one
for programmer subroutines and another for the others:
manDescAddSects {{x "X Windows"}} after 1
manDescAddSects {{X "X Subroutines"}} after 3
manDescMove * x *X11*
manDescMove x X *3
(4) If you never use the programmer subroutines, why not
save time and memory by not reading them into the database?
manDescDelete * {*[2348]} (braces prevent Tcl from trying to execute [2348] as a command)
Alternatively but not equivalently:
manDescDelete {2 3 4 8} *
TkMan's tkmandesc capability is patterned after xman's mandesc files. By placing a mandesc file at the root of a man page directory tree, one may create pseudo volumes and move and copy subdirectories into them. Silicon Graphics has modified xman so that simply by creating a subdirectory in a regular man subdirectory one creates a new volume. This is evil. It violates the individual user's rights to arrange the directory-volume mapping as he pleases, as the mandesc file or subdirectory that spontaneously creates a volume is set a single place and must be observed by all who read that directory. By contrast, TkMan places the directory-to-volume mapping control in an individual's own ~/.tkman file. This gives the individual complete control and inflicts no pogrom on others who share man page directories. Therefore, mandesc files are not supported in any way by TkMan.
One may still share custom setups, however, by sharing the relevant lines of ~/.tkman. In fact, a tkmandesc version of the standard SGI man page directory setup is included in the contrib directory of the TkMan distribution. For assistance with SGI-specific directory manipulation, contact Paul Raines (raines@bohr.physics.upenn.edu).
TkMan uses RosettaMan to translate and reformat man pages (see
Tom Phelps
University of California, Berkeley
Computer Science Division
387 Soda Hall #1776
Berkeley, CA 94720-1776
USA
phelps@cs.Berkeley.EDU
A World Wide Web page that lists other Tcl/Tk software and a related Berkeley Computer Science Division technical report, CSD-94-802, can be found at http://http.cs.berkeley.edu/~phelps/.
Permission to use, copy, modify, and distribute this software and its documentation for educational, research and non-profit purposes, without fee, and without a written agreement is hereby granted, provided that the above copyright notice, this and the following two paragraphs appear in all copies.
Help page last revised on $Date: 1996/07/17 00:57:39 $