*** INSTALLING *** TkMan 1.5 is based on Tcl 7.0 and Tk 3.3 and will not work with earlier versions. Tcl and Tk are available for anonymous ftp from harbor.ecn.purdue.edu. Tcl and Tk require X Windows, and TkMan expects a UNIX-like man page directory structure. Set BINDIR in the Makefile to where you keep your binaries (tkman and bs2tk go here). After properly editing the Makefile, type `make install'. Thereafter type `tkman' to invoke TkMan (perhaps after a `rehash'). The man page is always slightly out of date and therefore is not installed automatically; you must install it by hand by copying contrib/tkman.1 to the man/man1 subdirectory of whatever directory you wish. If you install a new version of TkMan after having used an old one and some things don't behave well, try removing the ~/.tkman file and running TkMan again. In particular, if you are moving from a pre-1.3 version of TkMan to 1.3 or later, you must delete the line "set man(print) ..." from ~/.tkman (assuming ~/.tkman exists) for printing to work correctly. Also, pre-1.3.4 Ultrix users should delete the line "set man(format) ..." from their ~/.tkman files. Paul Raines has written a startup file that specialized TkMan for use on SGIs. To use it, first create a ~/.tkman file by running TkMan and quitting via the `Quit' button in the lower right. Then append contrib/sgi_bindings.tcl to ~/.tkman. For assistance with SGI-specific directory manipulation, contact Paul Raines (raines@bohr.physics.upenn.edu). 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. -------------------------------------------------- *** COPYRIGHT *** Copyright (c) 1993 T.A. 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 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. -------------------------------------------------- *** SYNOPSIS *** A manual page reader, 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. TkMan adapts to your use of it, and you should kill it with the `Quit' button if you wish to save these adaptations. -------------------------------------------------- *** TkMan Q&A *** Q: What aren't the man page and icon installed? A: Dave Glowacki made the man page by cutting and pasting from the help page and it is always at least one release behind. Roar Smith submitted the icon (other submissions are welcome). I include the man page and icon in the distribution, but I don't support them in any way. Q: XXX man page doesn't format properly. A: bs2tk formats an nroff-formatted man page (always parsing the troff version would take much too long), reformatting it for Tk as follows: strip headers, footers show bullets, italics, boldface parse section and subsection headers parse SEE ALSO for links relocate change bars auto small caps And, on certain systems: Ultrix - upper and lower case section headers, odd and even page variations, interspersed tabs Solaris - bold italic If the man page isn't formatted properly, then try reformatting it with more-standard -man macros. If you see this problem on an entire class of man pages, package up a source version from .../man/manXXX and uuencode a formatted version from .../man/catXXX and e-mail them to me. Q: I installed a new version of TkMan, but a feature advertised as fixed is still broken. A: You may be overwriting fixed code or variables with your ~/.tkman. Make sure you are following the "delete XXX from ~/.tkman" instructions. Q: TkMan takes forever to start up. A: TkMan first builds a database of all man page names and their corresponding directories, so the more man pages you have, the longer it takes. Turning off the switches for these directories has no effect, as you may turn them back on and then where would be be? If, in investigating your MANPATH, you discover paths you never look at, deleting these will speed up start up. TkMan takes about 10 seconds to read in 5000 on my SPARCstation 1+. If, after adjusting for your machine speed and number of man pages, it still seems too slow, make sure you are using the final (not beta) version of Tcl 7.0/Tk 3.3. Q: bs2tk.c won't compile. A: bs2tk.c is written is ANSI C. Is your compiler ANSI compliant? Many older cc's aren't. GNU's gcc compiler is, it's free, and it works on every workstation I use. Q: XXX is really busted--I sure of it! A: To repeat, 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. Q: Cut and paste A: Tk works with PRIMARY property but others, like Emacs 18, only look at CLIPBOARD, so may need to paste into xclipboard first. bs2tk: illegal option -- T bs2tk: unidentified option -? You're picking up an old version of bs2tk. Limitations imposed by Tk * can't show volume contents in columns very well: Tk's tabs not good. I tried parallel listboxes, but that didn't look very good (entire columns move at once giving a ripple)