1I made this list for myself to help sort out design and configuration issues
2as I was adding support for the GNATS newtork daemon (gnatsd). I haven't
3clearly marked what applies to local disk access or network daemon access.
4
5
6GNATS programs executed by TkGnats
7==================================
8
9o  query-pr (local GNATS) / nquery-pr (network GNATS)
10
11    - tkpr_library.tcl (check_release_based_batch) to determine if GNATS is Release Based
12        - tkpr_library.tcl (get_gnats_config) calls check_release_based
13            - called by tkeditpr, tkgnats, tkquerypr, tksendpr, tkviewpr
14    - tkpr_library.tcl (get_gnats_list_batch) to get lists from GNATS
15        - tkpr_library.tcl (get_gnats_list)
16            - get_categories / get_submitters / get_responsible
17                - tkeditpr, tkgnats, tkquerypr, tksendpr, tkviewpr
18    - tkpr_library.tcl (get_pr_medium_text_batch) to get medium list of PR
19        - tkpr_library.tcl (delete_pr_local) to get Category and State only
20            - tkquery-pr (selection_Delete_cmd) to delete PRs
21        - tkprintpr.tcl (Medium) to get medium listing of PRs for printing
22    - tkpr_library.tcl (get_pr_medium_text_batch) to get medium list of PR
23        - tkprintpr.tcl (print_parsepr_medium) to get medium listing of PRs for printing
24            - print/Synopsis_Summary to get Number,Arrival-Date,Responsible,Category,
25                                            Priority,Synopsis,Last-Modified,Originator,
26                                            State,Severity.
27    - tkpr_library.tcl (get_pr_full_text_batch) to get full list of PR
28        - tkpr_library.tcl (lock_pr) to get full list of PR for editing when GNATS_ACCESS=local
29            - see npr-edit below for callers of lock-pr
30        - tkprintpr.tcl (Raw_Data) to get full listing of PRs for printing
31        - tkprintpr.tcl (print_parsepr) to get full listing of PRs for printing
32            - tkprintpr.tcl (Full) to get full listing of PRs for printing
33            - print/Description_Summary to get Number,Synopsis,State,Description
34                                        (Can't use medium)
35        - tkquerypr (selection_Email_cmd) to get Reply-To,Responsible,From,Category,Synopsis
36                                        (Can't use medium)
37        - tkviewpr (main) to get full list of PR for viewing Raw or Formatted
38    - tkquerypr (query_cmd_batch) to perform actual database queries
39
40o  pr-edit (local GNATS) / npr-edit (network GNATS)
41
42    - tkpr_library.tcl (lock_pr_batch) to lock PR for editing and to get full list of PR
43      for editing (npr-edit)
44        - tkeditpr (edit_window) to lock PR for editing
45        - tkeditpr (real_file_report) to re-lock PR: this is a get-around for a
46                   bug in gnatsd that unlocks a pr when the update fails
47        - tkpr_library.tcl (delete_pr_local) to lock PR for deleting
48    - tkeditpr (real_file_report_batch) to send edited PR back to GNATS
49    - tkpr_library.tcl (unlock_pr_batch) to unlock PR
50        - tkeditpr (edit_window) to unlock the PR after updating
51        - tkpr_library.tcl (delete_pr_local) to unlock the PR after deleting
52
53
54External programs executed by TkGnats
55=====================================
56
57o  TkGnats(Mailer) - sendmail, if TkGnats(MailMethod)=mailer
58o  TkGnats(InfoReader) - tkinfo, xinfo, etc; optional in tkgnats main menu
59o  TkGnats(MailReader) - pine, etc; optional in tkgnats main menu
60o  groups in tkpr_library.tcl (TkGnats_config) - to get GROUP list
61o  id in tkpr_library.tcl (TkGnats_config) - to get USER and GROUP
62o  whoami optionally in tkgnats.config, if id fails and env(USER) and env(LOGNAME) don't exist
63o  true in tkpr_library.tcl (do_reap) (protected by catch)
64o  ypcat|grep|cut in tkpr_library.tcl (fullname_from_logname) (protected with catch)
65    - tkpr_library.tcl (TkGnats_config) calls fullname_from_logname to set TkGnats(FullName)
66    - tksendpr uses TkGnats(FullName) as the default for Originator
67o  /bin/sh -c in tkquery_pr (perform_print_cmd) to execute Print(Previewer,*)
68    - can this be just directly exec'd? No, because it's chained to rm tempfile in background
69o  uname, arch, xdpyinfo|fgrep in tksendpr to get Environment defaults (optional)
70    - tcl_platform and [info hostname] values are used if uname fails
71o  sort, if TkGnats(QuerySortMethod)=external, to sort queries for the query listbox
72o  groff in tkprintpr.tcl is the input to Print(Printspooler,*)
73
74
75GNATS configuration details needed by TkGnats
76=============================================
77
78o GNATS_ROOT: TkGnats(GNATS_ROOT)
79
80    - set in tkgnats.config by the Makefile
81    - used in Makefile to read $(GNATS_ROOT)/gnats-adm/config which in turn sets
82      GNATS_ADDR, GNATS_USER and SUBMITTER in tkgnats.config
83    - tkpr_library.tcl (TkGnats_config) looks for env variable GNATS_ROOT and resets
84      GNATS_ADDR, GNATS_USER, SUBMITTER and GNATS_ROOT itself
85    - tkpr_library.tcl (delete_pr_local) gets the GNATS index from
86      $TkGnats(GNATS_ROOT)/gnats-adm/index
87      and the PR pathname from $TkGnats(GNATS_ROOT)/$full_id for deletion
88
89o GNATS_SITE: TkGnats(GNATS_SITE)
90
91    - REMOVED. No longer used. See SUBMITTER.
92
93o GNATS_USER: TkGnats(GNATS_USER)
94
95    - set in tkgnats.config by the Makefile
96    - tkpr_library.tcl (TkGnats_config) looks for env variable GNATS_ROOT and resets
97      this from the GNATS config file
98    - this is used for the default TkGnats(delete_authorized_users) in tkgnats.config
99      which is only required for GNATS_ACCESS=local.
100
101o GNATS_ADDR: TkGnats(GNATS_ADDR)
102
103    - set in tkgnats.config by the Makefile or gotten from the "servers" file info
104    - tkpr_library.tcl (TkGnats_config) looks for env variable GNATS_ROOT and resets
105      this from the GNATS config file
106    - tkpr_library.tcl (email_originator) as the recipient of the follow-up email
107    - tksendpr (send_report) as the recipient of the email bug report
108
109o LIBEXECDIR: TkGnats(GNATS_LIBEXECDIR)
110
111    - set in tkgnats.config by the Makefile
112    - tkpr_library.tcl (TkGnats_config) as $TkGnats(GNATS_LIBEXECDIR)/gnats/pr-edit
113      and npr-edit to get the path for the GNATS (n)pr-edit program
114
115o SUBMITTER
116
117    - set in tkgnats.config by the Makefile
118    - tkpr_library.tcl (TkGnats_config) looks for env variable GNATS_ROOT and resets
119      this from the GNATS config file
120    - tkpr_library.tcl (TkGnats_config) uses this as the default Organization if
121      nothing else is found
122    - tksendpr uses this to set the default Submitter in the dialog
123
124o GNATS category list
125
126    - TkGnats(CategoryList)    in tkpr_library.tcl (get_category_list)
127    - got from (n)query-pr or direct socket call
128
129o GNATS submitter list
130
131    - TkGnats(SubmitterList)   in tkpr_library.tcl (get_submitter_list)
132    - got from (n)query-pr or direct socket call
133
134o GNATS responsible list
135
136    - TkGnats(ResponsibleList) in tkpr_library.tcl (get_responsible_list)
137    - got from (n)query-pr or direct socket call
138
139o TkGnats(ReleaseBased)
140
141    - set automatically in tkpr_library.tcl (get_gnats_config / check_release_based)
142    - used throughout to determine if the Keywords field is used
143
144o TkGnats(GNATS_ACCESS)
145
146    - set in tkpr_library.tcl(TkGnats_config_rc) to local if GNATS_SERVER is blank,
147      otherwise set to network
148    - tkeditpr (real_file_report) to know to do the get-around for a bug in gnatsd
149      that unlocks a pr when the update fails
150    - tkpr_library.tcl (TkGnats_config) to inhibit TkGnats(delete_authorized) if not a
151      local GNATS system
152    - tkpr_library.tcl (lock_pr) to know if pr-edit is meant to return the full text of the
153      PR or not
154
155o TkGnats(GNATS_ACCESS_METHOD) (where used/how set/etc)
156
157    - defaults to socket if GNATS_ACCESS is network, but can be set to batch to
158      force usage of nquery-pr and npr-edit (not recommended)
159
160o TkGnats(GNATS_SERVER)
161
162    - set from the "servers" file info
163    - if GNATS_ACCESS=network: used as the --host argument to nquery-pr and npr-edit
164      (GNATS_ACCESS_METHOD=batch) or gnatsd socket (GNATS_ACCESS_METHOD=socket)
165
166o  TkGnats(GNATS_PORT)
167
168    - set from the "servers" file info
169    - if GNATS_ACCESS=network: used as the --port argument to nquery-pr and npr-edit
170      (GNATS_ACCESS_METHOD=batch) or gnatsd socket (GNATS_ACCESS_METHOD=socket)
171
172
173Other TkGnats configuration issues
174==================================
175
176o  tkgnats.config
177
178    - this file is sourced in tkpr_library.tcl (TkGnats_config), where only TkGnats
179      and env are declared global.
180
181o  TkGnats(EmailAddr)
182
183    - tkpr_library.tcl (TkGnats_config) checks for the environment variable REPLYTO. If it exists,
184      TkGnats(EmailAddr) is set to this value rather than TkGnats(LogName)
185    - tkeditpr (real_file_report) to know who is doing the edit so that name can be
186      omitted from receiving notification of the edit
187    - tkeditpr (real_file_report) as the name in the Audit Trail "Responsible-Changed-By:"
188      and "State-Changed-By:" entries, along with TkGnats(FullName)
189    - tkeditpr (real_file_report) as the From and Reply-To mail headers of the mail being sent
190    - tkpr_library.tcl (email_send) as the From and Reply-To mail headers of the mail being sent
191    - tkpr_library.tcl (email_send) to know who is sending the mail so that name can be
192      omitted from receiving notification of the edit
193
194o  TkGnats(ENVIRONMENT)
195
196    - tksendpr.tcl will use this to set the initial value of the Environment text when
197      creating new problem reports. Otherwise, the output of the UNIX command "uname -a"
198      (or the tcl_platform Tcl variables) is used.
199
200o  TkGnats(LogName)
201
202    - tkpr_library.tcl (TkGnats_config) sets by searching in this order:
203        - check the first output field of the id command
204        - then check USER environment variable
205        - then try LOGNAME environment variable
206        - then try running whoami
207    - tkpr_library.tcl (TkGnats_config) to set TkGnats(EmailAddr) if the environment
208      variable REPLYTO isn't available
209    - tkeditpr (main) to make sure root doesn't edit PRs
210    - tkpr_library.tcl (TkGnats_config) to compare against TkGnats(edit_authorized)
211    - tkpr_library.tcl (TkGnats_config) to compare against TkGnats(delete_authorized)
212    - tkpr_library.tcl (fullname_from_logname) to search "ypcat passwd" or /etc/passwd
213    - tkpr_library.tcl (lock_pr_batch) as the --lock argument to (n)pr-edit or for the
214      LOCK command when calling the gnatsd socket (lock_pr_socket)
215    - tksendpr (main) to make sure root doesn't send PRs
216    - used in the filename of various temporary files
217    - used in iconnames
218
219o  TkGnats(GroupName)
220
221    - tkpr_library.tcl (TkGnats_config) sets by searching in this order:
222        - first check the output of the groups command for a list of groups
223        - then check the second output field of the id command for a primary group
224        - then check GROUP environment variable
225    - tkpr_library.tcl (TkGnats_config) to compare against TkGnats(edit_authorized)
226    - tkpr_library.tcl (TkGnats_config) to compare against TkGnats(delete_authorized)
227
228o  TkGnats(ORGANIZATION)
229
230    - tkpr_library.tcl (TkGnats_config) sets by searching in this order:
231        - environment variable ORGANIZATION, which is either a filename whose
232          contents is used or else a string to use
233        - $env(HOME)/.signature, which is a filename whose contents is used
234        - if the above aren't found then $TkGnats(SUBMITTER) is used
235
236o  TkGnats(CreateDefaultCategory)
237
238    - tksendpr (main) to use as a pre-selected category default
239
240o  TkGnats(QuerySortMethod)
241
242    - tkpr_library.tcl (TkGnats_config) sets or overrides TkGnats(QuerySortMethod)
243      (internal or external)
244    - determines if Query listbox will be sorted by Tcl code (internal) or the unix
245      "sort" program (external). The internal sort runs as fast or faster than the
246      external sort in Tcl/Tk 8.0 due to the byte compiler. The internal sort
247      is mandatory for Win95/98/NT.
248    - tkpr_library.tcl (build_sort_cmd) to build sort keys
249    - tkquerypr (perform_sort_cmd) to sort listbox
250
251o  TkGnats(SMTP_SERVER)
252
253    - MailMethod is either mailer (like sendmail) or smtp to connect directly to
254      an smtp server when sending mail. smtp is mandatory for Win95/98/NT.
255
256o  TkGnats(SMTP_PORT)
257
258    - defaults to the standard 25.
259
260o TkGnats(GNATS_BINDIR)
261
262    - This can be set if the GNATS programs query-pr and nquery-pr aren't in your path.
263
264Full list of TkGnats array variables
265====================================
266
267o  This list can be viewed from the Help menu on any TkGnats window.
268
269
270Full list of environment variables checked by TkGnats
271=====================================================
272
273environment variable            sets TkGnats variable
274--------------------            ---------------------
275
276env(GNATS_ROOT)                 TkGnats(GNATS_ROOT), TkGnats(GNATS_ADDR),
277                                TkGnats(GNATS_USER), TkGnats(SUBMITTER)
278env(GROUP)                      TkGnats(GroupName) (if unix 'groups' and 'id' cmds not available)
279env(HOME)                       TkGnats(HOME)
280env(HOSTNAME)                   TkGnats(HOSTNAME)
281env(LOGNAME)                    TkGnats(LogName) (if env(USER) not found)
282env(ORGANIZATION)               TkGnats(ORGANIZATION)
283env(REPLYTO)                    TkGnats(EmailAddr) (otherwise use TkGnats(LogName))
284env(TKGNATSINI)                 TkGnats(TKGNATSINI)
285env(TKGNATSLIB)                 TkGnats(TKGNATSLIB) (and TkGnats(lib), which is actually used)
286env(TKGNATSSERVERS)             TkGnats(TKGNATSLIB) (and TkGnats(lib), which is actually used)
287env(USER)                       TkGnats(LogName) (if unix 'id' cmd not available)
288