Mercurial > hg > xemacs-beta
diff man/gnats/s-usage.texi @ 112:48d667d6f17f r20-1b8
Import from CVS: tag r20-1b8
author | cvs |
---|---|
date | Mon, 13 Aug 2007 09:20:48 +0200 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/s-usage.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,533 @@ +@c This is the usage section for send-pr. It is called as +@c chapter (Invoking send-pr) by send-pr.texi, and also as +@c section (Submitting Problem Reports) by gnats.texi (chapter/section +@c identifiers are adjusted accordingly) + +@c FIXME! This still seems jumbled... + +You can invoke @code{send-pr} from a shell prompt or from within +@sc{gnu} Emacs using @w{@samp{M-x send-pr}}. + +@menu +* using send-pr:: Creating new Problem Reports +* send-pr in Emacs:: Using send-pr from within Emacs +* send-pr from the shell:: Invoking send-pr from the shell +* Helpful hints:: +@end menu + +@node using send-pr +@section Creating new Problem Reports + +@c FIXME - this is a long node +Invoking @code{send-pr} presents a PR @dfn{template} with a number of +fields already filled in. Complete the template as thoroughly as +possible to make a useful bug report. Submit only one bug with each PR. + +@cindex template +A template consists of three sections: + +@table @dfn +@item Comments +The top several lines of a blank template consist of a series of +comments that provide some basic instructions for completing the Problem +Report, as well as a list of valid entries for the @samp{>Category:} +field. These comments are all preceded by the string @samp{SEND-PR:} +and are erased automatically when the PR is submitted. The +instructional comments within @samp{<} and @samp{>} are also removed. +(Only these comments are removed; lines you provide that happen to have +those characters in them, such as examples of shell-level redirection, +are not affected.) + +@item Mail Header +@code{send-pr} creates a standard mail header. @code{send-pr} completes +all fields except the @samp{Subject:} line with default values. +(@xref{Fields,,Problem Report format}.) + +@item @sc{gnats} fields +These are the informational fields that @sc{gnats} uses to route your +Problem Report to the responsible party for further action. They should +be filled out as completely as possible. (@xref{Fields,,Problem Report +format}. Also see @ref{Helpful hints,,Helpful hints}.) +@end table + +@ifset SENDPR +@noindent +For examples of a Problem Report template and complete Problem Report, +see @ref{An Example}. +@end ifset + +The default template contains your preconfigured @samp{>Submitter-Id:}. +@code{send-pr} attempts to determine values for the @samp{>Originator:} +and @samp{>Organization:} fields (@pxref{Fields,,Problem Report +format}). @code{send-pr} will set the @samp{>Originator:} field to +the value of the @code{NAME} environment variable if it has been set; +similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}. +@code{send-pr} also attempts to find out some information +about your system and architecture, and places this information in the +@samp{>Environment:} field if it finds any. + +You may submit problem reports to different Support Sites from the +default site by specifying the alternate site when you invoke +@code{send-pr}. Each @code{site} has its own list of categories for +which it accepts Problem Reports. +@c FIXME! This should go in.. +@c For a list of sites to whom @code{send-pr} is configured to send +@c Problem Reports, type @w{@samp{send-pr -S}}. +@ifset SENDPR +(@xref{default site,,Setting a default @var{site}}.) +@end ifset + +@code{send-pr} also provides the mail header section of the template +with default values in the @samp{To:}, @samp{From:}, and +@samp{Reply-To:} fields. The @samp{Subject:} field is empty. + +The template begins with a comment section: + +@cindex template comment section +@cindex comment section in the PR template +@smallexample +@group +SEND-PR: -*- send-pr -*- +SEND-PR: Lines starting with `SEND-PR' will be removed +SEND-PR: automatically as well as all comments (the text +SEND-PR: below enclosed in `<' and `>'). +SEND-PR: +SEND-PR: Please consult the document `Reporting Problems +SEND-PR: Using send-pr' if you are not sure how to fill out +SEND-PR: a problem report. +SEND-PR: +SEND-PR: Choose from the following categories: +@end group +@end smallexample + +@noindent +and also contains a list of valid @code{>Category:} values for the +Support Site to whom you are submitting this Problem Report. One (and +only one) of these values should be placed in the @code{>Category:} +field. +@ifset SENDPR +A complete sample bug report, from template to completed PR, is shown in +@ref{An Example}. For a complete list of valid categories, type +@w{@samp{send-pr -L}} at your prompt. @xref{Valid Categories,,Valid +Categories}, for a sample list of categories, . +@end ifset + +@c FIXME.. this sounds awkward +The mail header is just below the comment section. Fill out the +@samp{Subject:} field, if it is not already completed using the value of +@samp{>Synopsis:}. The other mail header fields contain default values. + +@cindex mail header section +@smallexample +@group +To: @var{support-site} +Subject: @emph{complete this field} +From: @var{your-login}@@@var{your-site} +Reply-To: @var{your-login}@@@var{your-site} +X-send-pr-version: send-pr @value{VERSION} +@end group +@end smallexample + +@noindent +where @var{support-site} is an alias for the Support Site you wish to +submit this PR to. + +The rest of the template contains @sc{gnats} fields. Each field is +either automatically completed with valid information (such as your +@samp{>Submitter-Id:}) or contains a one-line instruction specifying the +information that field requires in order to be correct. For example, +the @samp{>Confidential:} field expects a value of @samp{yes} or +@samp{no}, and the answer must fit on one line; similarly, the +@samp{>Synopsis:} field expects a short synopsis of the problem, which +must also fit on one line. Fill out the fields as completely as +possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to +what kinds of information to include. + +In this example, words in @emph{italics} are filled in with +pre-configured information: + +@cindex @code{send-pr} fields +@smallexample +@group +>Submitter-Id: @emph{your submitter-id} +>Originator: @emph{your name here} +>Organization: + @emph{your organization} +>Confidential:<[ yes | no ] (one line)> +>Synopsis: <synopsis of the problem (one line)> +>Severity: <[non-critical | serious | critical](one line)> +>Priority: <[ low | medium | high ] (one line)> +>Category: <name of the product (one line)> +>Class: <[sw-bug | doc-bug | change-request | support]> +>Release: <release number (one line)> +>Environment: + <machine, os, target, libraries (multiple lines)> + +>Description: + <precise description of the problem (multiple lines)> +>How-To-Repeat: + <code/input/activities to reproduce (multiple lines)> +>Fix: + <how to correct or work around the problem, if known + (multiple lines)> +@end group +@end smallexample + +@cindex @code{Submitter-Id} field +@cindex @code{>Submitter-Id:} +When you finish editing the Problem Report, @code{send-pr} mails it to +the address named in the @samp{To:} field in the mail header. +@code{send-pr} checks that the complete form contains a valid +@samp{>Category:}. + +@ifset SENDPR +Your copy of @code{send-pr} should have already been customized on +installation to reflect your @samp{>Submitter-Id:}. (@xref{Installing +send-pr, , Installing @code{send-pr} on your system}.) If you don't +know your @samp{>Submitter-Id:}, you can request it using +@w{@samp{send-pr --request-id}}. If your organization is not affiliated +with the site you send Problem Reports to, a good generic +@samp{>Submitter-Id:} to use is @samp{net}. +@end ifset + +@cindex bad Problem Reports +@cindex errors +@cindex invalid Problem Reports +If your PR has an invalid value in one of the @sc{Enumerated} fields +(@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in +a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine. +@var{nnnn} is the process identification number given to your current +@code{send-pr} session. If you are running @code{send-pr} from the +shell, you are prompted as to whether or not you wish to try editing the +same Problem Report again. If you are running @code{send-pr} from +Emacs, the Problem Report is placed in the buffer +@w{@samp{*send-pr-error*}}; you can edit this file and then submit it +with + +@smallexample +M-x gnats-submit-pr +@end smallexample + +@cindex subsequent mail +@cindex other mail +@cindex appending PRs +@cindex saving related mail +@cindex related mail +Any further mail concerning this Problem Report should be carbon-copied +to the @sc{gnats} mailing address as well, with the category and +identification number in the @samp{Subject:} line of the message. + +@smallexample +Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject} +@end smallexample + +@noindent +Messages which arrive with @samp{Subject:} lines of this form are +automatically appended to the Problem Report in the @samp{>Audit-Trail:} +field in the order received. + +@c --------------------------------------------------------------- +@node send-pr in Emacs +@section Using @code{send-pr} from within Emacs +@cindex using @code{send-pr} from within Emacs +@cindex @code{send-pr} within Emacs +@cindex invoking @code{send-pr} from Emacs +@cindex interactive interface + +You can use an interactive @code{send-pr} interface from within @sc{gnu} +Emacs to fill out your Problem Report. We recommend that you +familiarize yourself with Emacs before using this feature +(@pxref{Introduction,,Introduction,emacs,GNU Emacs}). + +Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing +@w{@samp{M-x send-pr}} doesn't work, see your system administrator for +help loading @code{send-pr} into Emacs.} @code{send-pr} responds with a +Problem Report template preconfigured for the Support Site from which +you received @code{send-pr}. (If you use @code{send-pr} locally, the +default Support Site is probably your local site.) + +You may also submit problem reports to different Support Sites from the +default site. To use this feature, invoke @code{send-pr} with + +@smallexample +C-u M-x send-pr +@end smallexample + +@code{send-pr} prompts you for the name of a @var{site}. @var{site} is +an alias on your local machine which points to an alternate Support +Site. + +@cindex Emacs +@code{send-pr} displays the template and prompts you in the minibuffer +with the line: +@smallexample +>Category: other +@end smallexample + +@noindent +Delete the default value @samp{other} @emph{in the minibuffer} and +replace it with the keyword corresponding to your problem (the list of +valid categories is in the topmost section of the PR template). For +example, if the problem you wish to report has to do with the @sc{gnu} C +compiler, and your support organization accepts bugs submitted for this +program under the category @samp{gcc}, delete @samp{other} and then type +@w{@samp{gcc[@key{RET}]}}. @code{send-pr} replaces the line + +@smallexample +>Category: <name of the product (one line)> +@end smallexample + +@noindent +in the template with + +@smallexample +>Category: gcc +@end smallexample + +@noindent +and moves on to another field. + +@cindex completion in Emacs +@cindex name completion in Emacs +@w{@code{send-pr}} provides name completion in the minibuffer. For +instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr} +attempts to complete the entry for you. Typing @w{@samp{g[@key{TAB}]}} +may not have the same effect if several possible entries begin with +@samp{g}. In that case @code{send-pr} cannot complete the entry because +it cannot determine whether you mean @samp{gcc} or, for example, +@samp{gdb}, if both of those are possible categories. +@w{@code{send-pr}} continues to prompt you for a valid entry until you +enter one. + +@w{@code{send-pr}} prompts you interactively to enter each field for +which there is a range of specific choices. If you attempt to enter a +value which is not in the range of acceptable entries, @code{send-pr} +responds with @w{@samp{[No match]}} and allows you to change the entry +until it contains an acceptable value. This avoids unusable information +(at least in these fields) and also avoids typographical errors which +could cause problems later. + +@code{send-pr} prompts you for the following fields: + +@c FIXME - should these go before the discussion on completion? +@example +@group +>Category: +>Confidential: (@emph{default}: no) +>Severity: (@emph{default}: serious) +>Priority: (@emph{default}: medium) +>Class: (@emph{default}: sw-bug) +>Release: +>Synopsis: (@emph{this value is copied to @code{Subject:}}) +@end group +@end example + +@noindent +After you complete these fields, @w{@code{send-pr}} places the cursor in +the @samp{>Description:} field and displays the message + +@smallexample +To send the problem report use: C-c C-c +@end smallexample + +@noindent +in the minibuffer. At this point, edit the file in the main buffer to +reflect your specific problem, putting relevant information in the +proper fields. +@ifset SENDPR +@xref{An Example}, for a sample Problem Report. +@end ifset + +@w{@samp{send-pr}} provides a few key bindings to make moving +around in a template buffer more simple: + +@table @code +@item C-c C-f +@itemx M-x change-field +Changes the field under the cursor. @code{edit-pr} prompts you for a +new value. + +@item M-C-b +@itemx M-x gnats-backward-field +Moves the cursor to the beginning of the value of the current field. + +@item M-C-f +@itemx M-x gnats-forward-field +Moves the cursor to the end of the value of the current field. + +@item M-p +@itemx M-x gnats-previous-field +Moves the cursor back one field to the beginning of the value of the +previous field. + +@item M-n +@itemx M-x gnats-next-field +Moves the cursor forward one field to the beginning of the value of the +next field. +@end table + +@code{send-pr} takes over again when you type @samp{C-c C-c} to send the +message. @code{send-pr} reports any errors in a separate buffer, which +remains in existence until you send the PR properly (or, of course, +until you explicitly kill the buffer). + +For detailed instructions on using Emacs, see +@ref{Introduction,,,emacs,GNU Emacs}. + +@node send-pr from the shell +@section Invoking @code{send-pr} from the shell +@cindex command line options +@cindex invoking @code{send-pr} from the shell +@cindex shell invocation + +@c FIXME! Add [ -S ] right after [ -L ]... +@smallexample +send-pr [ @var{site} ] + [ -f @var{problem-report} | --file @var{problem-report} ] + [ -t @var{mail-address} | --to @var{mail-address} ] + [ --request-id ] + [ -L | --list ] [ -P | --print ] + [ -V | --version] [ -h | --help ] +@end smallexample + +@var{site} is an alias on your local machine which points to an address +used by a Support Site. If this argument is not present, the default +@var{site} is usually the site which you received @code{send-pr} from, +or your local site if you use @sc{gnats} locally. +@ifset SENDPR +(@xref{default site,,Setting a default @var{site}}.) +@end ifset + +Invoking @code{send-pr} with no options calls the editor named in your +environment variable @code{EDITOR} on a default PR template. If the +environment variable @code{PR_FORM} is set, its value is used as a file +name which contains a valid template. If @code{PR_FORM} points to a +missing or unreadable file, or if the file is empty, @code{send-pr} +generates an error message and opens the editor on a default template. + +@table @code +@item -f @var{problem-report} +@itemx --file @var{problem-report} +Specifies a file, @var{problem-report}, where a completed Problem Report +already exists. @code{send-pr} sends the contents of the file without +invoking an editor. If @var{problem-report} is @samp{-}, +@w{@code{send-pr}} reads from standard input. + +@item -t @var{mail-address} +@itemx --to @var{mail-address} +Sends the PR to @var{mail-address}. The default is preset when +@code{send-pr} is configured. @emph{This option is not recommended}; +instead, use the argument @var{site} on the command line. + +@item -c @var{mail-address} +@itemx --cc @var{mail-address} +Places @var{mail-address} in the @code{Cc:} header field of the message +to be sent. + +@item --request-id +Sends a request for a @code{>Submitter-Id:} to the Support Site. + +@cindex listing valid categories +@item -L +@itemx --list +Prints the list of valid @code{>Category:} values on standard output. +No mail is sent. + +@item -s @var{severity} +@itemx --severity @var{severity} +@cindex @code{send-pr} fields +Sets the initial value of the @code{>Severity:} field to @var{severity}. + +@ignore +@item -S +@itemx --sites +Displays a list of valid @var{site} values on standard output. No mail +is sent. +@end ignore + +@item -P +@itemx --print +Displays the PR template. If the variable @code{PR_FORM} is set in your +environment, the file it specifies is printed. If @code{PR_FORM} is not +set, @code{send-pr} prints the standard blank form. If the file +specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an +error message. No mail is sent. + +@item -V +@itemx --version +Displays the @code{send-pr} version number and a usage summary. No mail +is sent. + +@item -h +@itemx --help +Displays a usage summary for @code{send-pr}. No mail is sent. +@end table + +@node Helpful hints +@section Helpful hints +@cindex helpful hints +@cindex Using and Porting @sc{gnu} CC +@cindex effective problem reporting +@cindex kinds of helpful information +@cindex information to submit +@cindex Report all the facts! + +There is no orthodox standard for submitting effective bug reports, +though you might do well to consult the section on submitting bugs for + +@sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and +Porting GNU CC}, by Richard Stallman. This section contains +instructions on what kinds of information to include and what kinds of +mistakes to avoid. + +In general, common sense (assuming such an animal exists) dictates the +kind of information that would be most helpful in tracking down and +resolving problems in software. +@itemize @bullet +@item +Include anything @emph{you} would want to know if you were looking at +the report from the other end. There's no need to include every minute +detail about your environment, although anything that might be different +from someone else's environment should be included (your path, for +instance). + +@item +Narratives are often useful, given a certain degree of restraint. If a +person responsible for a bug can see that A was executed, and then B and +then C, knowing that sequence of events might trigger the realization of +an intermediate step that was missing, or an extra step that might have +changed the environment enough to cause a visible problem. Again, +restraint is always in order (``I set the build running, went to get a +cup of coffee (Columbian, cream but no sugar), talked to Sheila on the +phone, and then THIS happened@dots{}'') but be sure to include anything +relevant. + +@item +Richard Stallman writes, ``The fundamental principle of reporting bugs +usefully is this: @strong{report all the facts}. If you are not sure +whether to state a fact or leave it out, state it!'' This holds true +across all problem reporting systems, for computer software or social +injustice or motorcycle maintenance. It is especially important in the +software field due to the major differences seemingly insignificant +changes can make (a changed variable, a missing semicolon, etc.). + +@item +Submit only @emph{one} problem with each Problem Report. If you have +multiple problems, use multiple PRs. This aids in tracking each problem +and also in analyzing the problems associated with a given program. + +@item +It never hurts to do a little research to find out if the bug you've +found has already been reported. Most software releases contain lists +of known bugs in the Release Notes which come with the software; see +your system administrator if you don't have a copy of these. + +@item +The more closely a PR adheres to the standard format, the less +interaction is required by a database administrator to route the +information to the proper place. Keep in mind that anything that +requires human interaction also requires time that might be better spent +in actually fixing the problem. It is therefore in everyone's best +interest that the information contained in a PR be as correct as +possible (in both format and content) at the time of submission. +@end itemize