Jim Brooks
jim@jimbrooks.org
2000/12/28

Synopsis
========

"hypersrc" is a freeware GTK+/GNOME program for browsing source code. 

Requirements
============

- GTK+/GLIB 1.2.8 (or later) installed.

  At least one old GTK+ version (1.2.3) is known to have a bug
  that causes a segfault when a tag is clicked (see below).

- GNOME (a recent version)

- "Exuberant ctags" 2.0.3 (or later) by Darren Hiebert.

  You probably already have it, if you have a recent Linux distribution.

  To be precise, requires a program capable of producing output equivalent
  to its -x option.  See "Unsupported Source Files".
  The webpage for Exuberant ctags is: http://fly.hiwaay.net/~darren/ctags
  hypersrc requires the cross-reference capability offered by its -x option.
  Old GNU ctags won't work because it lacks capability required by hypersrc.

Building/Installing/Quickstart
==============================

See INSTALL.txt

Customization and Options
=========================

Some preferences can be edited/saved via the GUI.
Preferences can be overridden by corresponding cmd-line args.
All preferences can be ignored by passing "-ignore-prefs".

hypersrc has a set of command line options to support customizing
the maximum amount of tags, tab width, window geometries, fonts, etc.
Invoke "hypersrc -help" to see a list of options.

Hypersrc.pl also has its own option list (see "Hypersrc.pl -help").

Options specific to hypersrc can be specified indirectly via Hypersrc.pl.
Options which Hypersrc.pl doesn't understand will pass thru to hypersrc.

You can put options that you want to use continuously into the definition
of $args in Hypersrc.pl.

Examples:

   Hypersrc.pl  -lang perl               (browse only Perl source files)
   Hypersrc.pl  -lang c  -lang c++       (browse both C and C++ source files)
   Hypersrc.pl  -ext .C                  (browse only C++ source files ending with .C). 
   Hypersrc.pl  -descend 5               (descend 5 dir levels when finding src files)
   Hypersrc.pl  -geom 80 160 940 600     (set size/position of main window)
   Hypersrc.pl  -maxtags 9000            (increase tag limit)

Directly Invoking hypersrc
==========================

The only mandatory option for hypersrc is "-ctags-x <file>" which specifies a file
that contains tags in the format used by the -x option of Exuberant ctags, eg:

   ctags  -x *.c  >  tags
   hypersrc  -ctags-x  tags

See "hypersrc -help" for other options.

Unsupported Source Files
========================

If you have a source file that Exuberant ctags doesn't support,
then you could write your own program/script/parser that produces output
that is similar to the -x option of Exuberant ctags,
and pass the output directly to hypersrc (see "Directly Invoking Hypersrc").

Testing
=======

Recent development/testing has been done on:

- GTK+/GLIB 1.2.8
- Exuberant ctags 3.2.1
- Red Hat 6.0/6.1 (x86)
- XFree86 3.3.5 & 4.0.1

Bugs/Problems/Limitations
=========================

- Program silently quits when a tag is clicked.

  Upgrade to GTK+ 1.2.8 if you are using an older version.
  GTK+ 1.2.3 definitely has a bug which hypersrc encounters.
  Other old versions might have this bug also.

  If this problem still persists, as a last resort, try deselecting
  the preference: "Misc / process GTK+ events while busy".
  However, be advised the program won't redraw itself while it is busy.

- The maximum amount of tags is ultimately limited by the #define MAX_TAGS_ABSOLUTE.

- Be warned that trying to browse everything in a very large source tree will
  TAKE A LARGE AMOUNT OF MEMORY and several minutes to start.  Instead browse
  a few subdirs at a time (cd in a subdir, or pass -dirs and/or -descend).

  For example, on a PentiumII, the program will take more than 90 mintues
  and 105 megs when starting to browse the entire Linux 2.4 source!

Legal
=====

hypersrc is "copy-lefted free software" that is distributed and protected
by the GNU General Public License (see "LICENSE.txt").
