--- name: "htconfig" section: "1" platform: "linux" package: "global" version: "5.7.1-2" release: "Debian 8 (Jessie)" platforms: ["linux"] url: "https://new.carta.tech/htconfig" --- # htconfig(1) create/update GLOBAL gsearch.cgi files ## 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)](/htmake/1.md) script which automates the process of generating hypertext source with the relevant options to [**htags**(1)](/htags/1.md) 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)](/htmake/1.md) 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)](/htmake/1.md) 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)](/htmake/1.md) or the Database options of [**htconfig**(1)](/htconfig/1.md).\ 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)](/htags/1.md). 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)](/htmake/1.md) 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)](/htags/1.md) defaults and is not required at all if the **--url** option is used *and* your system has [**lynx**(1)](/lynx/1.md) 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)](/htmake/1.md), **htags**(1), **global**(1). ## AUTHOR Ron Lee \ ## CREDITS Thanks to Shigio Yamaguchi \ for creating **GLOBAL** and releasing it as free software.\ A truly cool productivity tool!