diff options
Diffstat (limited to 'gnu/usr.bin/send-pr/doc/s-usage.texi')
| -rw-r--r-- | gnu/usr.bin/send-pr/doc/s-usage.texi | 570 |
1 files changed, 0 insertions, 570 deletions
diff --git a/gnu/usr.bin/send-pr/doc/s-usage.texi b/gnu/usr.bin/send-pr/doc/s-usage.texi deleted file mode 100644 index 5c9006b200af..000000000000 --- a/gnu/usr.bin/send-pr/doc/s-usage.texi +++ /dev/null @@ -1,570 +0,0 @@ -@c $FreeBSD$ - -@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 -* Submitting via e-mail:: Submitting a Problem Report via direct e-mail -* 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}. @xref{send-pr from the shell}. -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 on your local machine 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}. @emph{NOTE:} If you are using -send-pr to send problem reports to the FreeBSD Project, this version of -send-pr already has a customer ID in it and you do not need to request a -new one. -@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 - -@c ------------------------------------------------------------------------- -@node Submitting via e-mail -@section Submitting a Problem Report via direct e-mail -@cindex Direct e-mail -@cindex Submitting a PR via e-mail -In addition to using @code{send-pr}, there is another way to submit a problem -report. You can simply send an e-mail message to the support site. - -To do this, look at the address in the @samp{To:} field of the @code{send-pr} -template. When you send unformatted e-mail to this address, @sc{gnats} -processes the message as a new problem report, filling in as many fields from -defaults as it can: - -@table @code -@item Synopsis -The @samp{>Synopsis} field is filled in by the @samp{Subject:} header. - -@item Submitter ID -@sc{gnats} will try to derive the @samp{>Submitter} field from the address -in the @samp{From:} header. - -@item Description -All of the text in the body of the e-mail message is put into the -@samp{>Description} field. Each line of the text is indented by one space, -indicating that it is "quoted text" from the sender. -@end table - -Other fields, such as category, version, severity, etc. are set to default -values (if the @sc{gnats} administrator has set them). - -@c -------------------------------------------------------------------------- -@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 |