HTCONFIG(1)						       GLOBAL cgi Utilities						       HTCONFIG(1)

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 in-
	      volves 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  ht-
       config 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!

Debian GNU/Linux						   27 March 1999						       HTCONFIG(1)