Man Linux: Main Page and Category List

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!