TKMAN(1)

NAME
tkman - Tk-based manual page reader with hypertext-ish features

INTRODUCTION
I wanted my man page reader to have hypertext. Along the way of writing one, I added jumps to section titles, a configurable short cut list of commonly-referenced man pages, a history list, and two kinds of searching. Since man page formatting follows conventions but not rigid standards, not all man pages can be parsed fully. However, most yield their section titles and SEE ALSOs and their emphasized words. TkMan also tries to filter out the unsightly page footers and headers put in by `nroff', but nonstandard formatting can slip by. Not that the most recent information for TkMan can *always* be found by selecting Help in the Occasionals menu. First I'll describe how to use TkMan, although I hope that most features are intuitive. At the end are my address and UC's disclaimer.

USING TkMan

  Locating a man page
There are several ways to identify 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 `man'. The name may be just the name of the command or may include a `.n' or `(n)' at the end to specify in which section to look. Man pages are matched using file name globbing (as in `csh'), so you can use `?' to match any single character, `*' to mach any (zero or more) characters, `[' .. `]' to match any single character in the enclosed range, and `{' .. `}' to expand the enclosed strings. Usually TkMan searches the directories in your MANPATH for the man page, but you may instead provide a path name for the man page by beginning it with a `~' or a `/'; this is the way to access a man page which isn't installed in a man directory. Further, file browsers may display a man page in TkMan by `send'ing a message to the function `manShowManFound' with the full path name (starting with `/' and including the file name) of the desired man page. If multiple man page names match the specification, the first match (as searched for in MANPATH order) is shown and a pulldown menu appears which contains a list of the other matches. You can click one of the buttons labeled `1'--`8', `o', `l', or `n' (your letters may vary) to bring up that volume of man page entries (the name of the volume appears above) and then click on the name within the listing. Typing a letter (or letters) jumps to the line starting with that letter. Once you have a man page on the screen, you can click on the name of a man page within the text to jump there. (Access to X Windows' clipboard is still available: simply augment all Button 1 bindings with Meta.) The last few man pages you looked at can be accessed directly through the `History' pulldown menu. `Shortcuts' lists your personal favorites and is used just like `History', with the additional options of adding (by clicking `+') the current man page or removing (`-') it from the list. `apropos' information is available by typing the name and clicking `apropos' or hitting meta-return (for meta information, of course). Hypertext is active within this listing also.

  Working within a man page
The `whatis' information for a man page, if any, appears at the top of the screen. To the extent it follows convention, the man page is parsed to yield its section titles (which are directly available from the `Sections' pulldown) and references to other man pages from its SEE ALSO section (`Links' pulldown). It may be handy to tear off the `Sections' and `Links' menus. You can move about the man page by using the scrollbar, or typing space or C-v to page down or delete or M-v to scroll up. C-n and C-p scroll up and down, respectively, by a single line. M-< goes to the head and M-> to the tail of the text. 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 a search. Subsequently typing a few letters attempts to find a line with that string, starting its search with the topmost line currently visible. A second C-s finds the next match of the string typed so far. C-r is similar to C-s but searches backwards. Escape or C-g cancels the search. This incremental search can be use to quickly locate a particular command-line option or a particular command in a group (as in `csh'). The bottom of the screen interfaces to a TCL/Tk demo's (modified) `mkTextSearch' proc. Type in a regular expression to search for at the bottom and hit return or click `Search' to begin a search. Hit `Next' or keep hitting return to search for the next occurance. (`Prev' will be added when Tk supports a `tag prevrange' command.)

  Other commands
The `Occasionals' menu holds commands and options which you probably won't use much. The first group in this menu is comprised of commands which you may invoke several times in a single TkMan session. `Help' returns to this information screen. Although virtually made obsolete by TkMan, `Print' makes a copy of the current man page on dead trees. By default, incremental searching is not case sensitive, but regular expression searching is. These settings can be toggled with the next two menu checkboxes. If you install a new manual pages, invoking `Rebuild Database' will permit them to show up the next time that volume list is shown, without the bother of re-executing TkMan. You will probably only use commands in the next two clusters of `Occasionals' once or twice and leave them set for all executions of TkMan. Choose between seeing a man page's `whatis' information and the full path name of the found file with the `Show Path of Found Man' switch. Until `wish' has an option to startup iconified, TkMan has a checkbox for that. At the factory, TkMan is set to read the contents of man volumes on demand, which entails a little wait the first time that volume is shown, as opposed to waiting for all volumes to be loaded at startup but no waiting thereafter; the `Preload Volumes' switch chooses between these. Usually you'll want to search for man pages all the directories in your MANPATH; however, you can selective turn off searching in a directory by turning off its corresponding switch. `Mono' toggles between the proportionally-spaced font and a monospaced one, for use in those man pages which rely on a constant-width font to align columns (which Tk supports tabs better, the need for this will diminish). `Quit' exits TkMan, of course, after saving some status information (see below). To exit without saving status information, meta-click on `Quit'.

  Modifying TkMan
There are three levels of configuration to TkMan. (1) Transparent. Simply use TkMan and it will remember your window size and placement and short cuts (if you quit out of TkMan via the `Quit' button). (2) Configuration file. Other information, like the string used to print the man page and the fonts used, can be changed by editing one's own ~/.tkman. Thus, a single copy of TkMan (`tkman') can be shared, but each user can have his own customized setup. (3) Source code. Of course, but if you make generally useful changes or have suggestions for some, please report them back to me.

AUTHOR
    Tom Phelps
    University of California, Berkeley
    Computer Science Division
    571 Evans Hall
    Berkeley, CA  94720
    USA
    (510) 642-8155
    phelps@cs.Berkeley.EDU

TODO LIST
    speed up startup!  (how?)
    maybe have split screen like xman
    support a way of grouping, like SGIs
    backwards regexp search when `text' widget has `tag prevrange'
    save yview with shortcuts?  history?
    link up with Kennard White's texinfo reader
    add browsing of header files?

AVAILABILITY
The latest version of TkMan is always available by anonymous FTP at harbor.ecn.purdue.edu in the /pub/tcl/code directory. Paul Raines has modified TkMan for use on SGI (and System V?) machines; it's at bohr.physics.upenn.edu (130.91.48.159) in /pub/tk.

COPYRIGHT
Copyright (c) 1993 by T.A. Phelps (phelps@cs.Berkeley.EDU) University of California, Berkeley Department of Electrical Engineering and Computer Science Computer Science Division PERMISSION IS GRANTED TO DISTRIBUTE THIS SOFTWARE FREELY, BUT ONE MAY NOT CHARGE FOR IT OR INCLUDE IT WITH SOFTWARE WHICH IS SOLD. If you send me bug reports and suggestions for new features, include the versions of TkMan, TCL, Tk, X, and UNIX and your machine and X window manager names.

DISCLAIMER
IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.