TkInfo
======


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

TkInfo is a graphical browser for files in the GNU hypertext "info"
format. It runs on every system that supports Tcl/Tk, which means all
Unix/X, Macintosh, Windows95 and Windows NT systems.

TkInfo can also be embedded into other Tcl/Tk scripts to provide
integrated on-line help.

Info files provide a robust hyper-text capability that is ideal for
on-line help.  The format is suitable for both tty-based and graphical
systems.  In addition, the same texinfo source can produce both a nice
hardcopy manual (via TeX) and online browsable info files.  All GNU
programs (e.g. the editor emacs, the compiler gcc, the C library
glibc, and the shell bash, available for free from
ftp://prep.ai.mit.edu/pub/gnu) are documented in this way (via
texinfo). Info files usually reside in the directory /usr/info or
/usr/share/info or /usr/local/info or /usr/local/gnu/info on Unix
systems.


How to get it?
--------------

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

TkInfo versions 0.8 and later are available from
        http://math-www.uni-paderborn.de/~axel/tkinfo/


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

In order to unpack the gzipped tar archive tkinfo-x.y.tar.gz, you need
the programs gzip and tar. These are available for all operating
systems and can be downloaded from your favorite freeware archive.

You need an interpreter (usually called wish) for 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 under Unix, 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, check if you have a
program called wish4.0 or wish4.1 or wish8.0 or similar. If yes, then you
need to change the first line of the tkinfo script to

#!/usr/local/bin/wish4.0

or whatever the path of the correct wish is. If no, then you need to
install the newest version of Tcl and Tk first. They are available for
free via anonymous ftp from ftp://ftp.smli.com/pub/tcl .

If you only have an old version of Tcl/Tk (prior o Tcl7.4/Tk4.0)
installed on your system and you can't or don't want to upgrade, you
can use tkInfo version 0.7-beta.

In order to use tkInfo, you also need some info files to read, or else
you are restricted to the tkInfo documentation itself. I can recommend
the info files that come with the GNU C library glibc; they provide an
excellent introduction to advanced C programming. TkInfo (and most
other info readers) can deal with gzip and bzip2 compressed info files
transparently, so you can keep everything in your info directory
compressed at all times.

The "Manual" and "Apropos" functions of tkInfo require tkman to be
installed on your system. It is a browser for Unix man pages. TkInfo
works perfectly fine without TkMan, but you do want this program, it
is by far the best reader for Unix man pages. 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 having the X session managed by xdm.


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

Simply type

   ./tkinfo

in the tkinfo directory. If the node "(dir)Top" shows up with a
listing of several info files, you're fine. If some error message
appears and the tkInfo docs show up, tkInfo couldn't find a directory
containing an info file called "dir" in its default search path. If
there is such a directory somewhere on your system, you need to tell
tkinfo about it: either specify it in the environment variable
INFOPATH or with the command line option -dir (see below).


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

On Unix, put the program in a directory that's in your searchpath,
e.g. /usr/local/bin, and put the manpage tkinfo.1 in your man
directory, e.g. /usr/local/man/man1.

For considerably faster startup, you can also change the first line of
the script to

#!/usr/bin/wish

or whatever the full pathname of the correct wish binary is.

TkInfo uses the environment variables INFOPATH (a colon-separated list
of directories to search for info files) and INFOSUFFIX (a
colon-separated list of suffixes to try, one of which should always be
"") to locate info files.  The default for INFOSUFFIX should be fine
and there's no need for you to set that variable. The default search
paths for info files are defined in the procedure tkiInit() in the
variable defInfoPath. If these are not appropriate for you, you can
either set INFOPATH appropriately, pass directories to tkinfo on the
command line 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.

Initially, TkInfo searches for an info file called "dir" in the info
search path. If there is one, tkinfo will display it; on a well
maintained system, this info file contains links to all other
installed info files. If no dir file can be found, you can still read
other info files: simply type 'g' and then enter the info file's name,
either its full pathname or just its filename if it can be found in
the info search path.

If you want, you can attach an icon to the program class TkInfo in
your window manager's startup file. I use xman.xpm which looks
appropriate and exists on most systems.

For information about how to customize the appearance of tkInfo, start
the program, hit "h" and choose the "Customization" entry.


Any specific information for Win95/WinNT users?
-----------------------------------------------

You will probably want to start tkInfo in the following way:
    wish42 \wherever\tkinfo -dir c:\somewhere\info
if all your info files are stored in the directory c:\somewhere\info
(use whatever version of wish you have, obviously).  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. The `!' command to execute a tcl command
won't be very useful since the output is sent to stdout which is
discarded by Windows. Also, `M' to start tkman is useless since tkman
doesn't run on Windows. Please let me know if there are any other
issues.


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. I know for sure that transparent
treatment of compressed info files won't work on Macs since they don't
support pipes.


Version History
---------------

Version 2.11 (17-October-2017): Documentation patches by Debian
maintainer Peter Blackman.

Version 2.10 (12-October-2017): Correctly bind Shift-Tab, thanks
to Gerald Williams.

Version 2.9 (04-October-2017): Correctly deal with "Local Variables:"
info nodes, thanks to Gerald Williams.

Version 2.8 (22-March-2004): Removed a subtle bug found by Haakon
Riiser; now works correctly with identically named info files in
different directories.

Version 2.7 (21-March-2004): Will now also accept a menu item of the
dir file on the command line (closes Debian bug #149387). Included
/usr/share/info in default directory list (for Debian). Some
documentation updates. Now includes TkInfo.xpm from Debian (under
GPL). Options are now read from system-wide app-defaults file as
advertised.

Version 2.6 (25-June-2003): Minor fixes needed for Tcl/Tk 8.4. This
still works with older versions of Tcl/Tk.

Version 2.5 (30-June-1998): Now works cleanly in embedded mode, as
explained in the source. Don't allow 'quit' if in embedded mode.

Version 2.4 (27-January-1998): Removed bug introduced in 2.2 which
would ignore all but the first entry in INFOPATH. Improved handling of
initial info-file-not-found error.

Version 2.3 (19-January-1998): Tear-off menus now work cleaner under
tk8.0.

Version 2.2 (12-January-1998): Can now deal with bzip2 compressed info
files. Bzip2 compresses better and, if you have enough memory, is
faster than gzip. Fixed bug in handling of multiple info
directories. Fixed bug where dir would show up twice in history list.
We now deal correctly with Windows-style file and directory names that
start with a volume letter.

Version 2.1 (25-November-1997): Tear-off menus don't work properly under
tk4.0 - disabled.

Version 2.0 (18-November-1997): Meta now accesses menubar just like
Alt. Several internal cleanups. Index lookup bugs fixed; index lookups
now match against the current info file's node names as well.
Continue-Search (^s) now beeps and stops when the whole file has been
searched. Can now deal with identically-named info files in different
directories. Tab and Ctrl-Tab now work as intended.  History entries
can be accessed with Alt-h-<number>. Better status line, with more
feedback messages.  All tear-off menus now fully usable.  Insert page
separators during page-wise scrolling (turn off with command line
option +pagesep). Attempt to scroll at end of node results in jumping
to successor node (turn off with command line option +scrollthrough).

Version 1.9 (20-October-1997): History mechanism remembers position in
node and last selected link, like the "last" command. Minor cosmetical
cleanups.

Version 1.8 (24-September-1997): We can now do Index lookups with 'i'.
The prompt area now disappears upon any action, not just ^g.
Various other minor cosmetical changes and bug fixes.

Version 1.7 (18-August-1997): Raise the target window after a
redirect.  Add key bindings of ],[,{,} as in XEmacs. If foo and
foo.info both exist, prefer foo.info since foo is probably a directory
or an executable.  XEmacs info pages often use "()foo" instead of
"foo". We can deal with that now. The "logical successor" command
should never descend into the menu of Index nodes. Fixed another bug
under Tk4.0.

Version 1.6 (15-August-1997): Fixed a bug in the balloonhelp system.
We now have a manpage. Link highlighting now correct. Sun Keypad keys
now bound. Optional display of current info directory (command line
option -showdir).

Version 1.5 (16-June-1997): Transient menu works now under Tk4.0 as
well. Sun specific keysym bindings removed so that script works on
Win95 again. Help appears in its own window now. Remember position in
node and last selected link for "last" command. Can cycle links with
Tab like lynx. Added Usage tips. All lengthy actions now interruptible
with ^G. Backwards search. Previous inputs in the prompt (search and
goto) window can now be recalled with Crsr Up. Old nodelook command
line option changed to linklook; new command line options searchlook
and highlight.

Version 1.4 (04-Apr-1997): History mechanisms added. More
buttons. "Toggle" command removed; "Top" command added.
Debian-faq.info uses "Previous" instead of "Prev" in the header, and
^L characters. We can now deal with that.  Hitting Space repeatedly
walks through a complete info file in logical order. Backspace walks
backwards. Balloonhelp. Right-click on link sets up a "redirect
window"; successive right-clicks will send their output to that
window. Middle and Right-clicks work as expected also on the
buttons. Right-click brings up little menu. Searching is now done
through the whole info file, not only through the current node.

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 with the key bindings and
adds support for compressed info files.


What's left to do?
------------------

TkInfo is still incomplete.  The following is a list of things to do.
Feel free to send in patches.

-  Add option to allow all the "*note:" to not be drawn on the screen,
   or change them to "see also".
-  Implement stat'ing of the source files with auto-reload.
-  Figure out some heuristic for timely un-loading files to save memory.
-  Incremental search through the whole file. Glimpse search through
   the whole info tree.
-  A tree view of the info file should be possible, maybe similar to
   xoobr.
-  Bookmarks and Annotations support like Xemacs. Bookmarks should be
   organizable in folders and subfolders.
-  In short, implement everything from tkman, the mother of all tk
   scripts, and XEmacs info mode, the mother of all info browsers.


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

Kennard White <kennard@ohm.eecs.berkeley.edu>
  (up to version 0.7-beta)
Axel Boldt <axelboldt@yahoo.com>
  (beginning with version 0.8)

Please report any and all problems you have with this program to
axelboldt@yahoo.com.


License?
--------

TkInfo is free. The TkInfo script itself is covered under a BSD-style
license (start the program, type 'h' and go to "Copyright"). The man
page and the pixmap were contributed by the Debian project and are
covered by the GPL.