                             Configuring TkGnats
                             ===================
Configuration Files
===================

      TkGnats searches for several configuration files. Not one of them is
      mandatory, but obviously it will need to find at least one in order to
      run properly in your environment. The only file supplied with TkGnats
      is "TKGNATSLIB"/tkgnats.config. Never edit this file directly because
      it will just get overwritten when you install new versions of TkGnats.

      Group A:
               user-specified "INI" file   (command line or env variable)
               "TKGNATSLIB"/tkgnatsini
               "TKGNATSLIB"/servers
      Group B:
               "TKGNATSLIB"/tkgnats.config
               "TKGNATSLIB"/tkgnatsrc
               "TKGNATSLIB"/tkgnatsrc."operating_system_name"
               "UserDir"/tkgnatsrc
               "UserDir"/tkgnatsrc."operating_system_name"
               "TKGNATSLIB"/"ServerDir"/tkgnatsrc
               "UserDir"/"ServerDir"/tkgnatsrc

      Within Group A, each file overrides the previous Group A files.
      Nothing in Group B overrides Group A. Within Group B, each file
      overrides the previous Group B files.


Configuration file format
=========================

      The config files are in Tcl, but it should be fairly obvious what you
      have to do. The only trick is that you need quotes around values that
      contain spaces:

      set TkGnats(ORGANIZATION) BugsRUs
      set TkGnats(ORGANIZATION) "BugsRUs Calgary"


TkGnats command line arguments
==============================

      TkGnats has three command line arguments, which are probably rarely used.

      -lib

      This is "TKGNATSLIB". In UNIX, this is patched into the tkgnats script
      by the Makefile. In Windows, this is set by the command Shortcut.

      This can also be specified with the environment variable "TKGNATSLIB".

      -ini

      This is the "INI" file. Not normally used by UNIX users, and assumed to 
      be "UserDir"/tkgnats.ini in Windows.

      This can also be specified with the environment variable "TKGNATSINI".

      -servers

      This is the servers file. "TKGNATSLIB"/servers by default.

      This can also be specified with the environment variable "TKGNATSSERVERS".


Definitions
===========

    o "TKGNATSLIB"

      This is the directory where TkGnats resides. For Windows platforms, this
      is where the distribution was unzipped. For UNIX platforms, this is
      where the Makefile installed TkGnats.

    o "UserDir"

      This is where an individual user's configuration is stored. This can
      include fonts, saved queries, etc. For UNIX users, this is typically
      ~/.tkgnats; for Windows, it's usually a directory called tkgnats in the
      users directory tree.

    o "operating_system_name"

      This comes from the tcl variable tcl_platform(os).  This is equivalent
      to the UNIX "uname -s" command. For example, tkgnatsrc.SunOS, or
      tkgnatsrc.Linux.

    o "ServerDir"

      This only applies if you are accessing a network GNATS daemon. The 5th
      field of the "servers" file is a subdirectory name for specific GNATS
      server information. TkGnats creates the directory "UserDir"/"ServerDir".


TkGnats servers file
====================
        
      The servers file contains everything TkGnats needs to know to communicate
      with a GNATS daemon. In the absence of a servers file, TkGnats on UNIX
      platforms assumes direct access to the GNATS database on local disk.

      The servers file normally just contains a Tcl set statement for the
      TkGnats(Servers) variable. It has one line of six fields for each server
      that you communicate with. The fields are:

      1) TkGnats main menu title

         - this text string appears on the TkGnats main menu.

      2) GNATS_SERVER, the GNATS server hostname
      3) GNATS_PORT,   the GNATS server port number
      4) GNATS_ADDR,   the GNATS server email address

         - The administrator of the GNATS database will give you this info.

      5) "ServerDir"

         - This is used as the subdirectory name for server-specific info for
           TkGnats. You might create the directory "TKGNATSLIB"/"ServerDir"
           for global server-dependent configuration (ser examples below).
           TkGnats creates "UserDir"/"ServerDir" for you; that's where it 
           puts your saved queries.

         - I use a directory name made from the GNATS_ADDR email address up to
           the "@" symbol followed by a dot followed by the GNATS_SERVER. For
           example, If GNATS_ADDR is bugs@support.com and the server is
           gnatssrv.support.com, "ServerDir" would be
           bugs.gnatssrv.support.com.

      6) GNATS server key

         - The administrator of the GNATS database will give you this info.
           It's an alias that GNATS relates to its database.

      Here is an example showing two GNATS servers:

      set TkGnats(Servers) {
      "Widget Bugs" srv.widget.com 1529 bugs@widget.com bugs.srv.widget.com widget
      "FooBar bugs" srv.foobar.com 1529 bugs@foobar.com bugs.srv.foobar.com foobar
      }

      The server entry for UNIX users to tell TkGnats to access GNATS from local
      disk files is shown below. I use this so I can easily test both
      configurations at once. Also, the GNATS_USER (usually gnats) may want
      direct disk access to enable the menu item Actions/DeletePermanently.
      This is the only way to delete PR's from within TkGnats.  Otherwise, I
      highly recommend using the gnatsd over direct disk access.

      set TkGnats(Servers) {
      "Create/Query Problem Reports" {} {} {} {} {}
      "Widget Bugs" srv.widget.com 1529 bugs@widget.com bugs.srv.widget.com widget
      } 

      The most direct way for an individual to override a site-wide "servers"
      file is to use the tkgnats command line "-servers" argument, giving it the
      file name of your personal server file.

GNATS Security
==============

      As of gnats-3.107-beta, a userid/password scheme is available to
      control access to the GNATS database. If required, you can configure
      TkGnats to send your userid and password:

      set TkGnats(ServerPasswords) {
      bugs@widget.com rickm sickm
      bugs@foobar.com foo bar
      }

      The first field of ServerPasswords is from the fourth field of
      the Servers information above. It's the GNATS_ADDR (gnats bugs
      email address) of the server.  The next two fields are your
      userid and password.

Why so many configuration files?
================================

      Well, here are some examples.

    o "TKGNATSLIB"/tkgnatsini

      I found I needed one global file that was read in before any others,
      and that didn't need to be specified explicitly on the command line or
      an environment variable. I actually use code in this file that detects
      which of our sites TkGnats is being run on and then sources a separate
      site-specific file.

    o "TKGNATSLIB"/tkgnats.config

      This is the one that comes with TkGnats. Don't edit it directly. If
      you do, it will get overwritten the next time you update TkGnats unless
      you're careful to make a copy of it first. I suggest copying the
      required bits to "TKGNATSLIB"/tkgnatsrc and editing that.

    o "TKGNATSLIB"/tkgnatsrc."operating_system_name"

      In my office we have SUN and SGI workstations. For postscript viewers,
      we use "pageview" on the SUNs and "xpsview" on the SGIs. Thus, 
      "TKGNATSLIB"/tkgnatsrc.SunOS contains:
              set TkGnats(psPreviewer) "pageview %s"
      and "TKGNATSLIB"/tkgnatsrc.IRIX64 contains:
              set TkGnats(psPreviewer) "xpsview %s"

    o "TKGNATSLIB"/"ServerDir"/tkgnatsrc

      For one of our GNATS databases, we want the default "Class" to be
      "support" when creating a new problem report. In another, it's
      set to "change-request".


Run time Configuration
======================

      TkGnats automatically detects if GNATS is configured "release-based"
      and adds a query fields for the GNATS release-based fields.

      Some TkGnats values can be set at runtime by setting environment
      variables.

    o Instead of command line arguments, you can control tkgnats with the
      environment variables: TKGNATSLIB TKGNATSINI TKGNATSSERVERS

    o TkGnats checks for the environment variable REPLYTO. If it exists,
      TkGnats(EmailAddr) is set to this value rather than TkGnats(LogName).

    o This just applies to UNIX users with a local GNATS database:

      TkGnats checks for the environment variable "GNATS_ROOT".
      If it exists, the GNATS config file $GNATS_ROOT/gnats-adm/config is
      scanned for the following values:

          GNATS_ADDR, GNATS_USER, SUBMITTER

      which reset the following TkGnats variables:

          TkGnats(GNATS_ADDR), TkGnats(GNATS_USER),
          TkGnats(GNATS_ROOT), TkGnats(SUBMITTER)
   
      This happens _after_ "TKGNATSLIB"/tkgnats.config and any and all
      of the optional "tkgnatsrc" files (described above) have been read.
