Changes to gnats/doc/emacs.texi

[Milan Zamazal]

Index: gnats/doc/emacs.texi
diff -c gnats/doc/emacs.texi:1.1 gnats/doc/emacs.texi:1.2
*** gnats/doc/emacs.texi:1.1    Tue Dec 11 16:36:11 2001
--- gnats/doc/emacs.texi        Sat Dec 15 10:21:54 2001
***************
*** 1,5 ****
  @ignore
! @c Copyright (C) 2001 Milan Zamazal
  
  Permission is granted to make and distribute verbatim copies of
  this manual provided the copyright notice and this permission notice
--- 1,5 ----
  @ignore
! Copyright (C) 2001 Milan Zamazal
  
  Permission is granted to make and distribute verbatim copies of
  this manual provided the copyright notice and this permission notice
***************
*** 19,29 ****
  into another language, under the above conditions for modified versions.
  @end ignore
  
  @node Emacs
  @section The Emacs interface to @sc{gnats}
  
- TODO: To be written.
  
! For detailed instructions on using Emacs, see
! @ref{Introduction,,,emacs,GNU Emacs}.
  
--- 19,187 ----
  into another language, under the above conditions for modified versions.
  @end ignore
  
+ @c ***************************************************************************
+ 
  @node Emacs
  @section The Emacs interface to @sc{gnats}
+ @cindex Emacs
+ 
+ Emacs interface to @sc{gnats} provides basic access to @sc{gnats}
+ databases, i.e. sending, editing, and querying Problem Reports.  It
+ also defines a simple major mode for editing @file{dbconfig} files.
+ 
+ This section provides an overview of using @sc{gnats} with Emacs.  It
+ does not describe the use of Emacs itself, for detailed instructions
+ on using Emacs, see @ref{Top,,,emacs,GNU Emacs}.  For
+ installation instructions of the @sc{gnats} Emacs mode, see
+ @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}
+ mailing list, @ref{Support}.
+ 
+ @menu
+ * Emacs viewing::               Viewing PRs by their number.
+ * Emacs querying::              Querying the database.
+ * Emacs submitting::            Submitting new PRs.
+ * Emacs editing::               Editing PRs.
+ * Emacs editing buffer::        The editing buffer.
+ * Emacs and databases::         Changing the working database.
+ * dbconfig mode::               Major mode for dbconfig files.
+ * Other Emacs commands::        Miscellaneous commands.
+ * Emacs customization::         Customizing the Emacs interface.
+ @end menu
+ 
+ @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}
+ @item gnats-view-mode-hook
+ Hook run when @code{gnats-view-mode} is entered.
+ @end table
+ 
+ 
+ @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
+ their default values, if defined.  You can use the usual Problem
+ Report editing commands, @ref{Emacs editing}.  When you have filled in
+ all the fields, you can send the Problem Report by presing @kbd{C-c
+ C-c}.
+ 
+ If you run @kbd{M-x send-pr} with a preifx argument, it runs
+ @code{gnats-change-database} before putting you to the editing buffer,
+ @ref{Emacs and databases}.
+ 
+ 
+ @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},
+ for information how to edit the Problem Report in the buffer and how
+ to submit your changes.
+ 
+ Note you can also start editing of a selected Problem Report directly
+ from within the viewing buffer, @ref{Emacs viewing}, or the query
+ result buffer, @ref{Emacs querying}.
+ 
+ @table @code
+ @cindex @code{gnats-edit-mode-hook}
+ @item gnats-edit-mode-hook
+ Hook run when @code{gnats-edit-mode} is entered.
+ @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
+ database name to use, server and port it can be accessed on, and your
+ login name.
+ 
+ @cindex gnatsd, Emacs
+ If you want to use the @command{gnatsd} command, @ref{gnatsd},
+ directly, without connecting to a remote server or the localhost
+ connection port, provide your local file system full path to
+ @command{gnatsd} as the server name.  Port number does not matter in
+ this case.
+ 
+ @cindex password, Emacs
+ If the database requires a password to allow you the access to it, you
+ are prompted for the password the first time you connect to the
+ database.  If you provide an invalid password, you cannot connect to
+ the database anymore and you have to run the @kbd{M-x
+ gnats-change-database} command again.
+ 
+ 
+ @node dbconfig mode
+ @subsection dbconfig mode
+ 
+ @cindex dbconfig mode
+ @cindex @code{gnats-dbconfig-mode}
+ The Emacs interface defines a simple major mode
+ @code{gnats-dbconfig-mode} for editing @file{dbconfig} files,
+ @ref{dbconfig file}.  It defines basic mode attributes like character
+ syntax and font lock keywords, it does not define any special commands
+ now.
+ 
+ @table @code
+ @cindex @code{gnats-dbconfig-mode-hook}
+ @item gnats-dbconfig-mode-hook
+ Hook run when @code{gnats-dbconfig-mode} is entered.
+ @end table
+ 
+ 
+ @node Other Emacs commands
+ @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
  
  
! @node Emacs customization
! @subsection Customization
  
+ All the user variables can be customized in the customization group
+ @code{gnats}, @ref{Easy customization,,,emacs,GNU Emacs}.