NAME
htconfig - create/update GLOBAL gsearch.cgi files
SYNOPSIS
htconfig -I [-v] [-z] [-a action] [-p pathdb] cgidir
htconfig --install [--verbose] [--makeghtml] [--formaction=cgi]
[--pathdb=paths-file] cgidir
htconfig [-v] [-u url] [-d GTAGSDBPATH] [-s GTAGSROOT] [htmldir]
htconfig [--verbose] [--url=base-url] [--tags=GTAGSDBPATH]
[--src=GTAGSROOT] [htmldir]
DESCRIPTION
htconfig is a program to create and maintain a centralised cgi
interface for hypertext created with Shigio Yamaguchi’s GLOBAL source
code tag system.
htconfig is used to create the necessary scripts in your system’s
favoured cgi-bin directory, and to maintain the paths database, which
gsearch.cgi uses to locate your hypertext source and the associated
TAGS files. This enables GLOBAL’s hypertext search facilities without
requiring you to enable cgi execution outside of a system-wide cgi-bin
directory.
htconfig acts as a backend for the htmake(1) script which automates the
process of generating hypertext source with the relevant options to
htags(1) and adding required entries to the paths database. htconfig
can also optionally create a centralised ghtml.cgi script, for users of
the htags -c option which creates compressed hypertext with a .ghtml
suffix.
OPTIONS
Common Options
-v, --verbose
uh, you get one guess.
Install Options
These options are to be used during the initial installation of the
centralised cgi mechanism. If you installed this as a binary package
you probably won’t need to use these and can skip to the next section.
Otherwise you must run htconfig --install with any or all of the
following options before using htmake(1) or any of the Database Options
of htconfig.
-I, --install
Creates gsearch.cgi in cgidir and creates the config file
/etc/gtags/htmake.conf if it doesn’t already exist. You must
specify cgidir, there is no default.
-a action, --formaction=action
Puts the default submit action for hypertext created with
htmake(1) into /etc/gtags/htmake.conf when that file is created.
You can edit htmake.conf at any time to change it, or override
its setting from the command line. Setting this to the absolute
url of gsearch.cgi on your system is probably what you want here
unless you understand why not.
eg. --formaction=http://host/cgi-bin/gsearch.cgi
-p paths-database, --pathdb=paths-database
Puts the filesystem location of the paths database file into
/etc/gtags/htmake.conf when that file is created. You must
define a location for the paths database either with this option
or by editing the GSPATHDATA option in htmake.conf before using
htmake(1) or the Database options of htconfig(1).
Due to file system variations there is no default for this. For
Debian GNU/Linux systems the preferred location is:
/var/lib/gsearch/pathdata
One suggestion for *BSD systems would be:
/var/gsearch/pathdata
-z, --makeghtml
Installs the ghtml.cgi script in cgidir. You will also need
edit your http server config to make use of this. For apache
this involves ensuring mod_mime and mod_actions are loaded and
adding lines like:
AddHandler htags-gzipped-html ghtml
Action htags-gzipped-html /cgi-bin/ghtml.cgi
to your httpd.conf file.
Database Options
These options are used to configure and maintain the path database that
allows gsearch.cgi to find your hypertext source and it’s tag files.
You should call htconfig with these options when you move files or
create a new hypertext source tree with htags(1). The path database
requires the hypertext source to be generated with a unique id using
the htags --id=someid option.
When creating a new hypertext source tree you may prefer to use
htmake(1) which invokes htags with the desired options and then calls
htconfig to update the path database as a single operation.
htmldir
specifies the filesystem path to the root of your hypertext
source tree. It defaults to ./HTML in line with htags(1)
defaults and is not required at all if the --url option is used
and your system has lynx(1) availiable,
-u base-url, --url=base-url
the base url of your hypertext source. For best results always
use absolute url’s here.
eg. http://host/~user/mysource
It defaults to file:/htmldir
-d gtagsdbpath, --tags=gtagsdbpath
the filesystem path to the GTAGS files associated with your
source. It defaults to the current directory.
-s gtagsroot, --src=gtagsroot
the filesystem path to the root of your original plaintext
source tree. It defaults to the current directory.
EXAMPLES
To initialise and install cgi and config files:
# htconfig -I -a http://host/cgi-bin/gsearch.cgi \
-p /var/lib/gsearch/pathdata /usr/lib/cgi-bin
To generate hypertext and update path database:
$ cd /usr/src/myprog
$ gtags
$ htags --action=http://host/cgi-bin/gsearch.cgi \
--id=uniqueid --nocgi
$ htconfig
or more simply:
$ cd /usr/src/myprog
$ gtags
$ htmake
To update the path database if you relocate your hypertext, TAGS files,
or the original program source:
$ htconfig -u new-url -d new-gtagsdbpath \
-s new-gtagsdbroot newhtmldir
some of these option may be inferred - See their defaults under
Database Options
The user running htconfig or htmake must have write permission for the
path database.
FILES
/etc/gtags/htmake.conf
gsearch.cgi
ghtml.cgi
path database
BUGS
htconfig currently has no automatic housekeeping mechanism for ’stale’
database entries. This should be fixed RSN.
There is presently no file locking mechanism for database updates.
Attempting simultaneous updates could prove ’surprising’ ^_^
This is alpha software - expect anything!
SEE ALSO
htmake(1), htags(1), global(1).
AUTHOR
Ron Lee <ron@debian.org>
CREDITS
Thanks to Shigio Yamaguchi <shigio@gnu.org> for creating GLOBAL and
releasing it as free software.
A truly cool productivity tool!