Changes to gnats/doc/gnats.texi

[Yngve Svendsen]

Index: gnats/doc/gnats.texi
diff -c gnats/doc/gnats.texi:1.33 gnats/doc/gnats.texi:1.34
*** gnats/doc/gnats.texi:1.33   Tue Oct 15 15:31:59 2002
--- gnats/doc/gnats.texi        Sun Oct 20 18:30:49 2002
***************
*** 155,160 ****
--- 155,163 ----
  @item
  Appendix D @emph{Querying using regular expressions}
  @*Version 4 complete.
+ 
+ @item
+ Appendixes E and F were written specifically for GNATS 4.
  @end itemize
  
  @menu
***************
*** 166,171 ****
--- 169,175 ----
  * gnatsd::                The GNATS network server.
  * Access Control::        Controlling access to GNATS databases.
  * Regexps::               Querying using regular expressions.
+ * dbconfig recipes::      Useful dbconfig tricks.
  * Support::               GNATS related sites and mailing lists.
  * Index::
  @end menu
***************
*** 2002,2007 ****
--- 2006,2138 ----
  Again, see @ref{Regular Expression Syntax,,Regular Expression
  Syntax,regex,Regex}, for a much more complete discussion on regular
  expression syntax.
+ 
+ @c ===============================================================
+ 
+ @node dbconfig recipes
+ @appendix @file{dbconfig} recipes
+ @cindex dbconfig
+ @cindex @file{dbconfig} recipes
+ 
+ The @file{dbconfig} file (@ref{dbconfig file,,The @file{dbconfig}
+ file}) is the heart of any @sc{gnats} installation.  It contains some
+ very powerful machinery, something which this appendix tries to
+ illustrate.
+ 
+ We provide a range of examples that are both intended to be useful in
+ their own right and to serve as starting points or building blocks for
+ your own modifications.
+ 
+ @subsubheading Provide Gnatsweb URL in initial response
+ 
+ Sites that have Gnatsweb installed may wish to modify the response
+ e-mail which is sent to the submitter of a PR so that it includes a
+ URL where the status of the PR can be monitored.  In order to allow
+ this, you should first create an entry in @file{gnatsd.user_access}
+ which allows viewing of PRs in your database
+ (@xref{gnatsd.user_access,,The @file{gnatsd.user_access} file}.)
+ 
+ Next, locate the entry @code{mail-format
+ "initial-response-to-submitter"} in the @file{dbconfig} file of your
+ database and add the following @emph{before} the line reading ``The
+ individual assigned...'' in the @code{body} section:
+ 
+ @verbatim
+ \nYou can follow the status of this report on\n\
+ http://hostname/cgi-bin/scriptname?\n\
+ cmd=view&database=dbname&user=username&\n\
+ password=passwd&pr=%s\n\n\
+ @end verbatim
+ 
+ @noindent
+ Substitute @code{hostname}, @code{cgi-bin} and @code{scriptname} as
+ appropriate for the setup of your web server.  The part before the
+ @samp{?} would typically look something like
+ @code{http://www.example.com/cgi-bin/gnatsweb.pl}.  Substitute the
+ name of your database for @code{dbname}, and the username and password
+ of the user with @code{view} rights for @code{username} and
+ @code{passwd}.
+ 
+ @noindent
+ Next, add a @code{Number} to the @code{fields} list statement inside
+ the @code{body} so it reads as follows:
+ 
+ @verbatim
+ fields { "Category" "Number" "Number" "Responsible"
+          "Category" "Responsible" "Synopsis"
+          "Arrival-Date" }
+ @end verbatim
+ 
+ @subsubheading State full name of responsible in initial response
+ 
+ The initial e-mail response to the submitter of a PR identifies the
+ responsible person assigned to the PR as follows: ``The individual
+ assigned to look at your report is: @var{GNATS username}''.  Some
+ sites may wish to modify this so that the full name of the responsible
+ person is used instead of the @sc{gnats} user name.
+ 
+ The full name is contained in the @code{fullname} subfield of the
+ user's entry in the @file{responsible} file and can be accessed as
+ @code{Responsible[fullname]} (@pxref{administrative files,,Enumerated
+ field administrative files}.)
+ 
+ The change is achieved by editing the @file{dbconfig} item
+ @code{mail-format "initial-response-to-submitter"} and changing the
+ @code{fields} part of the @code{Body} from
+ 
+ @verbatim
+ fields { "Category" "Number" "Responsible"
+          "Category" "Responsible" "Synopsis"
+          "Arrival-Date" }
+ @end verbatim
+ 
+ @noindent
+ to
+ 
+ @verbatim
+ fields { "Category" "Number" "Responsible[fullname]"
+          "Category" "Responsible" "Synopsis"
+          "Arrival-Date" }
+ @end verbatim
+ 
+ @subsubheading Append-only Audit-Trail
+ 
+ The Audit-Trail of a PR is by default editable.  For some
+ applications, one might want to make the Audit-Trail append-only, so
+ it provides a full and unchangeable case history.  Also by default,
+ only certain changes, such as change of state and change of
+ responsible gets recorded in the Audit-Trail.  In some cases, it might
+ also be convenient to have a way of inserting comments directly into
+ the Audit-Trail.
+ 
+ The following procedure creates such an append-only Audit-Trail and
+ adds a PR field which makes it possible to register comments in the
+ Audit-Trail.
+ 
+ @noindent
+ First, add the keyword @code{read-only} to the Audit-Trail field
+ definition in @file{dbconfig}.
+ 
+ @noindent
+ Then, add the following field definition to @file{dbconfig}:
+ 
+ @verbatim
+ field "Add-To-Audit-Trail" {
+    description "Add a log entry to the Audit Trail"
+    multitext { default "\n" }
+    on-change  {
+         add-audit-trail
+         audit-trail-format {
+         format "**** Comment added by %s on %s ****\n %s\n\n"
+         fields { "$EditUserEmailAddr" "$CurrentDate" "$NewValue"
+         }
+         }
+     }
+     on-change {
+         set-field "Add-To-Audit-Trail" { "\n" }
+     }
+ }
+ @end verbatim
  
  @c ===============================================================