Changes to gnats/doc/emacs.texi

[Milan Zamazal]

Index: gnats/doc/emacs.texi
diff -c gnats/doc/emacs.texi:1.2 gnats/doc/emacs.texi:1.3
*** gnats/doc/emacs.texi:1.2    Sat Dec 15 10:21:54 2001
--- gnats/doc/emacs.texi        Wed Dec 26 16:26:10 2001
***************
*** 36,42 ****
  @ref{Installing utils}.
  
  Please note the Emacs interface was completely rewritten between
! @sc{gnats}@ 3 and @sc{gnats}@ 4.  It now uses @code{gnatsd},
  @ref{gnatsd}, exclusively for its operations and uses modern Emacs
  features like faces.  Its features are not complete though, you can
  send your suggestions and patches to the appropriate @sc{gnats}
--- 36,42 ----
  @ref{Installing utils}.
  
  Please note the Emacs interface was completely rewritten between
! @address@hidden 3} and @address@hidden 4}.  It now uses @code{gnatsd},
  @ref{gnatsd}, exclusively for its operations and uses modern Emacs
  features like faces.  Its features are not complete though, you can
  send your suggestions and patches to the appropriate @sc{gnats}
***************
*** 57,71 ****
  @node Emacs viewing
  @subsection Viewing Problem Reports
  
! @cindex @kbd{view-pr}
  To view a particular Problem Report, use the command @kbd{M-x
  view-pr}.  It asks for a Problem Report number and displays that
  Problem Report.
  
! @cindex @kbd{gnats-view-edit-pr}
  The displayed buffer is put in the view mode, @ref{Misc File
  Ops,,,emacs,GNU Emacs}.  If you decide to edit the displayed Problem
! Report, use the command @kbd{e} (@kbd{gnats-view-edit-pr}).
  
  @table @code
  @cindex @code{gnats-view-mode-hook}
--- 57,71 ----
  @node Emacs viewing
  @subsection Viewing Problem Reports
  
! @cindex @code{view-pr}
  To view a particular Problem Report, use the command @kbd{M-x
  view-pr}.  It asks for a Problem Report number and displays that
  Problem Report.
  
! @cindex @code{gnats-view-edit-pr}
  The displayed buffer is put in the view mode, @ref{Misc File
  Ops,,,emacs,GNU Emacs}.  If you decide to edit the displayed Problem
! Report, use the command @kbd{e} (@code{gnats-view-edit-pr}).
  
  @table @code
  @cindex @code{gnats-view-mode-hook}
***************
*** 77,89 ****
  @node Emacs querying
  @subsection Querying Problem Reports
  
! @c TODO
  
  
  @node Emacs submitting
  @subsection Submitting new Problem Reports
  
! @cindex @kbd{send-pr}
  You can submit new Problem Reports with the command @kbd{M-x send-pr}.
  The command puts you to the problem editing buffer, @ref{Emacs
  editing}.  The buffer is prefilled with the initial report fields and
--- 77,145 ----
  @node Emacs querying
  @subsection Querying Problem Reports
  
! @cindex @code{query-pr}
! Querying the database is performed by the @kbd{M-x query-pr} command.
! The command prompts for the query expression, @ref{Query expressions},
! and displays a buffer with the list of the matching Problem Reports.
! 
! The list of the Problem Reports is displayed in the @samp{summary}
! query format, @ref{Formatting query-pr output}.  Currently, the
! display format cannot be changed and it must output each Problem
! Report's number in the first column.
! 
! The Problem Report list buffer is put in the view mode, @ref{Misc File
! Ops,,,emacs,GNU Emacs}.  You can use most of the standard view mode
! commands in it.  Additionally, the following special commands are
! available:
! 
! @table @kbd
! @cindex @code{gnats-query-view-pr}
! @item v
! @itemx RET
! @itemx mouse-2
! View the current Problem Report (@code{gnats-query-view-pr}),
! @ref{Emacs viewing}.
! 
! @cindex @code{gnats-query-edit-pr}
! @item e
! Edit the current Problem Report (@code{gnats-query-edit-pr}),
! @ref{Emacs editing}.
! 
! @cindex @code{gnats-query-reread}
! @item g
! Update the Problem Report list (@code{gnats-query-reread}).  The last
! performed query is executed again and the buffer is filled with the
! new results.
! 
! @cindex @code{send-pr}
! @item s
! Send new Problem Report (@code{send-pr}), @ref{Emacs submitting}.
! 
! @cindex @code{gnats-change-database}
! @item D
! Change the current database (@code{gnats-change-database}), @ref{Emacs
! and databases}.
! 
! @cindex @code{bury-buffer}
! @item q
! Bury buffer, the buffer is put at the end of the list of all buffers.
! This is useful for quick escape of the buffer, without killing it.
! @end table
! 
! Similarly to other @sc{gnats} Emacs modes, there is a hook available
! for the Problem Report list.
! 
! @table @code
! @cindex @code{gnats-query-mode-hook}
! @item gnats-query-mode-hook
! Hook run when @code{gnats-query-mode} is entered.
! @end table
  
  
  @node Emacs submitting
  @subsection Submitting new Problem Reports
  
! @cindex @code{send-pr}
  You can submit new Problem Reports with the command @kbd{M-x send-pr}.
  The command puts you to the problem editing buffer, @ref{Emacs
  editing}.  The buffer is prefilled with the initial report fields and
***************
*** 100,106 ****
  @node Emacs editing
  @subsection Editing Problem Reports
  
! @cindex @kbd{edit-pr}
  To edit a particular Problem Report, use the command @kbd{M-x
  edit-pr}.  It asks for a Problem Report number and puts the given
  Problem Report in the editing buffer.  @xref{Emacs editing buffer},
--- 156,162 ----
  @node Emacs editing
  @subsection Editing Problem Reports
  
! @cindex @code{edit-pr}
  To edit a particular Problem Report, use the command @kbd{M-x
  edit-pr}.  It asks for a Problem Report number and puts the given
  Problem Report in the editing buffer.  @xref{Emacs editing buffer},
***************
*** 111,116 ****
--- 167,231 ----
  from within the viewing buffer, @ref{Emacs viewing}, or the query
  result buffer, @ref{Emacs querying}.
  
+ 
+ @node Emacs editing buffer
+ @subsection The Problem Report editing buffer
+ 
+ When you invoke a Problem Report editing command, the Problem Report
+ is put into a special editing buffer.  The Problem Report is formatted
+ similarly to the @code{query-pr -F} output, @ref{Formatting query-pr
+ output}.  Field identifiers are formatted as
+ 
+ @example
+ >Field:
+ @end example
+ 
+ with the text of the field following the identifier on the same line
+ for single-line fields or starting on the next line for multi-line
+ fields.
+ 
+ The Problem Report editing mode tries to prevent you from violating
+ the Problem Report format and the constraints put on the possible
+ field values.  Generally, you can use usual editing commands, some of
+ them have a slightly modified behavior though.  (If you encounter a
+ very strange behavior somewhere, please report it as a bug,
+ @ref{Support}.)
+ 
+ @cindex @code{gnats-next-field}
+ @cindex @code{gnats-previous-field}
+ You can move between fields easily by pressing the @kbd{TAB}
+ (@code{gnats-next-field}) or @kbd{M-TAB}
+ (@code{gnats-previous-field}) keys.
+ 
+ The field tags are read-only and you cannot edit them nor delete them.
+ If you want to ``remove'' a field, just make its value empty.
+ 
+ Editing a field value depends on the type of the edited field,
+ @ref{Field datatypes}.  For text fields, you can edit the value
+ directly, assuming you preserve the rule about single-line and
+ multi-line values mentioned above.
+ 
+ For enumerated fields, you cannot edit the value directly.  You can
+ choose it from the list of the allowed values, either from the menu
+ popped up by pressing the middle mouse button or from within
+ minibuffer by pressing any key on the field's value.  If the pressed
+ key matches any of the allowed field values, that value is put as the
+ default value after the minibuffer prompt.  You can also cycle through
+ the allowed field values directly in the editing buffer using the
+ @code{SPACE} key.  Enumerated field values are marked by a special
+ face to not confuse you; you must have enabled font lock mode to
+ benefit from this feature, @ref{Font Lock,,,emacs,GNU Emacs}.
+ 
+ Some field values can be read-only, you cannot edit them at all.
+ 
+ @cindex @code{gnats-apply-or-submit}
+ Once you have edited the Problem Report as needed, you can send it to
+ the server with the @kbd{C-c C-c} command
+ (@code{gnats-apply-or-submit}).  Successful submission is reported by
+ a message and the buffer modification flag in mode line is cleared.
+ Then you can either kill the buffer or continue with further
+ modifications.
+ 
  @table @code
  @cindex @code{gnats-edit-mode-hook}
  @item gnats-edit-mode-hook
***************
*** 118,133 ****
  @end table
  
  
- @node Emacs editing buffer
- @subsection The Problem Report editing buffer
- 
- @c TODO
- 
- 
  @node Emacs and databases
  @subsection Changing the database
  
! @cindex @kbd{gnats-change-database}
  By default, the Emacs interface connects to the default database,
  @ref{databases file}.  If you want to connect to another database, use
  the command @kbd{M-x gnats-change-database}.  It will ask you for the
--- 233,242 ----
  @end table
  
  
  @node Emacs and databases
  @subsection Changing the database
  
! @cindex @code{gnats-change-database}
  By default, the Emacs interface connects to the default database,
  @ref{databases file}.  If you want to connect to another database, use
  the command @kbd{M-x gnats-change-database}.  It will ask you for the
***************
*** 171,182 ****
  @subsection Other commands
  
  @table @kbd
! @cindex @kbd{unlock-pr}
  @item M-x unlock-pr
  Ask for a Problem Report number and unlock that Problem Report.  This
! function is useful if connection to a @sc{gnats} server crashed during
! an editing operation and further modifications of the Problem Report
! are blocked by a stealth lock.
  @end table
  
  
--- 280,291 ----
  @subsection Other commands
  
  @table @kbd
! @cindex @code{unlock-pr}
  @item M-x unlock-pr
  Ask for a Problem Report number and unlock that Problem Report.  This
! function is useful if connection to a @sc{gnats} server was
! interrupted during an editing operation and further modifications of
! the Problem Report are blocked by a stealth lock.
  @end table