xenial (1) htconfig.1.gz

Provided by: global_5.7.1-2_amd64 bug

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!