Changes to gnats/doc/gnats-faq.texi

[Hans-Albert Schneider]

Index: gnats/doc/gnats-faq.texi
diff -c gnats/doc/gnats-faq.texi:1.9 gnats/doc/gnats-faq.texi:1.10
*** gnats/doc/gnats-faq.texi:1.9        Sun Jul 21 17:51:59 2002
--- gnats/doc/gnats-faq.texi    Wed Oct  2 18:45:22 2002
***************
*** 111,116 ****
--- 111,117 ----
  
  @menu
  * What is GNATS::               A very short overview
+ * How to pronounce it::         
  * Get it::                      Where to get @sc{gnats}
  * Versions::                    Which versions are available?
  * Mailing Lists::               E-mail discussion lists
***************
*** 181,186 ****
--- 182,198 ----
  configured.
  
  
+ @node     How to pronounce it
+ @comment  node-name,     next,   previous,  up
+ @section  How is "@sc{gnats}" pronounced?
+ 
+ Q: So, How can I pronounce "@sc{gnats}?"  Should I pronounce "G"?
+ 
+ It has been reported that the original developers pronounced the "G".
+ (This is unlike the little insect called "gnat" where the "G" is not
+ pronounced.)
+ 
+ 
  @node     Get it
  @comment  node-name,  next,     previous,      up
  @section Where do I get it?
***************
*** 368,373 ****
--- 380,386 ----
  * Add a database::              How to create a new database
  * Renaming a Category::         
  * Changing Fields::             
+ * Append-only Audit-Trail::     
  @end menu
  
  @node Add a database
***************
*** 464,469 ****
--- 477,485 ----
  GNATS_ADMIN="gnats-admin@@bugs.example.com"
  @end smallexample
  
+ If your @sc{gnats} sits behind a firewall and needs to exchange mails
+ with the outside world, see also @ref{Outgoing mail bounces}.
+ 
  @end enumerate
  
  @noindent
***************
*** 521,526 ****
--- 537,545 ----
  database, but its name.  (In case you prefer the long form of the
  option, it is now @samp{--database} instead of @samp{--directory}.)
  
+ If your @sc{gnats} sits behind a firewall and needs to exchange mails
+ with the outside world, see also @ref{Outgoing mail bounces}.
+ 
  @end enumerate
  
  
***************
*** 588,593 ****
--- 607,642 ----
  This is currently not configurable.
  
  
+ @node Append-only Audit-Trail
+ @comment  node-name,  next,  previous,  up
+ @subsection How do make Audit-Trail append-only?
+ 
+ Mike Hoolehan wanted a "bugzilla-ish appending audit trail", i.e.,
+ Audit-Trail can not be changed arbitrarily, only appended.
+ 
+ He posted the following solution to the @email{help-gnats@@gnu.org}
+ mailing list:
+ 
+ First, set the Audit-Trail field to read-only.  Then add this:
+ 
+ @example
+ field "Add-To-Audit-Trail" {
+    description "Add a log entry to Audit Trail"
+    multitext { default "\n" }
+    on-change  {
+         add-audit-trail
+         audit-trail-format {
+         format "---- Comments by %s on %s ----\n %s\n\n" #whatever you like
+         fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue" }
+         }
+     }
+     on-change {
+         set-field "Add-To-Audit-Trail" { "\n" }
+     }
+ }
+ @end example
+ 
+ 
  @node Gnatsd
  @comment  node-name,  next,  previous,  up
  @section Gnatsd, the @sc{gnats} Daemon
***************
*** 828,836 ****
  
  @menu
  * queue-pr not available::      
  @end menu
  
! @node queue-pr not available,  , E-Mail, E-Mail
  @comment  node-name,  next,  previous,  up
  @subsubheading queue-pr not available for sendmail programs
  
--- 877,886 ----
  
  @menu
  * queue-pr not available::      
+ * Outgoing mail bounces::       
  @end menu
  
! @node queue-pr not available, Outgoing mail bounces, E-Mail, E-Mail
  @comment  node-name,  next,  previous,  up
  @subsubheading queue-pr not available for sendmail programs
  
***************
*** 849,854 ****
--- 899,937 ----
  @noindent
  Replace @address@hidden/usr/local/libexec/gnats/queue-pr}} by the real path to
  @file{queue-pr}.
+ 
+ 
+ @node Outgoing mail bounces
+ @comment  node-name,  next,  previous,  up
+ @subsubheading Mail from @sc{gnats} bounces
+ 
+ You are getting bounce mails like this:
+ 
+ @example
+    ----- Transcript of session follows -----
+ ... while talking to mail.example.com.:
+ >>> MAIL From:<gnats@@mymachine.subdomain.example.com> SIZE=334
+ <<< 501 5.1.8 <gnats@@mymachine.subdomain.example.com>...
+       Domain of sender address gnats@@mymachine.subdomain.example.com does 
not exist
+ @end example
+ 
+ Probably your @sc{gnats} sits behind a firewall, but it needs to
+ exchange mails with the world outside the firewall.  Make sure that
+ @var{GNATS_ADDR} is valid outside.
+ 
+ This is what probably happens behind the scenes: On its way to the
+ outside world, the sender address of the mail gets rewritten to
+ something "official" (like @code{Hans-Albert.Schneider@@example.com}, as
+ opposed to @code{me@@mymachine.subdomain.example.com}).  This is
+ especially necessary if the internal hosts are not visible outside.  If
+ your outgoing mail gateway still sees the internal address, it complains
+ with a message like the above (it has probably checked
+ @code{mymachine.subdomain.example.com} with your organization's external
+ DNS server, which does not know @code{mymachine}).
+ 
+ To solve this problem, get an "official" address for your @sc{gnats}
+ system, e.g., tool-bugs@@example.com, and use that one for
+ @var{GNATS_ADDR}.