TKMAN(1)

NAME
tkman - Tk-based manual page reader with hypertext

SYNOPSIS
A manual page browser, TkMan offers two major advantages over xman: hypertext links to other man pages (click on a word in the text which corresponds to a man page, and you jump there), and better navigation within long man pages with searches (both incremental and regular expression) and jumps to section headers. TkMan also offers some convenience features, like a user-configurable list of commonly used man pages, a one-click printout, and integration of `whatis' and `apropos'. Further, one may highlight, as if with a yellow marker, arbitrary passages of text in man pages and subsequently jump directly to these passages by selecting an identifying excerpt from a pulldown menu. Finally, TkMan gives one control over the directory-to-menu volume mapping of man pages with a capability similar to but superior to xman's mandesc in that rather than forcing all who share a man directory to follow a single organization, TkMan gives control to the individual. In fact, one may decide he has no use for a large set of man pages--say for instance the programmer routines in volumes 2, 3, 4, 8--and eliminate them from his personal database. 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. This man page is slightly less current than the help page available from within TkMan.

DESCRIPTION

  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 where `n' specifies 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 match any (zero or more) characters, `[' .. `]' to match any single character in the enclosed class, and `{' .. `}' to expand the enclosed strings. If you're running TkMan from a shell and giving it an initial man page name to load up as an argument, use this syntax (adequately quoted for protection from the shell), as opposed to the syntax of the standard `man' command. Usually TkMan searches the directories in your MANPATH environment variable for the man page, but you may instead provide a path name for the man page by beginning it with `~', `/', `.' or `..'; this is the way to access a man page which isn't installed in a MANPATH man directory. Further, other Tcl interpreters may display a man page in TkMan by `send'ing a message to the function `manShowMan' with the name of the desired man page, for example `send tkman manShowMan tcl'. 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. `apropos' information is available by typing the name and clicking `apropos' or hitting meta-return (for meta information, of course). The output of `apropos' is piped through `sort' and `uniq' to remove duplicates. To pass the matches through another filter, 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'. Hypertext is active within this listing also. The `Paths' pulldown gives you complete control over which directories of your MANPATH are searched for man pages and apropos information. You can call up a listing of all man pages in a volume through the `Volumes' pulldown menu and then select one to view by double-clicking on its name. Typing a letter jumps to the line in the listing starting with that letter (capital and lower case letters are distinct). The `all' pseudo volume can be useful when used with `Paths' to obtain a complete listing of man pages in, say, one directory tree. Once 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. 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. (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, 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 the escape key. 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 may be read from the same environment. For more sophisticated file browsing, use NBT, my Tcl/Tk-based file browser, which available from TkMan's home FTP site, mentioned above.)

  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 and subsection titles (which are directly available from the `Sections' pulldown) and references to other man pages from its SEE ALSO section (`Links' pulldown). One may jump directly to a section within a man page or a man page referenced in the SEE ALSO section, respectively, by selecting the corresponding entry from one of these pulldowns. It may be handy to tear off the `Sections' and `Links' menus (by dragging the menu title with mouse button 2 pressed). Within a man page or raw text file or pipe, you may added 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, releasing the button, then clicking on the `+' next to `Highlights'. To remove any highlights or portions thereof in a region, select it as before but then click on `-'. Highlighting information is persistent across executions of TkMan. You can move about the man page by using the scrollbar, or typing a number of key combinations familiar to Emacs aficionados. Space or C-v page down and delete or M-v page 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. One may "scan" the page by dragging up and down 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 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. (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 the search. This incremental search can be used to quickly locate a particular command-line option or a particular command in a group (as in `csh'). At the bottom of the screen, type in a regular expression to search for 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.] 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.

  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, helping to starve the planet of life-giving oxygen. 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 and be found in the next search without the bother of re-executing TkMan. Usually TkMan saves its persistent variables, only and always, when exited with the `Quit' button. One may guard against losing highlighting, shortcuts and other what-should-be persistent information by checkpointing the current state with the "Update operation, obviously. Like `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 SEE ALSO section. `Output' only affects the display destination of man pages. 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. Subsection parsing doesn't work for all varieties of man page macros formatting, but it can usefully augment the Sections listing for long man pages. At the factory, TkMan is set to format 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 `Preformat Volumes' switch chooses between these. If a man page has not been formatted by `nroff', TkMan must first pipe the source text through `nroff'. By turing on `Save on nroff', the `nroff'-formatted text is saved to disk (if possible), thereby eliminating this time-consuming step the next time the man page is read. `Mono' toggles between the proportionally-spaced font and a monospaced one, for use in those man pages that rely on a constant-width font to align columns [when 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, select the `Quit' option from the `Occasionals' pulldown.

Customizing 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. Most interesting persistent information, like the command(s) used to print the man page, the fonts used, 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. Thus, 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.) Most persistent information can be changed in the obvious way. For example, to change the means of highlighting from a light yellow background to an underline (to display better on a monochrome monitor), EDIT (change in place) `set man(show,highlight) {-background #ffd8ffffb332}' to `set man(show,highlight) {-underline yes}' I find that dark text is easier to read: `set man(show,fontcolor) black' To change colors append `option' commands to ~/.tkman. Alternatively, TkMan also works with standard X11 resources. For instance, this is how I set my foreground and background colors (X11 resource lines should be placed in one's `.Xdefaults' file, not in ~/.tkman): *TkMan*Foreground: SlateGray4 *TkMan*Background: beige Additional useful commands include `wm', which deals with the window manager; and `bind', which changes keyboard and mouse bindings not related to the text display window. For example, to set an icon image for TkMan, add this line to the end of ~/.tkman: `wm iconbitmap .man @/some/directory/TkMan.xpm' (3) 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.

  Command line options
`-title <title>' Place `<title>' in the window's title bar. `-iconify' and `--iconify' Start up iconified or uniconified (the default), respectively. `-iconname <name>' Use `<name>' in place of the uniconified window's title for the icon name. `-iconbitmap <bitmap-path>' and `-iconmask <bitmap-path>' Specify the icon bitmap and its mask. `-v' Show the current version of TkMan and exit. `-M <path-list>' `-M+ <path-list>' As with `man', change the search path for manual pages to the given colon-separated list of directory subtrees. The `-M+' option prepends these directories to the current list. There is no `-geometry' option. To assign a persistent geometry, start up TkMan, size and place the window as desired, then (this is important) quit via the `Quit' button in the lower right corner.

  Key bindings
Key bindings related to the text display box are kept in the `sb' array in ~/.tkman (see the Tcl documentation for more information on Tcl arrays). In editing the `sb(key,...)' keyboard bindings, modifiers MUST be listed in the following order: `M' (for meta), `C' (control), `A' (alt), `S' (shift). For instance, `set sb(key,MS-less) pagestart' is a valid binding, whereas `set sb(key,SM-less)' is not. To make a binding without a modifier key, precede the character by `-', as in `set sb(key,-space) pagedown'. If you have NBT and would like to share key bindings between them, save the keybindings in their own file, then `source' this file at the bottom of ~/.tkman.

Tkmandesc
Like `xman', TkMan gives you directory-by-directory control over named volume contents. Unlike and superior to `xman', however, each individual 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 MANPATH crossed with volume names, with the yield of each volume containing all the corresponding subdirectories in the MANPATH. By adding Tcl commands to your ~/.tkman (see above), you may add new volume names and add, move, copy and delete directories to/from/among directories. The interface to this functionality takes the form of Tcl commands, so you may need to learn Tcl--particularly the sections on Tcl lists and, perhaps, iteration (`foreach' or `for')--to use this facility to its fullest. Directory titles and SINGLE LETTER abbrevations are kept in lists. Letters 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.

  COMMANDS
These commands are added to the file ~/.tkman (see Customizing TkMan, above). 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) ...' To recreate a cross product of current section lists: `manDescDefaults' To add "pseudo" sections to default/current volume name list, at the end of the list, in alphabetical order, or before or after a specific volume: `set manDescAddSects <list of <letter, title pairs>>' or `set manDescAddSects <list of <letter, title pairs>> sort' or `set manDescAddSects <list of <letter, title pairs>> before <sect-letter>' or `set manDescAddSects <list of <letter, title pairs>> after <sect-letter>' To move/copy/delete/add directories: `manDescMove <from-list> <to-list> <dir-patterns>' `manDescCopy <from-list> <to-list> <dir-patterns>' `manDescDelete <from-list> <dir-patterns>' `manDescAdd <to-list> <dir-list>' The `<dir-patterns>' uses the same meta characters as man page searching (see above). It is matched against MANPATH directories with volume subdirectory appended, as in `/usr/man/man3'. `<from-list>' and `<to-list>' are Tcl lists of the unique single letter volume names; `*' is an abbreviation for all volumes. 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, you may invoke `manDescShow' to dump to stdout the current correspondence of directories to volumes names.

  EXAMPLES
(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 with a duplicate in their default locations: `manDescAddSects {{t "Man Pages du 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' We must name the X Subroutines volume "X", not "x" or "xsub" as the former would duplicate the letter used for other X man pages and the latter is a string of multiple letters. (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]' Alternatively but not equivalently: `manDescDelete {2 3 4 8} *'

  Tkmandesc vs. xman and SGI
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).

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

AVAILABILITY
The latest version of TkMan is always available by anonymous FTP at ftp.cs.Berkeley.EDU in the /ucb/mhgs directory.

SEE ALSO
man(1), man(7), catman(8), xman(1)

COPYRIGHT
Copyright (c) 1993 T.A. Phelps 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/or suggestions for new features, include the versions of TkMan, Tcl, Tk, X, and UNIX, your machine and X window manager names, and a copy of your ~/.tkman file. First check that values changed in the Makefile or source code aren't being unexpectedly overridden in ~/.tkman.

DISCLAIMER
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 and the following three paragraphs appear in all copies. Permission to incorporate this software into commercial products may be obtained from the Office of Technology Licensing, 2150 Shattuck Avenue, Suite 510, Berkeley, CA 94704. 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.