.TH HTCONFIG 1 "27 March 1999" "Debian GNU/Linux" "GLOBAL cgi Utilities" .\" Copyright (c) 1999, 2000 Ron Lee. All rights reserved. .\" This text may be distributed under the same terms as the htconfig source. .\" All copies of this manual must acknowledge the author and include the .\" above copyright statement. .\" .\" In cases of discrepancy the source is authorative. Duh 8^} .SH NAME htconfig \- create/update GLOBAL gsearch.cgi files .SH SYNOPSIS .nh .B htconfig -I .RB [ -v ] .RB [ -z ] .RB [ -a .IR action ] .RB [ -p .IR pathdb ] .I cgidir .HP .B htconfig --install .RB [ --verbose ] .RB [ --makeghtml ] .RB [ --formaction=\fIcgi\fP ] .RB [ --pathdb=\fIpaths-file\fP ] .I cgidir .HP .B htconfig .RB [ -v ] .RB [ -u .IR url ] .RB [ -d .IR GTAGSDBPATH ] .RB [ -s .IR GTAGSROOT ] .RI [ htmldir ] .HP .B htconfig .RB [ --verbose ] .RB [ --url=\fIbase-url\fP ] .RB [ --tags=\fIGTAGSDBPATH\fP ] .RB [ --src=\fIGTAGSROOT\fP ] .RI [ htmldir ] .hy .SH "DESCRIPTION" .B htconfig is a program to create and maintain a centralised cgi interface for hypertext created with .nh Shigio Yamaguchi's .hy \fBGLOBAL\fP source code tag system. .PP .B htconfig is used to create the necessary scripts in your system's favoured cgi-bin directory, and to maintain the \fIpaths database\fP, which .B gsearch.cgi uses to locate your hypertext source and the associated TAGS files. This enables \fBGLOBAL\fP's hypertext search facilities without requiring you to enable cgi execution outside of a system-wide cgi-bin directory. .PP .B htconfig acts as a backend for the \fBhtmake\fP(1) script which automates the process of generating hypertext source with the relevant options to \fBhtags\fP(1) and adding required entries to the paths database. .B htconfig can also optionally create a centralised \fBghtml.cgi\fP script, for users of the \fBhtags -c\fP option which creates compressed hypertext with a .ghtml suffix. .SH OPTIONS .SS Common Options .TP .B -v, --verbose uh, you get one guess. .SS 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 \fImust\fP run .nh .B "htconfig --install" .hy with any or all of the following options \fIbefore\fP using \fBhtmake\fP(1) or any of the \fBDatabase Options\fP of \fBhtconfig\fP. .TP .B -I, --install Creates \fBgsearch.cgi\fP in \fIcgidir\fP and creates the config file .nh \fI/etc/gtags/htmake.conf\fP .hy if it doesn't already exist. You \fImust\fP specify \fIcgidir\fP, there is no default. .TP .B -a action, --formaction=action Puts the default submit action for hypertext created with \fBhtmake\fP(1) into .nh \fI/etc/gtags/htmake.conf\fP .hy when that file is created. You can edit \fIhtmake.conf\fP at any time to change it, or override its setting from the command line. Setting this to the absolute url of \fBgsearch.cgi\fP on your system is probably what you want here unless you understand why not. .br .nh eg. .B --formaction=http://host/cgi\-bin/gsearch.cgi .hy .TP .B -p paths-database, --pathdb=paths-database Puts the filesystem location of the \fIpaths database\fP file into .nh \fI/etc/gtags/htmake.conf\fP .hy when that file is created. You \fImust\fP define a location for the \fIpaths database\fP either with this option or by editing the \fBGSPATHDATA\fP option in \fIhtmake.conf\fP before using .nh \fBhtmake\fP(1) .hy or the Database options of \fBhtconfig\fP(1). .br Due to file system variations there is no default for this. For Debian GNU/Linux systems the preferred location is: .br .I /var/lib/gsearch/pathdata .br One suggestion for *BSD systems would be: .br .I /var/gsearch/pathdata .TP .B -z, --makeghtml Installs the ghtml.cgi script in \fIcgidir\fP. You will also need edit your http server config to make use of this. For \fBapache\fP this involves ensuring \fImod_mime\fP and \fImod_actions\fP are loaded and adding lines like: .br .B AddHandler htags-gzipped-html ghtml .br .B Action htags-gzipped-html \fI/cgi-bin/ghtml.cgi\fP .br to your \fIhttpd.conf\fP file. .SS Database Options These options are used to configure and maintain the \fBpath database\fP that allows gsearch.cgi to find your hypertext source and it's tag files. You should call \fBhtconfig\fP with these options when you move files or create a new hypertext source tree with \fBhtags\fP(1). The \fBpath database\fP requires the hypertext source to be generated with a \fIunique id\fP using the \fBhtags --id=someid\fP option. .PP When creating a \fInew\fP hypertext source tree you may prefer to use \fBhtmake\fP(1) which invokes \fBhtags\fP with the desired options and then calls \fBhtconfig\fP to update the \fBpath database\fP as a single operation. .TP .I htmldir specifies the filesystem path to the root of your hypertext source tree. It defaults to \fI./HTML\fP in line with \fBhtags\fP(1) defaults and is not required at all if the \fB--url\fP option is used \fIand\fP your system has \fBlynx\fP(1) availiable, .TP .B -u base-url, --url=base-url the base url of your hypertext source. For best results always use absolute url's here. .br eg. \fIhttp://host/~user/mysource\fP .br It defaults to \fIfile:/htmldir\fP .TP .B -d gtagsdbpath, --tags=gtagsdbpath the filesystem path to the \fBGTAGS\fP files associated with your source. It defaults to the current directory. .TP .B -s gtagsroot, --src=gtagsroot the filesystem path to the root of your original plaintext source tree. It defaults to the current directory. .SH EXAMPLES To initialise and install cgi and config files: .PP # htconfig -I -a http://host/cgi-bin/gsearch.cgi \\ -p /var/lib/gsearch/pathdata /usr/lib/cgi-bin .PP To generate hypertext and update \fBpath database\fP: .PP $ cd /usr/src/myprog .br $ gtags .br $ htags --action=http://host/cgi-bin/gsearch.cgi \\ --id=uniqueid --nocgi .br $ htconfig .PP or more simply: .PP $ cd /usr/src/myprog .br $ gtags .br $ htmake .PP To update the \fBpath database\fP if you relocate your hypertext, TAGS files, or the original program source: .PP $ htconfig -u new-url -d new-gtagsdbpath \\ -s new-gtagsdbroot newhtmldir .PP .RS some of these option may be inferred - See their defaults under .B Database Options .RE .PP The user running \fBhtconfig\fP or \fBhtmake\fP must have write permission for the .B path database. .SH FILES .I /etc/gtags/htmake.conf .br .I gsearch.cgi .br .I ghtml.cgi .br .I path database .SH BUGS .B htconfig currently has no automatic housekeeping mechanism for 'stale' database entries. This should be fixed RSN. .PP There is presently no file locking mechanism for database updates. Attempting simultaneous updates could prove 'surprising' ^_^ .PP This is \fIalpha\fP software \- expect anything! .SH "SEE ALSO" .BR htmake (1), " htags" (1), " global" (1). .SH AUTHOR Ron Lee .SH CREDITS Thanks to Shigio Yamaguchi for creating \fBGLOBAL\fP and releasing it as free software. .br A truly cool productivity tool!