                             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, or if you
      have multiple databases. The 5th field of the "servers" file is a
      subdirectory name for specific GNATS server or database
      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 information is also used in the case of multiple databases
      on a UNIX system with direct disk access to the databases.

      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    (set to {} for local UNIX disk)
      3) GNATS_PORT,   the GNATS server port number (set to {} for local UNIX disk)
      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 or
           database-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 Database Alias

         - The administrator of the GNATS database will give you this info.
           It's an alias that GNATS relates to its database and is stored
           in the file /etc/gnats-db.conf on the gnatsd server host.

         - For multiple databases on UNIX with direct disk access, this is the
           GNATS_ROOT directory.

      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.

      Note the "2nd Database" entry with the "ServerDir" and "GNATSDatabaseAlias"
      entries:

      set TkGnats(Servers) {
      "Create/Query Problem Reports" {} {} {} {} {}
      "2nd Database For Testing"     {} {} {} test-db /usr/local/share/gnats/test-db
      "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".

TkGnats Configuration controlled by GNATS
=========================================

      The following GNATS configuration parameters are called "client
      hints" because front-end GNATS programs such as gnatsweb and
      TkGnats are free to support any and all of these configuration
      options. These options help give GNATS some degree of
      user-customizable fields until such time as the core GNATS code
      is modified for complete support.

      In the absence of the client hints, the default behaviour of any
      particular front-end client is up to the discretion of the
      client.

      The format is comma-separated field names. For example:

          MANDATORY_FIELDS="Category,Originator,Synopsis,Description"

      These optional parameters may be placed in the GNATS
      configuration file gnats-db/gnatas-adm/config. GNATS itself
      ignores these options.

      Where defaults are suggested, they are just a guideline to get
      the same behaviour as the gnats clients send-pr and edit-pr.

      Please note that GNATS currently has a limit of 255 characters
      per line in the config file, including the parameter name.

      FIELD_ALIASES:
        You can effectively rename any GNATS field with these aliases.
        The alias only affects the client interface. Behind the 
        scenes, the GNATS PR field still has the original name.
        Blanks are not allowed in field names. Field names longer
        than 13 characters will overflow the space alotted for them.
        Format: field(alias)
        Example: Release(Source),Quarter(Cost)

      REQUIRE_AUDIT_TRAIL_ENTRY: 
        Edits to these fields trigger entries in the Audit-Trail.
        "none" signals no fields. "all" signals all fields.

      REQUIRE_AUDIT_TRAIL_REASON: 
        Edits to one or more of these fields triggers the
        prompt of one reason for all changes for the Audit-Trail.
        "none" signals no fields. "all" signals all fields.

      REQUIRE_AUDIT_TRAIL_EMAIL: 
        Edits to one or more of these fields trigger the 
        sending of email notification.
        "none" signals no fields. "all" signals all fields.

      MANDATORY_FIELDS:
        SendPR will insist that new PRs have values for these fields.
        EditPR will insist that editied PRs have values for these fields.
        "none" signals no fields. "all" signals all fields, but doesn't
        include Audit-Trail, Unformatted or Release-Note in EditPR
        because these fields are usually added by GNATS and are often
        blank for the first part of a PRs life. You can always add these
        fields if you wish.

      SUPPRESSED_FIELDS: 
        Fields to suppress from view in all front-end views.
        SUPPRESSED_FIELDS override MANDATORY_FIELDS if a field
        appears in both lists.

      SUPPRESSED_SEND_FIELDS:  See "unless" options below.
        Fields not to present in SendPR.
        Format: field[(unless)]
        Default: State,Responsible,Release-Note,Unformatted,Audit-Trail
        Example: State,Responsible(edit),Release-Note,Audit-Trail

      SUPPRESSED_EDIT_FIELDS:  See "unless" options below.
        Fields not to present, or to present read-only, in EditPR.
        It is suggested that front-ends do not allow editing Arrival-Date,
        Last-Modified and Closed-Date, since these are maintained by GNATS.
        Format: field[(unless)]
        Example: Audit-Trail(admin)

      SUPPRESS "unless" options:
        Finer control over the showing of fields in SendPR and EditPR.
        In SendPR, the field is suppressed. 
        In EditPR, the field is suppressed or shown read-only, at the
                   discression or configuration of the front-end.

        Suppress fields:

        user      - unless the user of the front-end asks for it.
        edit      - unless the user has edit access.
        edituser  - unless the user has edit access and
                    the user of the the front-end asks for it.   
        admin     - unless the user has admin access.
        adminuser - unless the user has admin access and
                    the user of the the front-end asks for it.   

      TkGnats searches the GNATS config file (--list-config|LCFG) for
      parameters with these names.

      User specification for not suppressing fields are supplied in
      TkGnats config files in the format:

        set TkGnats(${field}In${app}Pr) 1

      where $field is any field such as State or Responsible, and $app
      is Send or Edit. For example:

        set TkGnats(StateInSendPr) 1

      The TkGnats defaults for these parameters are:

      FIELD_ALIASES              ""
      REQUIRE_AUDIT_TRAIL_ENTRY  "Responsible,State,Priority,Severity,Date-Required"
      REQUIRE_AUDIT_TRAIL_REASON "Responsible,State,Priority,Severity,Date-Required"
      REQUIRE_AUDIT_TRAIL_EMAIL  "Responsible,State,Priority,Severity,Date-Required"
      SUPPRESSED_FIELDS          "none"
      SUPPRESSED_SEND_FIELDS     "State,Responsible,Release-Note,Unformatted,Audit-Trail"
      SUPPRESSED_EDIT_FIELDS     "none"
      MANDATORY_FIELDS           "Class,State,Priority,Severity,Confidential,Category,
                                  Submitter-Id,Originator,Synopsis,Description"
        
      All field names are the original GNATS field names, not any aliases
      that you may have specified in FIELD_ALIASES.

      When creating a new PR, suppressed fields are either sent with
      CreateDefault{FIELD} values that TkGnats is configured to use or
      not sent at all, in which case GNATS itself will load blanks or
      default values. The fields are actually still seen and parsed by
      TkGnats when viewing and editing, but they just are left off the
      various windows. There are no default fields that are
      ignored. "Number" and "Text-Fields" (in the query window) can't
      be ignored, and at least one multitext field has to be not
      ignored.

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 TkGnats searches the GNATS config file (--list-config|LCFG) for
      TKGNATS_MIN_VERSION, in which case it will abort if you are running a
      version of TkGnats older than that specified. The numbers are compared
      as strings, so 3.0.2 is greater than 3.0.19. I'll have to make sure
      that all future TkGnats versions are compatable with this check.

    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 next four optional "tkgnatsrc" files (see Groub B above)
      have been read, but before the two optional "ServerDir"/tkgnatsrc
      files are read.
