2.5 The Emacs interface to GNATS

Emacs interface to GNATS provides basic access to GNATS databases, i.e. sending, editing, and querying Problem Reports. It also defines a simple major mode for editing ‘dbconfig’ files.

This section provides an overview of using GNATS with Emacs. It does not describe the use of Emacs itself, for detailed instructions on using Emacs, see (emacs)Top section ‘Top’ in GNU Emacs. For installation instructions of the GNATS Emacs mode, see Installing the utilities.

Please note the Emacs interface was completely rewritten between GNATS 3 and GNATS 4. It now uses gnatsd, The GNATS network server – 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 GNATS mailing list, GNATS support.

2.5.1 Viewing Problem Reports

To view a particular Problem Report, use the command M-x view-pr. It asks for a Problem Report number and displays that Problem Report.

The displayed buffer is put in the view mode, (emacs)Misc File Ops section ‘Misc File Ops’ in GNU Emacs. If you decide to edit the displayed Problem Report, use the command e (gnats-view-edit-pr).

gnats-view-mode-hook

Hook run when gnats-view-mode is entered.

2.5.2 Querying Problem Reports

Querying the database is performed by the M-x query-pr command. The command prompts for the query expression, Query expressions, and displays a buffer with the list of the matching Problem Reports.

The list of the Problem Reports is displayed in the ‘summary’ query format, 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, (emacs)Misc File Ops section ‘Misc File Ops’ in GNU Emacs. You can use most of the standard view mode commands in it. Additionally, the following special commands are available:

v

RET

mouse-2

View the current Problem Report (gnats-query-view-pr), Viewing Problem Reports.

e

Edit the current Problem Report (gnats-query-edit-pr), Editing Problem Reports.

g

Update the Problem Report list (gnats-query-reread). The last performed query is executed again and the buffer is filled with the new results.

G

Perform new query (query-pr).

s

Send new Problem Report (send-pr), Submitting new Problem Reports.

D

Change the current database (gnats-change-database), Changing the database.

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.

If the value of the variable gnats-query-reverse-listing is non-nil, the listing appears in the reversed order, i.e. with the Problem Reports of the highest number first, in the buffer.

Similarly to other GNATS Emacs modes, there is a hook available for the Problem Report list.

gnats-query-mode-hook

Hook run when gnats-query-mode is entered.

2.5.3 Submitting new Problem Reports

You can submit new Problem Reports with the command M-x send-pr. The command puts you to the problem editing buffer, Editing Problem Reports. The buffer is prefilled with the initial report fields and their default values, if defined. You can use the usual Problem Report editing commands, Editing Problem Reports. When you have filled in all the fields, you can send the Problem Report by presing C-c C-c.

If you run M-x send-pr with a prefix argument, it runs the gnats-change-database command before putting you to the editing buffer, Changing the database.

You can set the following variables to get some fields pre-filled:

gnats-default-organization

Default value of the ‘Organization’ field used in new Problem Reports.

gnats-default-submitter

Default value of the ‘Submitter-Id’ field used in new Problem Reports.

2.5.4 Editing Problem Reports

To edit a particular Problem Report, use the command M-x edit-pr. It asks for a Problem Report number and puts the given Problem Report in the editing buffer. See section The Problem Report 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, Viewing Problem Reports, or the query result buffer, Querying Problem Reports.

2.5.5 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 query-pr -F output, Formatting query-pr output. Field identifiers are formatted as

>Field:

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, GNATS support.)

You can move between fields easily by pressing the TAB (gnats-next-field) or M-TAB (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, 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 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, (emacs)Font Lock section ‘Font Lock’ in GNU Emacs.

Some field values can be read-only, you cannot edit them at all.

Once you have edited the Problem Report as needed, you can send it to the server with the C-c C-c command (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.

gnats-edit-mode-hook

Hook run when gnats-edit-mode is entered.

2.5.6 Changing the database

By default, the Emacs interface connects to the default database, The databases file. If you want to connect to another database, use the command 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.

If you want to use the gnatsd command, The GNATS network server – gnatsd, directly, without connecting to a remote server or the localhost connection port, provide your local file system full path to gnatsd as the server name. Port number does not matter in this case.

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 M-x gnats-change-database command again.

2.5.7 dbconfig mode

The Emacs interface defines a simple major mode gnats-dbconfig-mode for editing ‘dbconfig’ files, The dbconfig file. It defines basic mode attributes like character syntax and font lock keywords, it does not define any special commands now.

gnats-dbconfig-mode-hook

Hook run when gnats-dbconfig-mode is entered.

2.5.8 Other commands

M-x unlock-pr

Ask for a Problem Report number and unlock that Problem Report. This function is useful if connection to a GNATS server was interrupted during an editing operation and further modifications of the Problem Report are blocked by a stealth lock.

M-x unlock-database

Unlock the whole GNATS database. This function is useful in situations similar to when unlock-pr is used.

M-x gnats-show-connection

Show the connection buffer associated with the current buffer. You can view the Emacs communication with GNATSD in it. This is useful when something strange happens during the communication with the server, e.g. when sending a Problem Report with C-c C-c from a Problem Report editing buffer.

2.5.9 Customization

All the user variables can be customized in the customization group gnats, (emacs)Easy customization section ‘Easy customization’ in GNU Emacs.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.