Changes to gnats/doc/p-admin.texi

[Yngve Svendsen]

Index: gnats/doc/p-admin.texi
diff -c gnats/doc/p-admin.texi:1.26 gnats/doc/p-admin.texi:1.27
*** gnats/doc/p-admin.texi:1.26 Sun Jul 28 15:22:27 2002
--- gnats/doc/p-admin.texi      Mon Oct 14 18:11:58 2002
***************
*** 1316,1348 ****
  @subsection The @code{states} file
  @cindex @code{states} file
  
! This file lists the possible states for Problem Reports.  Each line
! consists of a state, followed optionally by colon and a one-line
! description of what the state means.  Lines beginning with @samp{#} will
! be ignored.
  
  @smallexample
! @var{state}:@var{optional descriptive text}
  @end smallexample
  
! State names can contain any alphanumeric character, @samp{-} (hyphen), 
@samp{_}
! (underscore), or @samp{.} (period), but no other characters.  The state name
! ends with a newline, or else with a colon followed by optional
! descriptive text.  The descriptive text, if present, can contain any
! character except newline, which marks the end of the description.  Empty
! or all-whitespace descriptions are allowed. This is not recommended,
! however, since although @sc{gnats} doesn't use this field, external
! tools might.
  
  The first state listed will be the state automatically assigned to
! Problem Reports when they arrive; by default this is named "open".  The
! last state listed is the end state for Problem Reports --- one should
! usually assume that a PR in this state is not being actively worked on;
! by default this state is named "closed".
! 
! It is probably best to leave "open" as the first state and "closed" as
! the last, otherwise some external tools looking for those two states by
! name may be fooled.
  
  @node addresses file
  @subsection The @code{addresses} file
--- 1316,1381 ----
  @subsection The @code{states} file
  @cindex @code{states} file
  
! This file lists the possible states for Problem Reports.  Each entry
! has up to three fields, separated by colons.  Lines beginning with
! @samp{#} will be ignored.
  
  @smallexample
! @var{state}:@var{type}:@var{description}
  @end smallexample
  
! @noindent
! @table @var
! @item state
! The name of the state.  It may contain alphanumerics as well as
! @samp{-} (hyphen), @samp{_} (underscore), or @samp{.} (period), but no
! other characters.
! 
! @item type
! This is the type of the state.  This field is optional and it may
! contain alphanumerics as well as @samp{-} (hyphen), @samp{_}
! (underscore), or @samp{.} (period), but no other characters.
! 
! The concept of the type of a state recognizes that there may for
! instance be several possible states for a Problem Report which
! effectively means that the PR is closed and that there may be certain
! actions that need to be taken when a PR reaches a ``closed state''.
! The problem may have been resolved, it might have been decided that
! the problem is unsolvable or simply that it won't be solved.  Some
! organizations may for instance wish to consider the ``suspended''
! state as a state of type ``closed''.
! 
! Currently, the only defined state types are ``open'' and ``closed'',
! the ``open'' type isn't currently used for anything while the
! ``closed'' type is only used to control the Closed-Date field of PRs.
! Changing the state of a PR to any state of type ``closed'' will set
! the Closed-Date field with a time stamp and changing the state of a PR
! from one ``closed'' state to another will leave the Closed-Date field
! as it was.  Changing the state of a PR from any state of type
! ``closed'' to a non-closed state will clear the Closed-Date field.
! 
! The @code{--skip-closed} option of @code{query-pr} refers to all
! states of type ``closed'', not to a specific state name of ``closed''.
! 
! @item description
! This is is an optional one-line description of what the state means.
! Any character is okay in the description; a newline ends it.
! @sc{gnats} itself does not currently use the description for anything,
! but certain external tools (such as TkGnats and Gnatsweb) look for it,
! so it's a good idea to include one for every state.
! @end table
  
  The first state listed will be the state automatically assigned to
! Problem Reports when they arrive; by default this is named ``open''.
! The last state listed is the end state for Problem Reports --- one
! should usually assume that a PR in this state is not being actively
! worked on; by default this state is named ``closed''.  Even if a
! different name has been chosen for this state, @sc{gnats} will force
! this state to be of type ``closed''.
! 
! It is recommended that you keep the default names of ``open'' and
! ``closed'' for the first and last states respectively, since there may
! be external tools that depend on these names.
  
  @node addresses file
  @subsection The @code{addresses} file
***************
*** 1366,1372 ****
  A valid submitter ID
  
  @item @var{address-fragment}
! Part of all of the e-mail address to be matched
  @end table
  
  Here is an example of an @code{addresses} file:
--- 1399,1405 ----
  A valid submitter ID
  
  @item @var{address-fragment}
! Part of, or all of the e-mail address to be matched
  @end table
  
  Here is an example of an @code{addresses} file: