*** INSTALLING ***

TkMan 1.7 is based on Tcl 7.4 and Tk 4.0 and will not work with
earlier versions.  Tcl and Tk are available for anonymous ftp from
ftp.smli.com or ftp.cs.berkeley.edu:/ucb/tcl.  Tcl and Tk require X
Windows, and TkMan expects a UNIX-like man page directory structure.

Be sure to read through the Makefile as there are pieces throughout
the top half of it that you may wish or need to customize for your
site.  Set BINDIR in the Makefile to where you keep your binaries
(tkman goes here), and MANDIR to the directory where the TkMan's
manual page should be copied.  After properly editing the Makefile,
type `make install'.  Thereafter type `tkman' to invoke TkMan (perhaps
after a `rehash').

TkMan uses the man page filter RosettaMan (rman), which should be
installed somewhere on your bin PATH.  RosettaMan is available from
ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman.tar.Z

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.

SUN SOLARIS, SGI IRIX, SCO, IBM AIX
These systems store manual pages in nonstandard ways.  Each of
Solaris, SGI IRIX and SCO requires a special bindings file found in
the contrib directory.  Random System V based OS'es should follow the
example for SGI.  IBM AIX'ers should convert InfoExplorer format man
pages to the standard /usr/man/cat* format using the procedure
described in section 7 of the document /usr/lpp/bos/bsdadm.
N.B. TkMan will find these new cat directories automatically **so long
as there is no man directory with the same number***.  For example, if
you convert some InfoExplorer pages into /usr/man/cat1 and have a
directory /usr/man/man1 for source for other manual pages, the
converted ones in /usr/man/cat1 won't be seen.  I recommend comverting
all the InfoExplorer pages into their own hierarchy that includes only
cat* directories.

THE PROBLEM OF "STRAY CATS"
TkMan steps through the user's MANPATH collecting directories matching
the patterns man* and cat*.  If there is a cat directory with the same
number as a man directory, the cat directory is thrown out, with the
reasoning that the cat directory simply has cached formatted versions
of pages in the corresponding man directory.  If there is no such man
directory, the cat version is kept, a feature which supports flavors
of UNIX that ship only formatted pages in "cat-only" directories.
Manual pages found in a cat directory but not in the corresponding man
directory (that is, a corresponding man directory exists but doesn't
have the man page) are known as "stray cats".  Unless you take action,
names of stray cats are not included in the database.  If there are
just a few, you can create these names in the man directory (say with
a symbolic link).  If there are entire directories, you can use
tkmandesc commands to specifically add these directories.

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

TkMan is a graphical, hypertext manual page browser for UNIX.

Compatible with Hewlett-Packard HP-UX, AT&T System V, SunOS, Sun
Solaris, OSF/1, DEC Ultrix, SGI IRIX, Linux, SCO, IBM AIX, FreeBSD

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.  For example,
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.  Or a Tcl/Tk programmer may decide
to group Tcl/Tk manual pages in their own volume listing.

Other features include:
* full text search of man pages (with Glimpse, optional)
* a list of recently added/changed manual pages
* a "history" list of recently visited pages
* a user-configurable "shortcuts" or "hot" list
* a preferences panel to control fonts, colors, and other system settings
* compatibility with compressed pages (both source and formatted)
* diagnostics on your manual page installation
* when asking to print a page that available only in formatted form,
  TkMan can try to reverse compile it to create [tn]roff source,
  which can then be reformatted as good-looking PostScript

TkMan adapts to your use of it, and you should kill it with the `Quit'
button if you wish to save these adaptations.

Be sure to look in the contrib directory for lots of good stuff.

--------------------------------------------------


*** TkMan Q&A ***


Q: XXX man page doesn't format properly.  
A: RosettaMan (rman) 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
        mark references to other man pages

And, on certain systems:

	Ultrix - upper and lower case section headers, odd and even page
	   variations, interspersed tabs
	Solaris - bold italics

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: 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.


Limitations imposed by Tk
* can't search backwards for regular expressions

--------------------------------------------------

*** Updating from older versions ***

Among the NEW features since version 1.6 are:

* Compatibility with Tcl 7.4/Tk 4.0
* Much faster searching within text buffer,
  taking advantage of a new feature in Tk 4.0
* Manual pages read in ~40% less time, once found in the database 
  and filtered through nroff if necessary
* Automated Glimpse indexing of compressed files
  (i.e., .glimpse_filters file created automatically--existing .glimpse_filters
  files are left unchanged)
* Back door to use local man command.  Useful in situations when the MANPATH
  changes frequently.  You do lose some functionality, however.


Among the NEW features are:

* database of man page names stored on disk, so once the database is built...
     startup much quicker, searching faster, volume listings faster,
     also, the help page comes up much quicker
     In sum, these changes make TkMan much more usable on slower machines.
* full text search through man pages with Glimpse (optional)
* Preferences panel to choose fonts, colors and other options
* list of recently added or changed manual pages
* likely man page references distinguished with typewriter font (Michael Harrison)
* hypertext list of all man pages with highlights (Steven S. Dick)
* support for short UNIX file names (for old file systems)
* support for saving formatted pages to H-P's cat.Z directories
* support for LANG environment variable (Yasuro Kawata)
* TKMAN environment variable searched for command line options
* Help file maintained in HTML and automatically converted for use in TkMan.
  This means that one can use a WWW browser to read the help and
  generate a PostScript version to print out.
* incremental searches highlight match
* manual page filter slightly improved (handles OSF and GNU formatting)
* error checking on MANPATH and existence of supporting executables
* support for Linux Filesystem Structure (FSSTND)
* support for IBM's AIX

Long-time TkMan users can remove bin/bs2tk, lib/taputils.tcl, lib/utils.tcl,
lib/searchbox.tcl.
