*** 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)

