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!