Reporting Problems With send-pr is a separate manual which
contains the same text as the chapter “Reporting problems with
send-pr
” in this manual, so that support sites who use
GNATS
may copy and distribute the send-pr
manual
when they distribute send-pr
(see section Configuring send-pr
for the outside world).
Throughout this manual, the personal pronouns you and your
refer to the GNATS
installer/administrator at a given site.
Copyright © 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.
[ < ] | [ > ] | [Contents] | [Index] | [ ? ] |
This manual documents a suite of utilities called GNATS
,
the GNU Problem Report Management System. GNATS
is a
bug-tracking tool designed for use at a central support site. Software
users who experience problems use electronic mail to communicate these
problems to the maintainers of that software; GNATS
partially automates the tracking of these problem reports (PRs)
by:
GNATS
offers many of the same features offered by more generic
databases. The database itself is simply an ordered repository for
problem reports; each PR receives a unique, incremental PR number
which identifies it throughout its lifetime.
Many of the primary functions available with GNATS
are
accessible from within GNU Emacs. See section Invoking the GNATS
tools. Also see
for information about submitting problem reports from within Emacs.
Problem reports go through several defined states in their lifetimes. The database considers the initial state of every PR to be open; this means the PR has been filed and the person or group responsible for it has been notified of the suspected problem. Once the problem has been examined, its state changes to analyzed, and work toward a solution begins. When a solution has been found and tested at the support site, that solution is sent to the party who reported the problem (the submitter). The PR goes into feedback state until the solution is confirmed by the submitter, at which point the state changes to closed. In some cases, it may be necessary to suspend work on a bug; in this case, its state changes to suspended rather than closed. For a detailed explanation of what each state means, see States of Problem Reports.
Please report all bugs to one of these addresses:
bug-gnats@prep.ai.mit.edu {ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gnats
This manual documents the 3.01 release of GNATS
.
1 Introducing GNATS | Introducing GNATS | |
2 Configuring and installing GNATS | Configuring and installing GNATS | |
3 Invoking the GNATS tools | Invoking the GNATS tools | |
• send-pr | Reporting problems with ‘send-pr’ | |
Index |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
Any support site which supports more than one product or category of
products realizes that a large amount of data flows back and forth in
the form of problem reports and communication between software
maintainers and software users. GNATS
addresses the
problem of organizing this communication by defining a database made up
entirely of messages filed automatically by electronic mail.
GNATS
is a tool for software maintainers. It consists
of ten different utilities which, when used in concert, formulate and
administer a database of problem reports grouped by site-defined
categories. It was designed for use within a support organization to
keep track of problems with software (hence the term Problem
Report). Essentially, GNATS
acts as an active archive
for field-separated textual data submitted through electronic mail.
1.1 The database paradigm | ||
1.2 Data Flow | Data Flow through the system | |
1.3 Flowchart of GNATS activities | Flowchart of GNATS activities | |
1.4 States of Problem Reports | ||
1.5 GNATS data fields | GNATS data fields |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is in the best interests of any software maintainer to make it easy
for users of her or his software to report problems they might have with
that software. It is also in her or his best interest to keep track of
reported problems in as organized a fashion as possible.
GNATS
makes this easy by automatically filing incoming
bug reports into proper places, and making them accessible to queries
and easily editable. It is a database specialized for a specific task.
GNATS
was designed for use at a support site that
handles a high level of problem-related traffic though electronic mail.
It maintains PRs in the form of text files with defined fields.
Each bug report resides in a separate file within a main repository;
editing access to the database is regulated to maintain consistency.
The fields GNATS
recognizes are discussed in
GNATS
data fields. We provide
edit-pr
with this distribution as a tool for software maintainers
to use when editing problem reports in the database. Maintainers can
use query-pr
for making inquiries about certain PRs or groups of
PRs with a very fast search mechanism based on an index which is kept
constantly up to date.
At the support site, a GNATS
administrator is
charged with the duty of maintaining GNATS
. These
duties are discussed in detail in Managing GNATS
, and generally include pruning log files, setting
up new categories for GNATS
to handle, and handling bug
reports that arrive in a format GNATS
cannot understand.
Responsibility for a given problem report is determined by the category
of the problem. Optionally, an automated reminder can be sent to the
responsible person if a problem report is neglected for a requisite time
period. See section Configuring and installing GNATS
, and Data Flow.
The tool send-pr
is provided with this distribution so that both
submitters may more easily submit bug reports that will have fewer
problems when being filed into the database. send-pr
is both a
shell script and a GNU Emacs mode; both implementations provide a
template for submitters to complete. In most cases, send-pr
will
be able to “figure out” the values of several fields, thus at least
partially automating the bug-reporting process. Of course, any editor
and mailer may be used to submit problem reports to the database.
However, the default values GNATS
assigns to partially
formatted PRs are not always correct for each PR. send-pr
is
easy to use; it brings up a template which prompts a user for certain
useful kinds of information, which is a step forward in the process of
knowing what kind of data to provide. (The send-pr
manual also
provides a “Helpful Hints” chapter to help people to decide what kinds
of information to provide in reporting bugs;
We also provide a utility called mkdist
, which constructs a
complete distribution of send-pr
, including documentation,
customized to your site’s combination of categories. See section Configuring send-pr
for the outside world.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Once you configure GNATS
to reflect the categories of
problem reports you wish to accept and the responsible parties, you can
start accepting problem reports from both internal and external sources.
For a flowchart describing the activity of GNATS
, see
Flowchart of GNATS
activities.
All incoming problem reports should be directed to a single mail alias
which you determine when configuring GNATS
for your
site. This alias pipes incoming reports into a program called
queue-pr
, which places them in the subdirectory
‘gnats-queue’ under the root GNATS
directory. The program queue-pr
is also run periodically via
cron
with a different option; this iteration of queue-pr
feeds the queued PRs in ‘gnats-queue’ to the program
file-pr
, which assigns each bug report an incremental identifying
number and places it in the database according to its category, updating
the index as well. file-pr
also forwards a copy of the bug
report to the person responsible for solving the problem, and optionally
sends an acknowledgment to the submitter of the problem report. The
GNU Problem Report Tracking System does not yet have the ability to
decipher random text, so any problem reports which arrive in a format
GNATS
does not recognize are kept in a separate
directory pending investigation by the GNATS
administrator. This directory is called, creatively enough,
‘pending’.
Depending on your configuration, gnats
may invoke
at-pr
, which, if a bug is listed with ‘>Priority: high’ or
‘Severity: critical’, sends a reminder to the person responsible
for the bug report if it isn’t analyzed within a certain requisite time
period (relative to the submitter of the bug; see section The submitters
file). at-pr
creates a queued job using
at
which, after the allotted time (in business hours, 8am
to 5pm Monday through Friday) is past, checks the PR to see if its state
has changed from ‘open’. If this hasn’t occurred, at-pr
sends mail to the responsible person and to gnats-admin
with the following message:
To: originator responsible gnats-admin Subject: PR id-number not analyzed in #hours hours PR id-number was not analyzed within the acknowledgment period of #hours business hours. The pertinent information is: Submitter-Id: submitter Originator: full name of the submitter Synopsis: synopsis Person responsible for the PR: responsible -- The GNU Problem Report Tracking System (GNATS)
At this point, the bug report has been filed, the responsible parties
have been notified, and an acknowledgment has been sent to the submitter
of the problem report. The state of the PR is ‘open’, and it is up
to the responsible person to contact the submitter for any more
information needed to analyze the problem. Any further mail should be
carbon-copied to the GNATS
mailing address as well, with
the category and id-number in the Subject line of the message:
To: submitter@submitter-site From: responsible (or anyone wishing to reply to this message) Subject: Re: PR category/id-number: original message subject Cc: GNATS address message…
This message is automatically appended to the Problem Report in the
‘>Audit-Trail:’. Messages are recorded there in the order
received. If the the PR in question is being edited when a reply comes
in, that message is placed in the queue to be appended to the PR
whenever queue-pr
is run again.
In order to maintain consistency, any large code samples or test cases
should reside in a separate directory. One strategy is to create a
directory called ‘test-cases’ or something similar in the home
directory of GNATS
, with subdirectories in each named
‘id-number-d’, storing all extra information according to the
PR identification number with which the information is related. Be sure
to note in the PR that the other information exists, and where. For
example:
gnats% ls -F ./test-cases 128-d/ 432-d/ 872-d/ 1102-d/ 322-d/ 778-d/ 995-d/
where each of these directories contains test cases which exhibit the problem reported.
Software maintainers use the program edit-pr
to alter fields in
certain PRs, and the program query-pr
to obtain information from
the database. query-pr --summary may also be used to generate a
one-line summary of each PR in the search, which can then be used with
awk
or sed
to create reports on the database:
query-pr --summary --state=open > Open-bugs query-pr --summary --state=analyzed > Analyzed-bugs cat Open-bugs Analyzed-bugs | awk -f ./bugsort.awk > current-bugs
GNATS
sends notifications of any changes in the state or
responsibility fields to the responsible party and to the submitter of
the bug report.
Maintainers now begin work on the bug, at first analyzing the problem (and thus changing the state of the PR to analyzed) and then seeking a solution for it. Once a PR is analyzed, work begins toward a solution. When the solution is found, the maintainer changes the state to feedback and provides the solution to the submitter of the bug report so that it may be tested; when the submitter confirms that the solution works, the state may be changed to closed. If for some reason the progress towards a solution must be stopped, the state can be changed to suspended. See section States of Problem Reports.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
activities[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Each PR goes through a defined series of states between origination and closure, and is considered active until it has been resolved or otherwise explicitly closed. The originator of a PR receives notification automatically of any state changes that occur.
The initial state of a Problem Report. This means the PR has been filed and the responsible person(s) notified.
The responsible person has analyzed the bug. The analysis should contain a preliminary evaluation of the problem and an estimate of the amount of time and resources necessary to solve the problem. It should also suggest possible workarounds.
This state indicates that the problem has been solved, and the originator has been given a patch or other fix. The PR remains in this state until the originator acknowledge that the solution works.
A Problem Report is closed (“the bug stops here”) only when any changes to the software in question have been documented, integrated and tested, and the submitter has confirmed the solution.
Work on the problem has been postponed. This happens if a timely solution is not possible or is not cost-effective at the present time. The PR continues to exist, though a solution is not being actively sought. If the problem cannot be solved at all, it should be closed rather than suspended.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
data fields1.5.1 Mail Header fields | ||
1.5.2 Problem Report fields |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A Problem Report may contain any mail header field described in the
Internet standard RFC-822. However, only the fields which identify the
sender and the subject are required for send-pr
to function
properly:
To:
The preconfigured mail alias for the support site where the PR is to be
sent, automatically supplied by send-pr
.
Subject:
A terse description of the problem.
From:
Usually supplied automatically by the originator’s mailer; should contain the originator’s electronic mail address.
Reply-To:
A return address to which electronic replies can be sent; in most
cases, probably the same address as the From:
field.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Problem Report fields begin with a keyword enclosed with ‘>’ and ‘:’, and belong to one of three data types:
One of a specific set of values. The value must be on the same line as
the keyword. For each ENUMERATED keyword, the possible choices are
listed in the send-pr
template as a comment.
One single line of text which must begin and end on the same line as the keyword.
Text of any length may occur in this field. TEXT may span multiple lines and may also include blank lines. A TEXT field ends only when another keyword appears.
The following fields are present whenever a PR is submitted via the
program send-pr
. GNATS
adds additional fields
when the PR arrives at the support site; explanations of these follow
this list.
>Submitter-Id:
(ENUMERATED) A unique identification code assigned by the support
site. It is used to identify all Problem Reports coming from a
particular site. (Submitters without a value for this field can invoke
send-pr
with the ‘--request-id’ option to apply for one from
the support organization. Problem Reports from those not affiliated
with the support organization should use the default value of ‘net’
for this field.)
>Originator:
(STRING) Originator’s real name. The default is the value of the
originator’s environment variable NAME
.
>Organization:
(TEXT) The originator’s organization. The default value is the
contents of the originator’s environment variable ORGANIZATION
,
or the contents of the file ‘.signature’ if ORGANIZATION
isn’t set.
>Confidential:
(ENUMERATED) Use of this field depends on the originator’s relationship with the support organization; contractual agreements often have provisions for preserving confidentiality. Conversely, a lack of a contract often means that any data provided will not be considered confidential. Submitters should be advised to contact the support organization directly if this is an issue.
If the originator’s relationship to the support organization provides for confidentiality, then if the value of this field is ‘yes’ the support organization treats the PR as confidential; any code samples you provide are not made publicly available (e.g., in regression test suites). The default value is ‘yes’.
>Synopsis:
(STRING) One-line summary of the problem.
>Severity:
(ENUMERATED) The severity of the problem. Accepted values include:
critical
The product, component or concept is completely non-operational or some essential functionality is missing. No workaround is known.
serious
The product, component or concept is not working properly or significant functionality is missing. Problems that would otherwise be considered ‘critical’ are rated ‘serious’ when a workaround is known.
non-critical
The product, component or concept is working in general, but lacks features, has irritating behaviour, does something wrong, or doesn’t match its documentation.
The default value is ‘serious’.
>Priority:
(ENUMERATED) How soon the originator requires a solution. Accepted values include:
high
A solution is needed as soon as possible.
medium
The problem should be solved in the next release of the software.
low
The problem should be solved in a future release.
The default value is ‘medium’.
>Category:
(ENUMERATED) The name of the product, component or concept where
the problem lies. The support organization provides a list of valid
categories; use ‘send-pr -L’ to see the listing provided with the
send-pr
distribution. For an example list, see
>Class:
(ENUMERATED) The class of a problem can be one of the following:
support
A support problem or question.
sw-bug
A software bug.
doc-bug
A bug in the documentation.
change-request
A request for a change in behavior, etc.
mistaken
No bug, user error or misunderstanding. This value is valid only at the support site.
duplicate (pr-number)
Duplicate PR. pr-number should be the number of the original PR.
The default is ‘sw-bug’.
>Release:
(STRING) Release or version number of the product, component or concept.
>Environment:
(TEXT) Description of the environment where the problem occured: machine architecture, operating system, host and target types, libraries, pathnames, etc.
>Description:
(TEXT) Precise description of the problem, including all
preconditions, inputs, outputs, conditions after the problem, and
symptoms. Any additional important information should be included. In
the send-pr
manual, users are instructed to include all the
details that would be necessary for someone else to recreate the
problems they report, however obvious. Sometimes seemingly arbitrary or
obvious information can point the way toward a solution. For the types
of information to include, see
>How-To-Repeat:
(TEXT) Example code, input, or activities to reproduce the problem. The support organization uses your example code both to reproduce the problem and to test whether the problem is fixed. Again, see for helpful hints.
The following fields are added to the PR when the support site receives it:
>Responsible:
The person responsible for this category, as noted in the ‘categories’ file.
>Arrival-Date:
The time that this PR was received by GNATS
.
>Audit-Trail:
Tracks changes in ‘>State:’ and ‘>Responsible:’ with the sub-fields:
State-Changed-<From>-<To>: <oldstate>-<newstate>
Responsible-Changed-<From>-<To>: <oldresp>-<newresp>
ENUMERATED field containing the values the state or responsible was changed from and to.
State-Changed-By: name
Responsible-Changed-By: name
ENUMERATED field containing the name of the maintainer who affected the change.
State-Changed-When: date and time
Responsible-Changed-When: date and time
STRING containing the time the change was made.
State-Changed-Why: reason…
Responsible-Changed-Why: reason…
TEXT field with the reason for the change.
Also contains any mail messages received by GNATS
related to this PR, in the order received.
>Unformatted:
Any information that does not fit into any of the above fields.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
There are several steps you need to go through to fully configure and
install GNATS
on your system. You will need root
access in order to make a new account for gnats
, to
allow this “user” access to cron
and at
, and to install
the GNATS
utilities. You may need root
access on
some systems in order to set mail aliases in place.
GNATS
tools are in
the subdirectory ‘gnats-3.01/gnats/*’.
Lists of files included in the distribution are in each directory in the file ‘MANIFEST’.
GNATS_ROOT
The directory where the database, all administration files, etc., resides. After installing, any changes should be made in this directory. From now on, we will refer to this directory as GNATS_ROOT.
GNATS_ADDR
The address to which software users should submit bugs. For instance,
if you wish all problem reports to be sent to your site at
‘bug-reports@your-organization’, this full address
should be the value of GNATS_ADDR
.
GNATS_SITE
A one-word name tag for your site, to be used as an alias for anyone who
submits bug reports. You should also include this name in the
‘submitters’ file so GNATS
can recognize bug reports
originating from inside your organization (see step 12). This value
also becomes the name of a list of categories your organization
supports, which is kept up to date locally when you run the program
mkcat
(see section The categories
file) and is
created for outside users when you use the utility mkdist
(see section Configuring send-pr
for the outside world).
DEFAULT_RELEASE
Used by send-pr
as a default value for the ‘>Release:’
field. Use the name or release number of your most recent release, or
just leave it blank to set no default.
DEFAULT_ORGANIZATION
Used by your local send-pr
as a default value for the
‘>Organization:’ field. Supply the name of your organization here.
This is the only ‘Makefile’ you should edit in this distribution.
GNATS
. See section The config.h
file.
configure
at the top level.configure
from the top level of the source directory,
‘gnats-3.01’, with the command
./configure hosttype
(where hosttype is your host type) and the “Right Thing” will
happen: GNATS
will be configured in the same directory
you unpacked it in; when built, it will be able to run on the machine
you’re building it on; and when installed, files which should be public
will be installed in ‘/usr/local’. You may omit hosttype on
most platforms; configure
has magical ways of finding out what
kind of machine you’re on.
You may wish to build GNATS
in a different directory
from the source directory, or install the user utilities like
query-pr
in a directory different from ‘/usr/local’. For
instructions on this, see Configuring GNATS
on your system.
root
privileges.
The following steps may require root
privileges.
|
|
|
|
|
gnats
, the new account you created.
GNATS_ROOT/gnats-adm/categories
,
GNATS_ROOT/gnats-adm/submitters
, and
GNATS_ROOT/gnats-adm/responsible
.
to reflect your schema for collecting data. See section Files used for GNATS
administration, for detailed discussions
of the formats of these files. For more discussion on data collection
schematics, see Introducing GNATS
.
mkcat
sets up the subdirectories of GNATS_ROOT
which will contain submitted Problem Reports. Each subdirectory is
named for the category its bugs will belong to; for instance, all bugs
submitted with a category of carbuerator will be filed in the
directory ‘GNATS_ROOT/carbuerator’.
mkcat
creates these directories according to the data you placed
in the ‘categories’ file (see section The categories
file); it also updates the local list of supported
categories used by send-pr
.
Always run mkcat
whenever you need to add a new category.
See section Managing GNATS
.
crontab
entry for the user gnats
to
periodically run the command
GNATS_ROOT/gnats-bin/queue-pr -r
The ‘-r’ option causes queue-pr
to feed all the incoming
bugs from the directory
‘GNATS_ROOT/gnats-queue’ into the
program file-pr
, which assigns each new bug an individual serial
number, notifies responsible parties of the existence of this bug,
updates the index, files the bug in the correct subdirectory, etc.
See section Introducing GNATS
.
gnats
account.
GNATS
is now “live” on your system. The program
send-pr
(invoked with M-x send-pr from within Emacs)
allows your local users to easily submit Problem Reports. You should
pre-configure and distribute copies of send-pr
to all parties you
wish to receive bug reports from using the program mkdist
; see
Configuring send-pr
for the outside world. See also
2.1 Configuring GNATS on your system | Configuring GNATS on your system | |
2.2 Using GNATS over a network | Using GNATS over a network | |
2.3 The config.h file | The ‘config.h’ file | |
2.4 Files used for GNATS administration | Files used for GNATS administration |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
on your systemSee What configure
does in Cygnus configure, for detailed information about configure
.
2.1.1 Changing the installation location | ||
2.1.2 Changing the build directory | ||
2.1.3 Other flags to configure | Other flags to ‘configure’ |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
‘/usr/local’ is the default installation directory, which can be
altered by invoking configure
with
./configure hosttype --prefix=install-dir
where install-dir is the alternative installation directory.
Nearly all files associated with GNATS
are installed in the
directory you indicated with GNATS_ROOT. The only files which are
installed in the file indicated with ‘prefix’ are:
send-pr
query-pr
edit-pr
installed in ‘prefix/bin’
libiberty.a
installed in ‘prefix/lib’
categories-list
named the value of GNATS_SITE, installed and updated by
mkcat
in ‘prefix/lib/gnats’
gnats.el
send-pr.el
installed in ‘prefix/lib/emacs/lisp’ (for information on byte-compiling these files, see Lisp Libraries in GNU Emacs)
gnats.info, send-pr.info
installed in ‘prefix/info’
GNATS ``man'' pages
installed in ‘prefix/man/manN’, where N
refers to the “man
” section (“1” for commands, “8” for
admin utilities, etc.).
It is not advised to change the values of these directories except
through the use of the flag ‘--prefix=dir’. All other
programs and files associated with GNATS
are installed
under the directory you indicated in ‘Makefile.in’ with the
variable ‘GNATS_ROOT’.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You may choose to build GNATS
in a different location
from the source code. In this case, you must first create the new
build directory, then call configure
from there:
mkdir build-directory cd build-directory srcdir/configure hosttype --srcdir=srcdir
where srcdir is the top level of the directory holding the
GNATS
distribution. The build directory is always your
current directory when you call configure
.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
configure
You can also use the following flags to configure
. None will
actually cause configure
to configure your GNATS
directory.
-V or --version
Prints out the version number of configure
.
--help
Prints out a list of all the flags configure
recognizes. Many
are not applicable to GNATS
.
The documentation for configure
is included with this
distribution in the directory
‘srcdir/gnats-3.01/etc’, and is
installed when GNATS
is installed. See What configure
does in Cygnus configure.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
over a networkIn order to install GNATS
for use on a network, you may
need root
privileges on each host you wish to install on.
GNATS
resides is NFS-mounted to each system that will need access to it, so
GNATS_ROOT will be the same for each host. (This can be
done with symbolic links as well.)
GNATS
source code tree in a separate
directory on each system you wish to build on.
This does a normal make all and make install for all files except those in the directory ‘srcdir/gnats’, which will only install:
query-pr
into ‘prefix/bin’
edit-pr
into ‘prefix/bin’
pr-edit
into ‘prefix/lib/gnats’
pr-addr
into ‘prefix/lib/gnats’
gnats.el
send-pr.el
into ‘prefix/lib/emacs/lisp’ (for information on byte-compiling these files, see Lisp Libraries in GNU Emacs)
on each system.
GNATS
will run on.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
config.h
fileThe file ‘gnats-3.01/gnats/config.h’ is used as a header file where you may define certain local conventions you wish to implement or suppress. The only local conventions switchable by this file are the following:
#define NOTIFY TRUE
in ‘config.h’, GNATS
will automatically send out a
reminder to the responsible person for a given PR if that PR is not
analyzed within a requisite period of time. The period is determined
for each submitter separately in the ‘submitters’.
See section The submitters
file, for more information
about the ‘submitters’ file. For information on at-pr
,
the program which sends out this reminder, see Introducing GNATS
.
#define ACKNOWLEDGE TRUE
GNATS
will automatically send an acknowledgment to the
submitter of a Problem Report when the PR is first received. The
acknowledgment is of the form:
To: your address From: gnats Subject: Re: category/serial-number:Synopsis In-Reply-To: Your message of date Thank you very much for your problem report. It has the internal identification: category/serial-number The individual assigned to look at your bug is: responsible Category: category of the bug Responsible: responsible Synopsis: Synopsis from submitted PR Arrival-Date: arrival date
#define DEFAULT_SUBMITTER "default"
so that GNATS
may assign the value ‘default’ to any
PR that arrives without a ‘Submitter-Id’. This value is usually
either ‘net’ or ‘unknown’.
#define KEEP_RECEIVED_HEADERS TRUE
to specify whether GNATS
should keep the
‘Received:’ headers for mail messages. Every email message has one
or more ‘Received:’ headers to tell you how a message got from the
sender to the recipient. Define this to be TRUE if you want
GNATS
to preserve all of those ‘Received:’ headers.
If you tend not to use the information, define it to be FALSE so
GNATS
will only keep the first ‘Received:’ header.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
administrationThe following files are located in
‘GNATS_ROOT/gnats-adm’, where
GNATS_ROOT is the resident directory of
GNATS
. See section Introducing GNATS
, to see how these files interact.
2.4.1 The categories file | The ‘categories’ file | |
2.4.2 The responsible file | The ‘responsible’ file | |
2.4.3 The submitters file | The ‘submitters’ file | |
2.4.4 The index file | The ‘index’ file | |
2.4.5 The current file | The ‘current’ file |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
categories
fileThis file contains a list of problem categories, specific to your site,
which GNATS
will track. You must edit this file
initially, creating valid categories and then running
‘GNATS_ROOT/gnats-bin/mkcat’ to create
the corresponding subdirectories of GNATS_ROOT. To
create a new category once the system is in place, simply log in as
gnats
, add a line to this file, and run mkcat
.
Lines beginning with a ‘#’ will be ignored.
Its consists of four fields delineated with colons, as follows:
category:description:responsible:notify
A unique, valid category name, which can contain only text characters, dashes, underbars, etc., and cannot contain spaces or any of the following characters:
! $ & * ( ) { } [ ] ` ' " ; : < > ~
Ideally, category names should not contain commas or begin with periods.
Each line will have a corresponding subdirectory in the main
GNATS
directory (GNATS_ROOT).
A terse textual description of the category.
The name tag of the party responsible for this category of problems, as listed in the ‘responsible’ file.
One or more other parties which should be notified when a bug with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas.
A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation bugs in a variety of areas, you could have entries such as
doc:General Doc Questions:myboss:me, mypal doc-rock:Doc for ROCK program:me:myboss doc-stone:Docs for STONE utilities:mypal:fred@bedrock.com doc-local:in-house documentation:me:doc-local-log
In the above example, bugs sent with a category of ‘doc’ are sent
to the local mail address (or alias) ‘myboss’, and also sent to the
addresses ‘me’ and ‘mypal’. Bugs with a category of
‘doc-rock’ are sent to the local addresses ‘me’ and
‘myboss’ only, while PRs sent with the category ‘doc-stone’
are sent outside the local organization as well as to ‘mypal’. PRs
arriving for the category ‘doc-local’ are sent only to ‘me’,
and are also sent to doc-local-log
(in this case, an alias should
be set up in ‘/etc/aliases’ to reflect a location for the log file,
such as ‘doc-local-log: /users/me/local-log’).
Whenever you add a new category, be sure to run
GNATS_ROOT/gnats-bin/mkcat
to create a subdirectory for it and update the local categories list.
Only one category must be present for GNATS
to function:
pending:Category for faulty PRs: gnats-admin:
The ‘pending’ directory is created automatically when you run make install.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
responsible
fileThis file contains a list of the responsible parties. Lines beginning with a ‘#’ will be ignored. Each entry contains three fields, separated by colons:
responsible:full-name:mail-address
A name-tag description of the party in question, such as her or his user name, or the name of the group. This name will be listed in the PR in the ‘Responsible’ field.
The full name of the party (“Butch Cassidy”; “Compiler Group”).
The full, valid mail address of the party. This field is only necessary if the responsible party has no local mail address or alias.
A sample ‘responsible’ listing might be:
ren:Ren Hoek: stimpy:Stimpson J. Cat:stimpy@lederhosen.org
Here, ren
is a local user. stimpy
is remote, so his full
address must be specified.
The following entry must be present for GNATS
to function:
gnats-admin: GNATS administrator:
(Remember, you put in gnats-admin
as a mail alias, so
for this purpose gnats-admin
is a local address.)
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
submitters
fileThis is an optional database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with a ‘#’ will be ignored.
Entries are in the format:
submitter-id:name:type:resp-time:contact:notify
A unique identifier for a specific site or other entity which will be submitting Problem Reports.
A textual description of this entity.
Optional description for the type of relationship this submitter to your support site. This could indicate a contract type, a level of expertise, etc.
GNATS
is capable of reminding responsible parties of
bugs marked with a ‘>Severity’ value of ‘critical’, or those
with a ‘>Severity’ of ‘serious’ and a ‘>Priority’ value
of ‘high’, when these bugs are not analyzed within a certain
period. This argument, in business hours, defines that response period.
This function is active if the NOTIFY
field is defined as
‘TRUE’ in ‘config.h’ at build-time; see The config.h
file. If NOTIFY
is ‘FALSE’, this field is
ignored. For information on at-pr
, the program which sends out
this reminder, see Introducing GNATS
.
The name tag of the “main contact” at the support site for this submitter. This contact should be in the ‘responsible’ file. Incoming bugs from submitter will be sent to this contact. Optionally, this field can be left blank.
Any other parties which should receive copies of Problem Reports sent in by submitter.
A few example entries in the ‘submitters’ file:
univ-hell: University of Southern Hades::3:beelzebub:lucifer tta: Telephones and Telegraphs of America:support:720:dave:
In this example, when a PR comes in from the University of Hades, it
should have ‘univ-hell’ in its ‘Submitter-Id’ field; this bug
will go to beelzebub
(who should be in the ‘responsible’
file), and if it is not analyzed within three hours a reminder message
will be sent. lucifer
also receives a copy of the bug, and a
copy of the reminder message as well (if it is sent). When Telephones
and Telegraphs of America utilizes their “support” contract and
submits a bug, a copy is sent only to dave
, who has 720 hours to
return an analysis before a reminder is sent.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
index
fileThe index is used to accelerate searches on the database. This file is
not created until the first PR comes in. It is then kept up to date by
GNATS
; you should never touch this file.
Any searches on subjects contained in the index will be much faster than searches which depend on data not in the index. The index contains entries for: id-number; category; responsible; submitter; state; class; and severity.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
current
fileThis file contains the last serial number assigned to an incoming PR.
It is used internally by GNATS
; you need never touch
this file.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
toolsThe following programs comprise GNATS
:
send-pr
Used by anyone who has a problem with a given set of software to submit a report of the problem to the maintainers of that software
query-pr
Used by software maintainers to query the GNATS
database
(see section Querying individual Problem Reports).
edit-pr
Used by software maintainers to edit Problem Reports (to record new data, to change the responsible party, etc.) (see section Editing existing Problem Reports).
mkcat
Used by the GNATS
administrator when creating new
categories (see section The categories
file).
rmcat
Does the opposite of mkcat
, i.e. removes categories
(see section Managing GNATS
).
mkdist
Used by the GNATS
administrator when creating a
distribution of the program send-pr
for offsite submitters of PRs
(see section Configuring send-pr for the outside world).
gen-index
Used by the GNATS
administrator if the index file
becomes corrupted, or if an up-to-date copy of it is wanted for some
reason. gen-index
builds an index and prints it to the standard
output (see section Managing GNATS
).
queue-pr
Handles incoming bugs, first through a mail alias by queueing incoming
PRs as they arrive, and second as a periodic transfer agent between the
queue and the database (see section Introducing GNATS
).
file-pr
The internal program which files Problem Reports as they come in
(see section Introducing GNATS
).
at-pr
Used internally by GNATS
to send reminders to
maintainers based on quoted response times (see section Introducing GNATS
).
pr-edit
Used by edit-pr
to error-check and submit edited Problem Reports
(see section Editing existing Problem Reports).
pr-addr
Provides a valid electronic mail address for a given responsible name tag. Information is drawn from the file ‘GNATS_ROOT/gnats-adm/responsible’. Used internally.
Of these, only send-pr
, query-pr
, and edit-pr
are
installed in a public directory. The database itself is write-protected
solely to maintain data consistency. mkcat
, rmcat
,
gen-index
and mkdist
are designed for use by a database or
system administrator, while at-pr
, pr-edit
,
pr-addr
, file-pr
, and ‘queue-pr -q’ are
completely internal and not meant to be called by hand.
‘queue-pr -r’ can be run by hand, but it is usually easiest to
let it run periodically via cron
.
3.1 Querying individual Problem Reports | ||
3.2 Editing existing Problem Reports | ||
3.3 Managing GNATS | Managing GNATS | |
3.4 Configuring send-pr for the outside world | Configuring ‘send-pr’ for the outside world |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can obtaining data from the database through the program
query-pr
, which uses the search parameters you provide with
options and/or arguments to find matching Problem Reports in the
database. You can invoke query-pr
from within Emacs as well as
from the shell.
All arguments to query-pr
are optional. If you don’t specify a
PR and don’t give any search parameters, query-pr
will display
the entire database. All arguments are considered as PR numbers to
display. Any number of options can be given; all are connected with a
logical AND
.
3.1.1 Invoking query-pr | ||
3.1.2 Example queries |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
query-pr
query-pr
uses the same arguments whether it is invoked from the
shell or from Emacs. From the shell, simply type query-pr,
followed by any search parameters you wish to exercise. From Emacs,
type M-x query-pr, and you will be prompted for search
parameters in the minibuffer. Use
C-x ` or M-x next-error
to scroll through the matching PRs.
The usage for query-pr
is:
query-pr [gnats-id] [-i | --sql] [-F | --full] [-d directory | --directory=directory] [-c category | --category=category] [-S submitter | --submitter=submitter] [-r responsible | --responsible=responsible] [-s state | --state=state] [-C [yes | no] | --confidential=[yes | no]] [-e severity | --severity=severity] [-p priority | --priority=priority] [-O originator | --originator=originator] [-o outfile | --output=outfile] [-P | --print-path] [-x | --skip-closed] [-q | --summary] [-V | --version] [-h | --help ]
Without the ‘-F’ or ‘--full’ option, query-pr
will only
display a “header” for each PR which meets the search criteria. Any
number of the options listed may be included in the search criteria.
gnats-id
The identification number of the PR you wish to view.
-i
--sql
Prints information in a form readable by an SQL database; see Example queries.
-F
--full
Prints the full Problem Report rather than just summary information.
-d directory
--directory=directory
Changes the directory to directory from GNATS_ROOT.
-c category
--category=category
Search only for PRs with a ‘Category’ field of category.
-S submitter
--submitter=submitter
Search only for PRs with a ‘Submitter’ field of submitter.
-r responsible
--responsible=responsible
Search only for PRs with a ‘Responsible’ field of responsible.
-s state
--state=state
Search only for PRs with a ‘State’ field of state. Values
will be one of: open
, analyzed
, suspended
,
feedback
, or closed
.
-C [yes | no]
--confidential=[yes | no]
Search only for PRs with a ‘Confidential’ field of either yes or no. If this option is not given, all PRs will be eligible for the search regardless of their confidentiality.
-e severity
--severity=severity
Search only for PRs with a ‘Severity’ field of severity.
Values will be one of: critical
, serious
, or
non-critical
.
-p priority
--priority=priority
Search only for PRs with a ‘Priority’ field of priority.
Values will be one of: high
, medium
, or low
.
-O originator
--originator=originator
Search only for PRs with an ‘Originator’ field of originator. Since this option does not reference the index, queries using it will be much faster if another search criterion is used that is part of the index.
-o outfile
--output=outfile
Print all output to outfile rather than to the standard output.
-P
--print-path
Prints the path which query-pr
used to find the current PR. A
line of the form ‘directory/number:number’ will
be printed before each PR. You will probably never want to use this
option; it is automatically used from within Emacs to facilitate
scrolling through groups of PRs with C-x `.
-x
--skip-closed
Omit closed PRs from the search path. This option is ignored if you are doing a search on the ‘>State:’ field (using ‘-s’ or ‘--state=state’).
-q
--summary
Print a short single-line summary of PR information.
-V
--version
Print the version number of query-pr
.
-h
--help
Print a brief usage summary.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following query:
query-pr --category=rats --responsible=fred --state=analyzed
yields all PRs in the database which contain the fields:
>Category: rats and >Responsible: fred and >State: analyzed
The following query:
query-pr 500 --submitter=icabod
returns summary information for PR number 500 if and only if its
‘Submitter-Id’ field contains the value ‘mitchell’ (i.e., only
if PR number 500 was submitted by mitchell
.)
The following example shows another alternative output function:
query-pr --sql search criteria…
The ‘--sql’ (or ‘-i’) option prints information in a format which can be uploaded into a relational database. The output is one line per PR, delimited with pipe (‘|’) symbols, and contains the following fields in order:
id-number | category | synopsis | confidential | \ severity | priority | responsible | state | class | \ submitter-id | arrival-date | originator | release
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Use edit-pr
to make changes to existing PRs in the database. The
shell script and Emacs Lisp file are designed to keep the data in each
Problem Report and in the index consistent, and also provide an easy and
safe way to edit PRs. State changes (when progress toward a solution is
being made) and responsibility changes (“passing the bug”) are tracked
in the ‘>Audit-Trail:’ field.
3.2.1 edit-pr in Emacs | ||
3.2.2 edit-pr from the shell |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
edit-pr
in EmacsCall edit-pr
from within Emacs with M-x edit-pr. You
will be prompted for a PR identification number; type the number of the
PR you wish to edit.
The easiest way to edit a PR from Emacs is to use the special key bindings provided. These are:
C-c C-s
gnats-submit-pr
Save and submit the PR currently being edited. Do this when you’re finished editing; if you simply kill the buffer, your changes will be lost.
C-c C-e
edit-pr
Runs edit-pr
in a new buffer.
C-c C-a
gnats-mail-reply
Sends mail to the originator of this PR, using the address in the ‘From:’ field of the mail header.
C-c RET
gnats-mail-other-window
Splits the current window, and sends mail to the originator of this PR, using the address in the ‘From:’ field of the mail header, in the new window.
C-c C-r
gnats-responsible-change-from-to
Change the ‘Responsible’ field. You will be prompted for the new responsible person. Each time the ‘Responsible’ field is changed, the previous value and the reason for the change are both mailed to the responsible parties and the submitter, and recorded in the ‘Audit-Trail’ section of the PR as follows:
Responsible-Changed-<From>-<To>
: Records the value change.Responsible-Changed-By
: Your name here.Responsible-Changed-When
: Records the current date.Responsible-Changed-Why
: Emacs places the point in thisfield as a prompt for you to fill in the reason for the change.
C-c C-s
gnats-state-change-from-to
Change the ‘State’ field. You will be prompted for the new state. Each time the ‘State’ field is changed, the previous value and the reason for the change are both mailed to the responsible parties and the submitter, and recorded in the ‘Audit-Trail’ section of the PR as follows:
State-Changed-<From>-<To>
: Records the value change.State-Changed-By
: Your name here.State-Changed-When
: Records the current date.State-Changed-Why
: Emacs places the point in this field asa prompt for you to fill in the reason for the change.
M-C-b
gnats-backward-field
Moves the point to the beginning of the value of the current field.
M-C-f
gnats-forward-field
Moves the point to the end of the value of the current field.
M-p
gnats-previous-field
Moves the point back one field to the beginning of the value of the previous field.
M-n
gnats-next-field
Moves the point forward one field to the beginning of the value of the next field.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
edit-pr
from the shellThe usage for the edit-pr
shell script is:
edit-pr gnats-id [-v | --version] [-h | --help]
You must first determine which PR you want to edit. The options are:
-v or --version
Prints the current version number of edit-pr
.
-h or --help
Prints the usage message shown above.
edit-pr
first examines the value you specify for
gnats-id and locks the corresponding PR if it is not
already locked. This is to prevent you from editing a PR at the same
time as another user. If the PR you wish to edit is already in the
process of being edited, edit-pr
will tell you the name of the
person who has it locked.
edit-pr
then calls the editor specified in your environment
variable EDITOR
on a temporary copy of that PR. (If you don’t
have the variable EDITOR
defined in your environment, the default
editor vi
is used.)
Edit the PR, changing any relevant fields or adding to existing
information. When you exit the editor, you will be asked on the
standard input to specify reasons for changes if you’ve changed either
the ‘Responsible’ field or the ‘State’ field; the information
you provide when changing either of these two fields is tracked along
with the change that occurred, your name, and the time of change in a
section of the PR called the ‘Audit-Trail’. Copies of the
‘Audit-Trail’ are then mailed to you, to
gnats-admin
, and to the person Responsible
for
the bug as listed in the ‘gnats-adm/responsible’ (both
the new Responsible
and the old one, if that value changed).
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
GNATS
In daily usage, GNATS
is self-maintaining. However,
there are various administrative duties which will have to be performed
periodically:
pending
directoryIf a Problem Report arrives with a ‘Category’ field that is
unrecognized by the ‘gnats-adm/categories’ file, it is
placed in the directory ‘GNATS_ROOT/pending’, as
GNATS
has no way of knowing which subdirectory it should
be filed under. GNATS
sends a notice to the
gnats-admin
and to the party responsible for that
submitter (as listed in the ‘submitters’ file) when this occurs.
To file these PRs, simply call edit-pr
on each file in the
‘pending’ directory and repair the problematic category. In many
cases the culprit is simply a typographical error, although it may be
necessary sometimes to contact the submitter of the PR to decipher the
originator’s intentions.
To add a new category, simply insert a new line in the
‘categories’ file and then run the program mkcat
. This
automatically creates a subdirectory in GNATS_ROOT for
this category, and updates the local list of known categories for
send-pr
. See section The categories
file.
It is important to note that only your local send-pr
will have
access to this new information; any copies of send-pr
which you
have distributed will have outdated category lists. You must either
contact your submitters and instruct them to update their copy of the
categories list, which they installed in
‘libdir/gnats/support-site’ from the
distribution you provided, or you must build another distribution of
send-pr
with this new information and redistribute it.
To remove a category, you need to:
rmcat
, so
long as they abide by the above constraints).
send-pr
After you edit your ‘categories’ file to reflect the nature of
your support activities, you can build a distribution of this custom
category configuration by invoking the command mkdist
.
mkdist
creates a ‘Makefile’ and a valid category list in a
directory which you specify on the command line, which will contain a
full distribution of the program send-pr
, including a
Makefile
, an up-to-date list of categories your organization
supports, and all send-pr
documentation. See section Configuring send-pr
for the outside world.
If for some reason the ‘index’ becomes corrupted, or if you wish to
generate a new one for some reason, use the program gen-index
as
follows.
gen-index [-n | --numeric] [-d dir | --directory=dir] [-o file | --outfile=file] [-h | --help]
With no options, gen-index
generates an index that is ordered the
same as the order of the categories as they appear in the
‘categories’ file. The options are:
-n
--numeric
Sort index entries numerically.
-d dir
--directory=dir
Use dir as the root directory.
-o file
--outfile=file
Place output in the file file rather than sending it to standard output.
-h
--help
Print the usage for gen-index
.
edit-pr
“locks” each file while the file is being edited. This
is to ensure that no two users edit the same PR at the same time, thus
avoiding data collisions. If edit-pr
crashes for some reason,
however, the lock remains in place, as edit-pr
does not remove
the lock until the new PR is in place. File locks are simply files in
the database named
GNATS_ROOT/category/gnats-id.lock
where gnats-id is the PR being edited.
If a GNATS
user finds a PR locked, first make sure that
no one else is editing that PR (it has been known to occur that some
users will background an editing session and then forget that it
exists), then log in as gnats
and run
gnats-bin/pr-edit --unlock gnats-id
Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible.
Log files often grow to unfathomable proportions. As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more bugs.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
send-pr
for the outside worldNow that GNATS
is up and running on your system, you
probably want to distribute send-pr
to all your friends,
relatives, enemies, etc. so they can more easily submit bugs to your
organization. To do this, log in as gnats
and create a
directory to hold the distribution. Then run the program
gnats-bin/mkdist dist-directory release
This creates a directory called dist-directory (you can specify a
full pathname) which contains a full distribution of the program
send-pr
, including a ‘Makefile’ and all the send-pr
documentation. You can then simply package up this directory and send
it to your bug report submitters.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Jump to: | -
>
A B C D E F G H I K L M N O P Q R S T U V W |
---|
Jump to: | -
>
A B C D E F G H I K L M N O P Q R S T U V W |
---|
[Top] | [Contents] | [Index] | [ ? ] |
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on May 19, 2025 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on May 19, 2025 using texi2html 5.0.