RCS: $Id: README,v 1.23 1997/03/08 23:43:26 axel Exp $


TkInfo
======


What is it?
-----------

TkInfo is a tk script to read GNU "info" files and display them.
TkInfo can be used stand alone (via WISH), or embedded within an
application to provide integrated, on-line help. It runs on every
system that supports Tcl/Tk, which means all Unix/X, Mac, and 
Windows variants.

Info files provide a robust hyper-text capability that is ideal for
on-line help.  The format is suitable for both tty-based systems and
graphical systems.  In addition, the same document source can produce
both a nice hardcopy manual and Info files.  Note that most GNU
software is documented in this way (via texinfo). Info files usually
reside in a directory /usr/info or /usr/local/info or
/usr/local/gnu/info or similar. Other info readers are xinfo (old),
info (text-based), and the info mode of the editor (X-)emacs
(huge). It is also possible to serve info files on the WWW with
info2www or to convert their texinfo source to HTML with texi2html.


Where to get it?
----------------

tkinfo up to version 0.7-beta is available by anonymous ftp from:
        ftp://ptolemy.eecs.berkeley.edu/pub/misc

tkinfo versions 0.8 and later are available from 
        http://www.math.ucsb.edu/~boldt/tkinfo/


What is required to run it?
---------------------------

You need Tcl7.4 and Tk4.0 or better on your system. Tcl/Tk is a
language to quickly develop portable graphical user interfaces, among
other things. If you're running the X Window system, you can check
your version of Tk with the shell command

     $ echo 'puts $tk_version; exit' | wish

If you get an error or a version smaller than 4.0, you need to install
the newest version of Tcl and Tk. They are available via anonymous ftp
from ftp://ftp.smli.com/pub/tcl.

If you have an old version of Tcl/Tk installed on your system and you
can't or don't want to upgrade, you can use TkInfo version 0.7-beta.

The "Manual" and "Apropos" functions of tkInfo require tkman to be
installed on your system. It is a browser for Unix manual
pages. TkInfo works perfectly fine without TkMan, but you do want this
program, believe me. It's at
    ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/
and you need to fetch both tkman and rman.  In order for tkinfo to be
able to communicate with TkMan, you have to use a secure X server,
which is easiest accomplished by running xdm.


How to try it out?
------------------

Simply type 

  $ ./tkinfo

in the tkinfo directory, and then type 'h' to learn more about the 
program. You can get the available command line options with

  $ ./tkinfo --help

If tkInfo can't find your info directories and gives you an error
message "Can't locate info nodes...", or if you have problems with the
fonts, see below.


How to install it permanently?
------------------------------

On Unix, put it in a directory that's in your searchpath. For faster
startup, you can also change the first line of the script to

#!/usr/bin/wish

or whatever the full pathname of your wish binary is.

TkInfo uses the environment variable INFOPATH (a colon-separated list
of directories) and INFOSUFFIX (a colon-separated list of suffixes) to
locate info files.  The defaults used if either of these variables is
not set are defined in the procedure tkiInit() in the variable
defInfoPath. You can either set your environment variables
appropriately, pass directories on the commandline with "-dir", or
edit the defaults in defInfoPath once and for all for your site. For
faster startup, don't include more directories than necessary in that
variable.

For information about how to customize the appearance of tkInfo, start
the program, hit "h" and choose the "Customization" entry. That same
information is also present at the top of the tkinfo script itself.


Any specific information for Windows users?
-------------------------------------------

You will probably want to start tkInfo in the following way:
  wish42.exe \wherever\tkinfo.tcl -dir \your\infodir
where all your info files are stored in the directory \your\infodir.
Once inside the program, all paths should be given to tkinfo in the
unix notation with "/" as separator. If you transport info files to
your Windows machine, make sure that the long filenames survive
intact, or else many links won't work. You probably don't have a
middle mouse button; in order to display a node in a new window, you
can use the undocumented "Shift-Click" on the link. If there are any
other issues, let me know.


Any specific information for Macintosh users?
---------------------------------------------

Actually, I haven't tested tkInfo on Macs, so I can't offer any
help. Let me know if you try it out.


What has changed?
-----------------

Version 1.3 (08-Mar-1997): backslashes in links (even at the end) work
now (for latex.info). Correct status message after error. Search
status messages improved.

Version 1.2 (05-Mar-1997): Fixed --help. .Xdefaults customization now
optional. -geometry now handled correctly in all cases.

Version 1.1 (04-Mar-1997): If there's more than one info directory
specified (with INFOPATH or with -dir), a new Directory menu will let
you choose; D command removed. Now works with Windows and Macs. Search
status messages fixed. Initial node name can now contain spaces.  Now
deals correctly with doubles in INFOPATH. Ctrl-2 didn't work
correctly. m and f commands now implemented: allows for completely
mouseless operation. All fonts, colors, etc. are now customizeable
through .Xdefaults. Customization documented in new info node in the
docs.

Version 1.0 (20-Feb-1997): if a node can't be found, try case
insensitive search. Can now do apropos search using tkman. Ctrl-2
opens second menu entry in new window. Keep search status messages
visible. From Frank Leitner: better, customizeable fonts, pointer
changes over links, scrollbar should not vanish upon shrinking the
window, help menu moved to the right.

Version 0.9 (17-Feb-1997): node names are case sensitive! (someone
tell that the author of ipc.info...) Delete key works now.
Crossreferences inside or after menus work. Can now specify an info
file to load on the commandline. No problems with special characters
in node names anymore. Case-insensitive search and Ctrl-s
fixed. Backslash in regexps fixed. Now distributed as a single tcl
script. Scrolling with button-2 and selecting with button-1 now works
as expected even over links. Can deal with Xemacs-style menu
entries of the form "* GNUS::." Accept new command line options -help,
-iconic, and -geometry; -lines removed. Docs improved and source code
roadmap added.

Version 0.8 (6-Feb-1997) now maintained by Axel Boldt. Works with
tcl7.4/tk4.0 or later. Older versions of tcl/tk are no longer
supported. Middle-click on link will bring up the node in new
window. More keybindings and minor improvements to the interface. New
command line option -lines. Docs updated.

Version 0.7-beta (23-Dec-1993) adds many new features including a menu
bar, links to tkman, reorganized files, "gz" compressed file support,
improved searching interface, better docs, and many other minor
improvements.

Version 0.6 (27-Aug-1993) adds a couple new features, and a mod so
that menu items and xrefs trigger on ButtonRelease events rather than
ButtonPress in order to work around a weird interaction with the tk
text widget.  The toplevel widgets use classname "TkInfo".  Also adds
text searching, much more documentation.  Modified to support tcl7.0.

Version 0.5 adds several new features including: several new scrolling
commands, new menuing commands; a "node look" that changes how
highlighting is performed (mainly for B/W screens); a menu of
top-level info "dir"s; much better error messages and popup error
windows; optional display of headers.

Version 0.4 fixes some bugs with auto loading and replaces the unusable
"-file" option with "-infofile".  It provides a work around for Ultrix sh.

Version 0.3 fixes some bugs in with the key bindings and
adds support for compressed info files.


Who wrote it?
-------------

Kennard White <kennard@ohm.eecs.berkeley.edu>
  (up to version 0.7-beta)
Axel Boldt <boldt@math.ucsb.edu>
  (starting with version 0.8)
