diff options
-rw-r--r-- | gnu/usr.bin/send-pr/COPYING | 339 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/Makefile | 29 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/README | 43 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/categories | 2 | ||||
-rwxr-xr-x | gnu/usr.bin/send-pr/install-sid.sh | 82 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr-el.in | 744 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.1 | 269 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.info | 1604 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.sh | 523 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.texi | 657 |
10 files changed, 4292 insertions, 0 deletions
diff --git a/gnu/usr.bin/send-pr/COPYING b/gnu/usr.bin/send-pr/COPYING new file mode 100644 index 0000000..515b6d3 --- /dev/null +++ b/gnu/usr.bin/send-pr/COPYING @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +he GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + Appendix: How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + <signature of Ty Coon>, 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/gnu/usr.bin/send-pr/Makefile b/gnu/usr.bin/send-pr/Makefile new file mode 100644 index 0000000..76ecf50 --- /dev/null +++ b/gnu/usr.bin/send-pr/Makefile @@ -0,0 +1,29 @@ +# +# Makefile for building a standalone send-pr. +# + +BINDIR= /usr/bin +NOOBJ=noobj +MAN1= send-pr.1 +DATADIR=/etc +SUBMITTERS=current-users +RELEASE=`uname -rsm` + +all: send-pr.sh send-pr-el.in install-sid.sh + sed -e 's,@DATADIR@,$(DATADIR),g' \ + -e 's/@DEFAULT_RELEASE@/$(RELEASE)/g' send-pr.sh > send-pr + sed -e 's,@DATADIR@,$(DATADIR),g' \ + -e 's/@DEFAULT_RELEASE@/$(RELEASE)/g' send-pr-el.in > send-pr.el + sed -e 's,@BINDIR@,$(BINDIR),g' install-sid.sh > install-sid + +beforeinstall: + install -c -o ${BINOWN} -g ${BINGRP} -m ${BINMODE} \ + ${.CURDIR}/send-pr ${DESTDIR}/usr/bin/send-pr + install -c -o ${BINOWN} -g ${BINGRP} -m 0644 \ + ${.CURDIR}/categories ${DESTDIR}/etc/gnats/freefall + sh ${.CURDIR}/install-sid ${SUBMITTERS} + +clean: + rm -f send-pr send-pr.el install-sid + +.include <bsd.prog.mk> diff --git a/gnu/usr.bin/send-pr/README b/gnu/usr.bin/send-pr/README new file mode 100644 index 0000000..b479179 --- /dev/null +++ b/gnu/usr.bin/send-pr/README @@ -0,0 +1,43 @@ + send-pr - sends bug reports to a central support site + +`send-pr' uses electronic mail to submit support questions and +software bugs to a central site. No piece of software is perfect, and +software organizations understand this `send-pr' is designed to allow +users who have problems to submit reports of these problems to sites +responsible for supporting the software in question, in a defined form +which can be read by an electronically managed database. + +`send-pr' is part of a suite of programs known collectively as GNATS, +an acronym for Problem Report Management System. GNATS consists of +several programs which, used in concert, formulate and partially +administer a database of Problem Reports, or PRs, at a central support +site. A PR goes through several states in its lifetime; GNATS tracks +the PR and all information associated with it through each state and +finally acts as an archive for PRs which have been resolved. + +The same engine can be used to submit bugs to any number of support +sites by setting up aliases for each of them; `send-pr' error-checks +each PR as it is sent to be sure that the category specified matches a +category supported by the site in question. + +`send-pr' invokes an editor on a problem report template (after trying +to fill in some fields with reasonable default values). When you exit +the editor, `send-pr' sends the completed form to the support site. +At the support site, the PR is assigned a unique number and is stored +in the GNATS database according to its category and customer-id. GNATS +automatically replies with an acknowledgement, citing the category and +the PR number. + +See the Texinfo file `send-pr.texi' or the Info file `send-pr.info' +for detailed installation and usage information. + +See the file MANIFEST for a list of the files which should have +accompanied this distribution. + +See `send-pr.texi', `send-pr.info', or the file INSTALL for the +installation procedure for `send-pr'. + + +Copyright (c) 1993, Free Software Foundation, Inc. +See the file COPYING for copyright information concerning this +distribution and all its components. diff --git a/gnu/usr.bin/send-pr/categories b/gnu/usr.bin/send-pr/categories new file mode 100644 index 0000000..6d6ebff --- /dev/null +++ b/gnu/usr.bin/send-pr/categories @@ -0,0 +1,2 @@ +pending +test diff --git a/gnu/usr.bin/send-pr/install-sid.sh b/gnu/usr.bin/send-pr/install-sid.sh new file mode 100755 index 0000000..f7f24e5 --- /dev/null +++ b/gnu/usr.bin/send-pr/install-sid.sh @@ -0,0 +1,82 @@ +#!/bin/sh +# Drop in the SUBMITTER id into a site's installed send-pr script. +# Copyright (C) 1993 Free Software Foundation, Inc. +# Contributed by Brendan Kehoe (brendan@cygnus.com), based on a +# version written by Heinz G. Seidl (hgs@ide.com). +# +# This file is part of GNU GNATS. +# +# GNU GNATS is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# GNU GNATS is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU GNATS; see the file COPYING. If not, write to +# the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +COMMAND=`echo $0 | sed -e 's,.*/,,g'` +USAGE="Usage: $COMMAND [--install-dir=prefix] [--help] [--version] submitter-id" + +VERSION=3.2 + +BINDIR=@BINDIR@ + +SUBMITTER= +TEMP=/tmp/sp$$ + +if [ $# -eq 0 ]; then + echo "$USAGE" + exit 1 +fi + +while [ $# -gt 0 ]; do + case "$1" in + -install-dir=*|--install-dir=*|--install-di=*|--install-d=*|--install-=*|--install=*|--instal=*|--insta=*|--inst=*|--ins=*|--in=*|--i=*) + I=`echo "$1" | sed 's/-*i[a-z\-]*=//'` + BINDIR=$I/bin ;; + --version) echo $COMMAND version $VERSION ; exit 1 ;; + -*) echo "$USAGE" ; exit 1 ;; + *) SUBMITTER=$1 ;; + esac + shift +done + +path=`echo $0 | sed -e "s;${COMMAND};;"` + +[ -z "$path" ] && path=. + +if [ -f $BINDIR/send-pr ]; then + SPPATH=$BINDIR/send-pr +elif [ -f $path/send-pr ]; then + SPPATH=$path/send-pr +else + echo "$COMMAND: cannot find \`$BINDIR/send-pr' or \`$path/send-pr'" >&2 + exit 1 +fi + +trap 'rm -f $TEMP ; exit 0' 0 +trap 'echo "$COM: Aborting ..."; rm -f $TEMP ; exit 1' 1 2 3 13 15 + +sed -e "s/^SUBMITTER=.*/SUBMITTER=${SUBMITTER}/" $SPPATH > $TEMP + +if grep $SUBMITTER $TEMP > /dev/null; then + cp $SPPATH $SPPATH.orig && + rm -f $SPPATH && + cp $TEMP $SPPATH && + chmod a+rx $SPPATH && + rm -f $TEMP $SPPATH.orig || + { echo "$COMMAND: unable to replace send-pr" >&2 ; exit 1; } +else + echo "$COMMAND: something went wrong when sed-ing the submitter into send-pr" >&2 + exit 1 +fi + +echo "$COMMAND: \`$SUBMITTER' is now the default submitter ID for send-pr" + +exit 0 diff --git a/gnu/usr.bin/send-pr/send-pr-el.in b/gnu/usr.bin/send-pr/send-pr-el.in new file mode 100644 index 0000000..036b4e7 --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr-el.in @@ -0,0 +1,744 @@ +;;;; -*-emacs-lisp-*- +;;;;--------------------------------------------------------------------------- +;;;; EMACS interface for send-pr (by Heinz G. Seidl, hgs@cygnus.com) +;;;; Slightly hacked by Brendan Kehoe (brendan@cygnus.com). +;;;; +;;;; This file is part of the Problem Report Management System (GNATS) +;;;; Copyright 1992, 1993 Cygnus Support +;;;; +;;;; This program is free software; you can redistribute it and/or +;;;; modify it under the terms of the GNU General Public +;;;; License as published by the Free Software Foundation; either +;;;; version 2 of the License, or (at your option) any later version. +;;;; +;;;; This program is distributed in the hope that it will be useful, +;;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +;;;; General Public License for more details. +;;;; +;;;; You should have received a copy of the GNU Library General Public +;;;; License along with this program; if not, write to the Free +;;;; Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +;;;; +;;;;--------------------------------------------------------------------------- +;;;; +;;;; This file contains the EMACS interface to the Problem Report Management +;;;; System (GNATS): +;;;; +;;;; - The `send-pr' command and the `send-pr-mode' for sending +;;;; Problem Reports (PRs). +;;;; +;;;; For more information about how to send a PR see send-pr(1). +;;;; +;;;;--------------------------------------------------------------------------- +;;;; +;;;; Configuration: the symbol `DEFAULT-RELEASE' can be replaced by +;;;; site/release specific strings during the configuration/installation +;;;; process. +;;;; +;;;; Install this file in your EMACS library directory. +;;;; +;;;;--------------------------------------------------------------------------- + +(provide 'send-pr) + +;;;;--------------------------------------------------------------------------- +;;;; Customization: put the following forms into your default.el file +;;;; (or into your .emacs) +;;;;--------------------------------------------------------------------------- + +;(autoload 'send-pr-mode "send-pr" +; "Major mode for sending problem reports." t) + +;(autoload 'send-pr "send-pr" +; "Command to create and send a problem report." t) + +;;;;--------------------------------------------------------------------------- +;;;; End of Customization Section +;;;;--------------------------------------------------------------------------- + +(autoload 'server-buffer-done "server") +(defvar server-buffer-clients nil) +(defvar mail-self-blind nil) +(defvar mail-default-reply-to nil) + +(defconst send-pr::version "3.2") + +(defvar gnats:root "/home/gnats" + "*The top of the tree containing the GNATS database.") + +;;;;--------------------------------------------------------------------------- +;;;; hooks +;;;;--------------------------------------------------------------------------- + +(defvar text-mode-hook nil) ; we define it here in case it's not defined +(defvar send-pr-mode-hook text-mode-hook "Called when send-pr is invoked.") + +;;;;--------------------------------------------------------------------------- +;;;; Domains and default values for (some of) the Problem Report fields; +;;;; constants and definitions. +;;;;--------------------------------------------------------------------------- + +(defconst gnats::emacs-19p + (not (or (and (boundp 'epoch::version) epoch::version) + (string-lessp emacs-version "19"))) + "Is this emacs v19?") + +;;; These may be changed during configuration/installation or by the individual +;;; user in his/her .emacs file. +;;; +(defun gnats::get-config (var) + (let ((shell-file-name "/bin/sh") + (buf (generate-new-buffer " *GNATS config*")) + ret) + (save-excursion + (set-buffer buf) + (shell-command (concat ". " gnats:root "/gnats-adm/config; echo $" var ) + t) + (if (looking-at "/bin/sh:\\|\n") + (setq ret nil) + (setq ret (buffer-substring (point-min) (- (point-max) 1))))) + (kill-buffer buf) + ret)) + +;; const because it must match the script's value +(defconst send-pr:datadir (or (gnats::get-config "DATADIR") "@DATADIR@") + "*Where the `gnats' subdirectory containing category lists lives.") + +(defvar send-pr::sites nil + "List of GNATS support sites; computed at runtime.") +(defvar send-pr:default-site + (or (gnats::get-config "GNATS_SITE") "freefall") + "Default site to send bugs to.") +(defvar send-pr:::site send-pr:default-site + "The site to which a problem report is currently being submitted, or NIL +if using the default site (buffer local).") + +(defvar send-pr:::categories nil + "Buffer local list of available categories, derived at runtime from +send-pr:::site and send-pr::category-alist.") +(defvar send-pr::category-alist nil + "Alist of GNATS support sites and the categories supported at each; computed +at runtime.") + +;;; Ideally we would get all the following values from a central database +;;; during runtime instead of having them here in the code. +;;; +(defconst send-pr::fields + (` (("Category" send-pr::set-categories + (, (or (gnats::get-config "DEFAULT_CATEGORY") nil)) enum) + ("Class" (("sw-bug") ("doc-bug") ("change-request") ("support")) + (, (or (gnats::get-config "DEFAULT_CONFIDENTIAL") 0)) enum) + ("Confidential" (("yes") ("no")) + (, (or (gnats::get-config "DEFAULT_CONFIDENTIAL") 1)) enum) + ("Severity" (("non-critical") ("serious") ("critical")) + (, (or (gnats::get-config "DEFAULT_SEVERITY") 1)) enum) + ("Priority" (("low") ("medium") ("high")) + (, (or (gnats::get-config "DEFAULT_PRIORITY") 1)) enum) + ("Release" nil + (, (or (gnats::get-config "DEFAULT_RELEASE") "@DEFAULT_RELEASE@")) + text) + ("Submitter-Id" nil + (, (or (gnats::get-config "DEFAULT_SUBMITTER") "unknown")) + text) + ("Synopsis" nil nil text + (lambda (a b c) (gnats::set-mail-field "Subject" c))))) + "AList, keyed on the name of the field, of: +1) The field name. +2) The list of completions. This can be a list, a function to call, or nil. +3) The default value. +4) The type of the field. +5) A sub-function to call when changed.") + +(defvar gnats::fields nil) + +(defmacro gnats::push (i l) + (` (setq (, l) (cons (,@ (list i l)))))) + +(defun send-pr::set-categories (&optional arg) + "Get the list of categories for the current site out of +send-pr::category-alist if there or from send-pr if not. With arg, force +update." + ;; + (let ((entry (assoc send-pr:::site send-pr::category-alist))) + (or (and entry (null arg)) + (let ((oldpr (getenv "GNATS_ROOT")) cats) + (send-pr::set-sites arg) + (setenv "GNATS_ROOT" gnats:root) + (setq cats (gnats::get-value-from-shell + "send-pr" "-CL" send-pr:::site)) + (setenv "GNATS_ROOT" oldpr) + (if entry (setcdr entry cats) + (setq entry (cons send-pr:::site cats)) + (gnats::push entry send-pr::category-alist)))) + (setq send-pr:::categories (cdr entry)))) + +(defun send-pr::set-sites (&optional arg) + "Get the list of sites (by listing the contents of DATADIR/gnats) and assign +it to send-pr::sites. With arg, force update." + (or (and (null arg) send-pr::sites) + (progn + (setq send-pr::sites nil) + (mapcar + (function + (lambda (file) + (or (memq t (mapcar (function (lambda (x) (string= x file))) + '("." ".." "pr-edit" "pr-addr"))) + (not (file-readable-p file)) + (gnats::push (list (file-name-nondirectory file)) + send-pr::sites)))) + (directory-files (format "%s/gnats" send-pr:datadir) t)) + (setq send-pr::sites (reverse send-pr::sites))))) + +(defconst send-pr::pr-buffer-name "*send-pr*" + "Name of the temporary buffer, where the problem report gets composed.") + +(defconst send-pr::err-buffer-name "*send-pr-error*" + "Name of the temporary buffer, where send-pr error messages appear.") + +(defvar send-pr:::err-buffer nil + "The error buffer used by the current PR buffer.") + +(defconst gnats::indent 17 "Indent for formatting the value.") + +;;;;--------------------------------------------------------------------------- +;;;; `send-pr' - command for creating and sending of problem reports +;;;;--------------------------------------------------------------------------- + +(fset 'send-pr 'send-pr:send-pr) +(defun send-pr:send-pr (&optional site) + "Create a buffer and read in the result of `send-pr -P'. +When finished with editing the problem report use \\[send-pr:submit-pr] +to send the PR with `send-pr -b -f -'." + ;; + (interactive + (if current-prefix-arg + (list (completing-read "Site: " (send-pr::set-sites 'recheck) nil t + send-pr:default-site)))) + (or site (setq site send-pr:default-site)) + (let ((buf (get-buffer send-pr::pr-buffer-name))) + (if (or (not buf) + (progn (switch-to-buffer buf) + (cond ((or (not (buffer-modified-p buf)) + (y-or-n-p "Erase previous problem report? ")) + (erase-buffer) t) + (t nil)))) + (send-pr::start-up site)))) + +(defun send-pr::start-up (site) + (switch-to-buffer (get-buffer-create send-pr::pr-buffer-name)) + (setq default-directory (expand-file-name "~/")) + (auto-save-mode auto-save-default) + (let ((oldpr (getenv "GNATS_ROOT")) + (case-fold-search nil)) + (setenv "GNATS_ROOT" gnats:root) + (shell-command (concat "send-pr -P " site) t) + (setenv "GNATS_ROOT" oldpr) + (if (looking-at "send-pr:") + (cond ((looking-at "send-pr: .* does not have a categories list") + (setq send-pr::sites nil) + (error "send-pr: the GNATS site %s does not have a categories list" site)) + (t (error (buffer-substring (point-min) (point-max))))) + (save-excursion + ;; Clear cruft inserted by bdamaged .cshrcs + (re-search-forward "^SEND-PR:") + (delete-region 1 (match-beginning 0))))) + (set-buffer-modified-p nil) + (send-pr:send-pr-mode) + (setq send-pr:::site site) + (send-pr::set-categories) + (if (null send-pr:::categories) + (progn + (and send-pr:::err-buffer (kill-buffer send-pr:::err-buffer)) + (kill-buffer nil) + (message "send-pr: no categories found")) + (and mail-default-reply-to + (gnats::set-mail-field "Reply-To" mail-default-reply-to)) + (and mail-self-blind + (gnats::set-mail-field "BCC" (user-login-name))) + (mapcar 'send-pr::maybe-change-field send-pr::fields) + (gnats::position-on-field "Description") + (message (substitute-command-keys + "To send the problem report use: \\[send-pr:submit-pr]")))) + +(fset 'do-send-pr 'send-pr:submit-pr) ;backward compat +(defun send-pr:submit-pr () + "Pipe the contents of the buffer *send-pr* to `send-pr -f -.' unless this +buffer was loaded with emacsclient, in which case save the buffer and exit." + ;; + (interactive) + (cond + ((and (boundp 'server-buffer-clients) + server-buffer-clients) + (let ((buffer (current-buffer)) + (version-control nil) (buffer-backed-up nil)) + (save-buffer buffer) + (kill-buffer buffer) + (server-buffer-done buffer))) + (t + (or (and send-pr:::err-buffer + (buffer-name send-pr:::err-buffer)) + (setq send-pr:::err-buffer + (get-buffer-create send-pr::err-buffer-name))) + (let ((err-buffer send-pr:::err-buffer) mesg ok) + (save-excursion (set-buffer err-buffer) (erase-buffer)) + (message "running send-pr...") + (let ((oldpr (getenv "GNATS_ROOT"))) + (setenv "GNATS_ROOT" gnats:root) + (call-process-region (point-min) (point-max) "send-pr" + nil err-buffer nil send-pr:::site + "-b" "-f" "-") + (setenv "GNATS_ROOT" oldpr)) + (message "running send-pr...done") + ;; stupidly we cannot check the return value in EMACS 18.57, thus we need + ;; this kluge to find out whether send-pr succeeded. + (if (save-excursion + (set-buffer err-buffer) + (goto-char (point-min)) + (setq mesg (buffer-substring (point-min) (- (point-max) 1))) + (search-forward "problem report sent" nil t)) + (progn (message mesg) + (kill-buffer err-buffer) + (delete-auto-save-file-if-necessary) + (set-buffer-modified-p nil) + (bury-buffer)) + (pop-to-buffer err-buffer)) + )))) + +;;;;--------------------------------------------------------------------------- +;;;; send-pr:send-pr-mode mode +;;;;--------------------------------------------------------------------------- + +(defvar send-pr-mode-map + (let ((map (make-sparse-keymap))) + (define-key map "\C-c\C-c" 'send-pr:submit-pr) + (define-key map "\C-c\C-f" 'gnats:change-field) + (define-key map "\M-n" 'gnats:next-field) + (define-key map "\M-p" 'gnats:previous-field) + (define-key map "\C-\M-f" 'gnats:forward-field) + (define-key map "\C-\M-b" 'gnats:backward-field) + map) + "Keymap for send-pr mode.") + +(defconst gnats::keyword "^>\\([-a-zA-Z]+\\):") +(defconst gnats::before-keyword "[ \t\n\f]*[\n\f]+>\\([-a-zA-Z]+\\):") +(defconst gnats::after-keyword "^>\\([-a-zA-Z]+\\):[ \t\n\f]+") + +(fset 'send-pr-mode 'send-pr:send-pr-mode) +(defun send-pr:send-pr-mode () + "Major mode for submitting problem reports. +For information about the form see gnats(1) and send-pr(1). +Special commands: \\{send-pr-mode-map} +Turning on send-pr-mode calls the value of the variable send-pr-mode-hook, +if it is not nil." + (interactive) + (gnats::patch-exec-path) + (put 'send-pr:send-pr-mode 'mode-class 'special) + (kill-all-local-variables) + (setq major-mode 'send-pr:send-pr-mode) + (setq mode-name "send-pr") + (use-local-map send-pr-mode-map) + (set-syntax-table text-mode-syntax-table) + (setq local-abbrev-table text-mode-abbrev-table) + (setq buffer-offer-save t) + (make-local-variable 'send-pr:::site) + (make-local-variable 'send-pr:::categories) + (make-local-variable 'send-pr:::err-buffer) + (make-local-variable 'paragraph-separate) + (setq paragraph-separate (concat (default-value 'paragraph-separate) + "\\|" gnats::keyword "[ \t\n\f]*$")) + (make-local-variable 'paragraph-start) + (setq paragraph-start (concat (default-value 'paragraph-start) + "\\|" gnats::keyword)) + (run-hooks 'send-pr-mode-hook) + t) + +;;;;--------------------------------------------------------------------------- +;;;; Functions to read and replace field values. +;;;;--------------------------------------------------------------------------- + +(defun gnats::position-on-field (field) + (goto-char (point-min)) + (if (not (re-search-forward (concat "^>" field ":") nil t)) + (error "Field `>%s:' not found." field) + (re-search-forward "[ \t\n\f]*") + (if (looking-at gnats::keyword) + (backward-char 1)) + t)) + +(defun gnats::mail-position-on-field (field) + (let (end + (case-fold-search t)) + (goto-char (point-min)) + (re-search-forward "^$") + (setq end (match-beginning 0)) + (goto-char (point-min)) + (if (not (re-search-forward (concat "^" field ":") end 'go-to-end)) + (insert field ": \n") + (re-search-forward "[ \t\n\f]*")) + (skip-chars-backward "\n") + t)) + +(defun gnats::field-contents (field &optional elem move) + (let (pos) + (unwind-protect + (save-excursion + (if (not (gnats::position-on-field field)) + nil + (setq pos (point-marker)) + (if (or (looking-at "<.*>$") (eolp)) + t + (looking-at ".*$") ; to set match-{beginning,end} + (gnats::nth-word + (buffer-substring (match-beginning 0) (match-end 0)) + elem)))) + (and move pos (goto-char pos))))) + +(defun gnats::functionp (thing) + (or (and (symbolp thing) (fboundp thing)) + (and (listp thing) (eq (car thing) 'lambda)))) + +(defun gnats::field-values (field) + "Return the possible (known) values for field FIELD." + (let* ((fields (if (eq major-mode 'gnats:gnats-mode) gnats::fields + send-pr::fields)) + (thing (elt (assoc field fields) 1))) + (cond ((gnats::functionp thing) (funcall thing)) + ((listp thing) thing) + (t (error "ACK"))))) + +(defun gnats::field-default (field) + "Return the default value for field FIELD." + (let* ((fields (if (eq major-mode 'gnats:gnats-mode) gnats::fields + send-pr::fields)) + (thing (elt (assoc field fields) 2))) + (cond ((stringp thing) thing) + ((null thing) "") + ((numberp thing) (car (elt (gnats::field-values field) thing))) + ((gnats::functionp thing) + (funcall thing (gnats::field-contents field))) + ((eq thing t) (gnats::field-contents field)) + (t (error "ACK"))))) + +(defun gnats::field-type (field) + "Return the type of field FIELD." + (let* ((fields (if (eq major-mode 'gnats:gnats-mode) gnats::fields + send-pr::fields)) + (thing (elt (assoc field fields) 3))) + thing)) + +(defun gnats::field-action (field) + "Return the extra handling function for field FIELD." + (let* ((fields (if (eq major-mode 'gnats:gnats-mode) gnats::fields + send-pr::fields)) + (thing (elt (assoc field fields) 4))) + (cond ((null thing) 'ignore) + ((gnats::functionp thing) thing) + (t (error "ACK"))))) + +;;;;--------------------------------------------------------------------------- +;;;; Point movement functions +;;;;--------------------------------------------------------------------------- + +(or (fboundp 'defsubst) (fset 'defsubst 'defun)) + +(defun send-pr::maybe-change-field (field) + (setq field (car field)) + (let ((thing (gnats::field-contents field))) + (and thing (eq t thing) + (not (eq 'multi-text (gnats::field-type field))) + (gnats:change-field field)))) + +(defun gnats:change-field (&optional field default) + "Change the value of the field containing the cursor. With arg, ask the +user for the field to change. From a program, the function takes optional +arguments of the field to change and the default value to use." + (interactive) + (or field current-prefix-arg (setq field (gnats::current-field))) + (or field + (setq field + (completing-read "Field: " + (if (eq major-mode 'gnats:gnats-mode) + gnats::fields + send-pr::fields) + nil t))) + (gnats::position-on-field field) + (sit-for 0) + (let* ((old (gnats::field-contents field)) + new) + (if (null old) + (error "ACK") + (let ((prompt (concat ">" field ": ")) + (domain (gnats::field-values field)) + (type (gnats::field-type field)) + (action (gnats::field-action field))) + (or default (setq default (gnats::field-default field))) + (setq new (if (eq type 'enum) + (completing-read prompt domain nil t + (if gnats::emacs-19p (cons default 0) + default)) + (read-string prompt (if gnats::emacs-19p (cons default 1) + default)))) + (gnats::set-field field new) + (funcall action field old new) + new)))) + +(defun gnats::set-field (field value) + (save-excursion + (gnats::position-on-field field) + (delete-horizontal-space) + (looking-at ".*$") + (replace-match + (concat (make-string (- gnats::indent (length field) 2) ?\40 ) value) t))) + +(defun gnats::set-mail-field (field value) + (save-excursion + (gnats::mail-position-on-field field) + (delete-horizontal-space) + (looking-at ".*$") + (replace-match (concat " " value) t))) + +(defun gnats::before-keyword (&optional where) + "Returns t if point is in some white space before a keyword. +If where is nil, then point is not changed; if where is t then point is moved +to the beginning of the keyword, otherwise it is moved to the beginning +of the white space it was in." + ;; + (if (looking-at gnats::before-keyword) + (prog1 t + (cond ((eq where t) + (re-search-forward "^>") (backward-char)) + ((not (eq where nil)) + (re-search-backward "[^ \t\n\f]") (forward-char)))) + nil)) + +(defun gnats::after-keyword (&optional where) + "Returns t if point is in some white space after a keyword. +If where is nil, then point is not changed; if where is t then point is moved +to the beginning of the keyword, otherwise it is moved to the end of the white +space it was in." + ;; + (if (gnats::looking-after gnats::after-keyword) + (prog1 t + (cond ((eq where t) + (re-search-backward "^>")) + ((not (eq where nil)) + (re-search-forward "[^ \t\n\f]") (backward-char)))) + nil)) + +(defun gnats::in-keyword (&optional where) + "Returns t if point is within a keyword. +If where is nil, then point is not changed; if where is t then point is moved +to the beginning of the keyword." + ;; + (let ((old-point (point-marker))) + (beginning-of-line) + (cond ((and (looking-at gnats::keyword) + (< old-point (match-end 0))) + (prog1 t + (if (eq where t) + t + (goto-char old-point)))) + (t (goto-char old-point) + nil)))) + +(defun gnats::forward-bofield () + "Moves point to the beginning of a field. Assumes that point is in the +keyword." + ;; + (if (re-search-forward "[ \t\n\f]+[^ \t\n\f]" (point-max) '-) + (backward-char) + t)) + +(defun gnats::backward-eofield () + "Moves point to the end of a field. Assumes point is in the keyword." + ;; + (if (re-search-backward "[^ \t\n\f][ \t\n\f]+" (point-min) '-) + (forward-char) + t)) + +(defun gnats::forward-eofield () + "Moves point to the end of a field. Assumes that point is in the field." + ;; + ;; look for the next field + (if (re-search-forward gnats::keyword (point-max) '-) + (progn (beginning-of-line) (gnats::backward-eofield)) + (re-search-backward "[^ \t\n\f][ \t\n\f]*" (point-min) '-) + (forward-char))) + +(defun gnats::backward-bofield () + "Moves point to the beginning of a field. Assumes that point is in the +field." + ;; + ;;look for previous field + (if (re-search-backward gnats::keyword (point-min) '-) + (gnats::forward-bofield) + t)) + + +(defun gnats:forward-field () + "Move point forward to the end of the field or to the beginning of the next +field." + ;; + (interactive) + (if (or (gnats::before-keyword t) (gnats::in-keyword t) + (gnats::after-keyword t)) + (gnats::forward-bofield) + (gnats::forward-eofield))) + +(defun gnats:backward-field () + "Move point backward to the beginning/end of a field." + ;; + (interactive) + (backward-char) + (if (or (gnats::before-keyword t) (gnats::in-keyword t) + (gnats::after-keyword t)) + (gnats::backward-eofield) + (gnats::backward-bofield))) + +(defun gnats:next-field () + "Move point to the beginning of the next field." + ;; + (interactive) + (if (or (gnats::before-keyword t) (gnats::in-keyword t) + (gnats::after-keyword t)) + (gnats::forward-bofield) + (if (re-search-forward gnats::keyword (point-max) '-) + (gnats::forward-bofield) + t))) + +(defun gnats:previous-field () + "Move point to the beginning of the previous field." + ;; + (interactive) + (backward-char) + (if (or (gnats::after-keyword t) (gnats::in-keyword t) + (gnats::before-keyword t)) + (progn (re-search-backward gnats::keyword (point-min) '-) + (gnats::forward-bofield)) + (gnats::backward-bofield))) + +(defun gnats:beginning-of-field () + "Move point to the beginning of the current field." + (interactive) + (cond ((gnats::in-keyword t) + (gnats::forward-bofield)) + ((gnats::after-keyword 0)) + (t + (gnats::backward-bofield)))) + +(defun gnats::current-field () + (save-excursion + (if (cond ((or (gnats::in-keyword t) (gnats::after-keyword t)) + (looking-at gnats::keyword)) + ((re-search-backward gnats::keyword nil t))) + (buffer-substring (match-beginning 1) (match-end 1)) + nil))) + +;;;;--------------------------------------------------------------------------- +;;;; Support functions +;;;;--------------------------------------------------------------------------- + +(defun gnats::looking-after (regex) + "Returns t if point is after regex." + ;; + (let* ((old-point (point)) + (start (if (eobp) + old-point + (forward-char) (point)))) + (cond ((re-search-backward regex (point-min) t) + (goto-char old-point) + (cond ((eq (match-end 0) start) + t)))))) + +(defun gnats::nth-word (string &optional elem) + "Returns the elem-th word of the string. +If elem is nil, then the first wort is returned, if elem is 0 then +the whole string is returned." + ;; + (if (integerp elem) + (cond ((eq elem 0) string) + ((eq elem 1) (gnats::first-word string)) + ((equal string "") "") + ((>= elem 2) + (let ((i 0) (value "")) + (setq string ; strip leading blanks + (substring string (or (string-match "[^ \t]" string) 0))) + (while (< i elem) + (setq value + (substring string 0 + (string-match "[ \t]*$\\|[ \t]+" string))) + (setq string + (substring string (match-end 0))) + (setq i (+ i 1))) + value))) + (gnats::first-word string))) + +(defun gnats::first-word (string) + (setq string + (substring string (or (string-match "[^ \t]" string) 0))) + (substring string 0 (string-match "[ \t]*$\\|[ \t]+" string))) + +;;;;--------------------------------------------------------------------------- + +(defun gnats::patch-exec-path () + ;; + "Replaces `//' by `/' in `exec-path'." + ;; + ;(make-local-variable 'exec-path) + (let ((err-buffer (get-buffer-create " *gnats::patch-exec-path*")) + (ret)) + (setq exec-path (save-excursion (set-buffer err-buffer) + (prin1 exec-path err-buffer) + (goto-char (point-min)) + (replace-string "//" "/") + (goto-char (point-min)) + (setq ret (read err-buffer)) + (kill-buffer err-buffer) + ret + )))) + +(defun gnats::get-value-from-shell (&rest command) + "Execute shell command to get a list of valid values for `variable'." + ;; + (let ((err-buffer (get-buffer-create " *gnats::get-value-from-shell*"))) + (save-excursion + (set-buffer err-buffer) + (unwind-protect + (condition-case var + (progn + (apply 'call-process + (car command) nil err-buffer nil (cdr command)) + (goto-char (point-min)) + (if (looking-at "[-a-z]+: ") + (error (buffer-substring (point-min) (point-max)))) + (read err-buffer)) + (error nil)) + (kill-buffer err-buffer))))) + +(or (fboundp 'setenv) + (defun setenv (variable &optional value) + "Set the value of the environment variable named VARIABLE to VALUE. +VARIABLE should be a string. VALUE is optional; if not provided or is +`nil', the environment variable VARIABLE will be removed. +This function works by modifying `process-environment'." + (interactive "sSet environment variable: \nsSet %s to value: ") + (if (string-match "=" variable) + (error "Environment variable name `%s' contains `='" variable) + (let ((pattern (concat "\\`" (regexp-quote (concat variable "=")))) + (case-fold-search nil) + (scan process-environment)) + (while scan + (cond + ((string-match pattern (car scan)) + (if (eq nil value) + (setq process-environment (delq (car scan) + process-environment)) + (setcar scan (concat variable "=" value))) + (setq scan nil)) + ((null (setq scan (cdr scan))) + (setq process-environment + (cons (concat variable "=" value) + process-environment))))))))) + +;;;; end of send-pr.el diff --git a/gnu/usr.bin/send-pr/send-pr.1 b/gnu/usr.bin/send-pr/send-pr.1 new file mode 100644 index 0000000..3717ebd --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr.1 @@ -0,0 +1,269 @@ +.\" -*- nroff -*- +.\" --------------------------------------------------------------------------- +.\" man page for send-pr (by Heinz G. Seidl, hgs@cygnus.com) +.\" updated Feb 1993 for GNATS 3.00 by Jeffrey Osier, jeffrey@cygnus.com +.\" +.\" This file is part of the Problem Report Management System (GNATS) +.\" Copyright 1992 Cygnus Support +.\" +.\" This program is free software; you can redistribute it and/or +.\" modify it under the terms of the GNU General Public +.\" License as published by the Free Software Foundation; either +.\" version 2 of the License, or (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +.\" General Public License for more details. +.\" +.\" You should have received a copy of the GNU Library General Public +.\" License along with this program; if not, write to the Free +.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA +.\" +.\" --------------------------------------------------------------------------- +.nh +.TH SEND-PR 1 xVERSIONx "February 1993" +.SH NAME +send-pr \- send problem report (PR) to a central support site +.SH SYNOPSIS +.B send-pr +[ +.I site +] +[ +.B \-f +.I problem-report +] +[ +.B \-t +.I mail-address +] +.br +.in +0.8i +[ +.B \-P +] +[ +.B \-L +] +[ +.B \-\-request-id +] +[ +.B \-v +] +.SH DESCRIPTION +.B send-pr +is a tool used to submit +.I problem reports +.\" SITE ADMINISTRATORS - change this if you use a local default +(PRs) to a central support site. In most cases the correct +.I site +will be the default. This argument indicates the support site which +is responsible for the category of problem involved. Some sites may +use a local address as a default. +.I site +values are defined by using the +.BR aliases (5). +.LP +.B send-pr +invokes an editor on a problem report template (after trying to fill +in some fields with reasonable default values). When you exit the +editor, +.B send-pr +sends the completed form to the +.I Problem Report Management System +(\fBGNATS\fR) at a central support site. At the support site, the PR +is assigned a unique number and is stored in the \fBGNATS\fR database +according to its category and submitter-id. \fBGNATS\fR automatically +replies with an acknowledgement, citing the category and the PR +number. +.LP +To ensure that a PR is handled promptly, it should contain your (unique) +\fIsubmitter-id\fR and one of the available \fIcategories\fR to identify the +problem area. (Use +.B `send-pr -L' +to see a list of categories.) +.LP +The +.B send-pr +template at your site should already be customized with your +submitter-id (running `\|\fBinstall-sid\fP \fIsubmitter-id\fP\|' to +accomplish this is part of the installation procedures for +.BR send-pr ). +If this hasn't been done, see your system administrator for your +submitter-id, or request one from your support site by invoking +.B `send-pr \-\-request\-id'. +If your site does not distinguish between different user sites, or if +you are not affiliated with the support site, use +.B `net' +for this field. +.LP +The more precise your problem description and the more complete your +information, the faster your support team can solve your problems. +.SH OPTIONS +.TP +.BI \-f " problem-report" +specify a file (\fIproblem-report\fR) which already contains a +complete problem report. +.B send-pr +sends the contents of the file without invoking the editor. If +the value for +.I problem-report +is +.BR `\|\-\|' , +then +.B send-pr +reads from standard input. +.TP +.BI \-t " mail-address" +Change mail address at the support site for problem reports. The +default +.I mail-address +is the address used for the default +.IR site . +Use the +.I site +argument rather than this option in nearly all cases. +.TP +.B \-P +print the form specified by the environment variable +.B PR_FORM +on standard output. If +.B PR_FORM +is not set, print the standard blank PR template. No mail is sent. +.TP +.B -L +print the list of available categories. No mail is sent. +.TP +.B \-\-request\-id +sends mail to the default support site, or +.I site +if specified, with a request for your +.IR submitter-id . +If you are +not affiliated with +.IR site , +use a +.I submitter-id +of +.BR net \|'. +.TP +.B \-v +Display the +.B send-pr +version number. +.LP +Note: use +.B send-pr +to submit problem reports rather than mailing them directly. Using +both the template and +.B send-pr +itself will help ensure all necessary information will reach the +support site. +.SH ENVIRONMENT +The environment variable +.B EDITOR +specifies the editor to invoke on the template. +.br +default: +.B vi +.sp +If the environment variable +.B PR_FORM +is set, then its value is used as the file name of the template for +your problem-report editing session. You can use this to start with a +partially completed form (for example, a form with the identification +fields already completed). +.SH "HOW TO FILL OUT A PROBLEM REPORT" +Problem reports have to be in a particular form so that a program can +easily manage them. Please remember the following guidelines: +.IP \(bu 3m +describe only +.B one problem +with each problem report. +.IP \(bu 3m +For follow-up mail, use the same subject line as the one in the automatic +acknowledgent. It consists of category, PR number and the original synopsis +line. This allows the support site to relate several mail messages to a +particular PR and to record them automatically. +.IP \(bu 3m +Please try to be as accurate as possible in the subject and/or synopsis line. +.IP \(bu 3m +The subject and the synopsis line are not confidential. This is +because open-bugs lists are compiled from them. Avoid confidential +information there. +.LP +See the GNU +.B Info +file +.B send-pr.info +or the document \fIReporting Problems With send-pr\fR\ for detailed +information on reporting problems +.SH "HOW TO SUBMIT TEST CASES, CODE, ETC." +Submit small code samples with the PR. Contact the support site for +instructions on submitting larger test cases and problematic source +code. +.SH FILES +.ta \w'/tmp/pbad$$ 'u +/tmp/p$$ copy of PR used in editing session +.br +/tmp/pf$$ copy of empty PR form, for testing purposes +.br +/tmp/pbad$$ file for rejected PRs +.SH EMACS USER INTERFACE +An Emacs user interface for +.B send-pr +with completion of field values is part of the +.B send-pr +distribution (invoked with +.BR "M-x send-pr" ). +See the file +.B send-pr.info +or the ASCII file +.B INSTALL +in the top level directory of the distribution for configuration and +installation information. The Emacs LISP template file is +.B send-pr-el.in +and is installed as +.BR send-pr.el . +.SH INSTALLATION AND CONFIGURATION +See +.B send-pr.info +or +.B INSTALL +for installation instructions. +.SH SEE ALSO +.I Reporting Problems Using send-pr +(also installed as the GNU Info file +.BR send-pr.info ). +.LP +.BR gnats (l), +.BR query-pr (1), +.BR edit-pr (1), +.BR gnats (8), +.BR queue-pr (8), +.BR at-pr (8), +.BR mkcat (8), +.BR mkdist (8). +.SH AUTHORS +Jeffrey Osier, Brendan Kehoe, Jason Merrill, Heinz G. Seidl (Cygnus +Support) +.SH COPYING +Copyright (c) 1992, 1993 Free Software Foundation, Inc. +.PP +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. +.PP +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. +.PP +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be included in +translations approved by the Free Software Foundation instead of in +the original English. + diff --git a/gnu/usr.bin/send-pr/send-pr.info b/gnu/usr.bin/send-pr/send-pr.info new file mode 100644 index 0000000..4e98715 --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr.info @@ -0,0 +1,1604 @@ +This is Info file send-pr.info, produced by Makeinfo-1.55 from the +input file ./send-pr.texi. + +START-INFO-DIR-ENTRY +* send-pr:: Reporting problems--using send-pr +END-INFO-DIR-ENTRY + + Copyright (C) 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. + + +File: send-pr.info, Node: Top, Next: send-pr in detail, Prev: (DIR), Up: (DIR) + +Overview +******** + + This manual documents `send-pr', version 3.2, which uses electronic +mail to submit support questions and problem reports to a central +Support Site. No body of work is perfect, and support organizations +understand this; `send-pr' is designed to allow users who have problems +to submit reports of these problems to sites responsible for supporting +the products in question, in a defined form which can be read by an +electronically managed database. + + `send-pr' is part of a suite of programs known collectively as +GNATS, the GNU Problem Report Management System. GNATS consists of +several programs which, used in concert, formulate and partially +administer a database of "Problem Reports", or "PRs", at a central +Support Site. A PR goes through several states in its lifetime; GNATS +tracks the PR and all information associated with it through each state +and finally acts as an archive for PRs which have been "closed". + + Because `send-pr' exists as a shell (`/bin/sh') script and as an +Elisp file for use with GNU Emacs, it can be used from any machine on +your network which can run a shell script and/or Emacs. + + In general, you can use any editor and mailer to submit valid Problem +Reports, as long as the format required by GNATS is preserved. +`send-pr' automates the process, however, and ensures that certain +fields necessary for automatic processing are present. `send-pr' is +strongly recommended for all initial problem-oriented correspondence +with your Support Site. The organization you submit Problem Reports to +supplies an address to which further information can be sent; the person +responsible for the category of the problem you report contacts you +directly. + +* Menu: + +* send-pr in detail:: Details about send-pr and GNATS +* Invoking send-pr:: Editing and sending PRs +* An Example:: A working example +* Installing send-pr:: Installing send-pr on your system +* Index:: + + +File: send-pr.info, Node: send-pr in detail, Next: Invoking send-pr, Prev: Top, Up: Top + +Details about send-pr and GNATS +******************************* + + A "Problem Report" is a message that describes a problem you are +having with a body of work. `send-pr' organizes this message into a +form which can be understood and automatically processed by GNATS, the +GNU Problem Report Management System. A Problem Report is organized +into "fields" which contain data describing you, your organization, and +the problem you are announcing (*note Problem Report format: Fields.). +Problem Reports go through several defined states in their lifetimes, +from "open" to "closed" (*note States of Problem Reports: States.). + +* Menu: + +* States:: States of Problem Reports +* Fields:: Problem Report format + + +File: send-pr.info, Node: States, Next: Fields, Up: send-pr in detail + +States of Problem Reports +========================= + + Each PR goes through a defined series of states between origination +and closure. The originator of a PR receives notification +automatically of any state changes. + +"open" + The initial state of a Problem Report. This means the PR has been + filed and the responsible person(s) notified. + +"analyzed" + The responsible person has analyzed the problem. 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. + +"feedback" + 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 acknowledges that the solution works. + +"closed" + A Problem Report is closed ("the bug stops here") only when any + changes have been integrated, documented, and tested, and the + submitter has confirmed the solution. + +"suspended" + 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. + + +File: send-pr.info, Node: Fields, Prev: States, Up: send-pr in detail + +Problem Report format +===================== + + The format of a PR is designed to reflect the nature of GNATS as a +database. Information is arranged into "fields", and kept in +individual records (Problem Reports). + + Problem Report fields are denoted by a keyword which begins with `>' +and ends with `:', as in `>Confidential:'. Fields belong to one of +three data types: + +ENUMERATED + One of a specific set of values, which vary according to the + field. The value for each keyword must be on the same line as the + keyword. These values are not configurable (yet). + + For each ENUMERATED keyword, the possible choices are listed in the + `send-pr' template as a comment. The following fields are + ENUMERATED format; see the descriptions of fields below for + explanations of each field in detail: + + >Confidential: >Severity: >Priority: + >Class: >State: >Number: + +TEXT + One single line of text which must begin and end on the same line + (i.e., before a newline) as the keyword. See the descriptions of + fields below for explanations of each field in detail. The + following fields are TEXT format: + + >Submitter-Id: >Originator: >Synopsis: + >Category: >Release: >Responsible: + >Arrival-Date: + +MULTITEXT + Text of any length may occur in this field. MULTITEXT may span + multiple lines and may also include blank lines. A MULTITEXT field + ends only when another keyword appears. See the descriptions of + fields below for explanations of each field in detail. + + The following fields are MULTITEXT format: + + >Organization: >Environment: >Description: + >How-To-Repeat: >Fix: >Audit-Trail: + >Unformatted: + + A Problem Report contains two different types of fields: "Mail +Header" fields, which are used by the mail handler for delivery, and +"Problem Report" fields, which contain information relevant to the +Problem Report and its submitter. A Problem Report is essentially a +specially formatted electronic mail message. + + The following is an example Problem Report. Mail headers are at the +top, followed by GNATS fields, which begin with `>' and end with `:'. +The `Subject:' line in the mail header and the `>Synopsis:' field are +usually duplicates of each other. + + Message-Id: MESSAGE-ID + Date: DATE + From: ADDRESS + Reply-To: ADDRESS + To: BUG-ADDRESS + Subject: SUBJECT + + >Number: GNATS-ID + >Category: CATEGORY + >Synopsis: SYNOPSIS + >Confidential: yes *or* no + >Severity: critical, serious, *or* non-critical + >Priority: high, medium *or* low + >Responsible: RESPONSIBLE + >State: open, analyzed, suspended, feedback, *or* closed + >Class: sw-bug, doc-bug, change-request, support, + *or* duplicate + >Submitter-Id: SUBMITTER-ID + >Arrival-Date: DATE + >Originator: NAME + >Organization: ORGANIZATION + >Release: RELEASE + >Environment: + ENVIRONMENT + >Description: + DESCRIPTION + >How-To-Repeat: + HOW-TO-REPEAT + >Fix: + FIX + >Audit-Trail: + APPENDED-MESSAGES... + State-Changed-From-To: FROM-TO + State-Changed-When: DATE + State-Changed-Why: + REASON + Responsible-Changed-From-To: FROM-TO + Responsible-Changed-When: DATE + Responsible-Changed-Why: + REASON + >Unformatted: + MISCELLANEOUS + +* Menu: + +* Mail header fields:: +* Problem Report fields:: + + +File: send-pr.info, Node: Mail header fields, Next: Problem Report fields, Up: Fields + +Mail header fields +------------------ + + 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 by `send-pr': + +`To:' + The preconfigured mail address for the Support Site where the PR + is to be sent, automatically supplied by `send-pr'. + +`Subject:' + A terse description of the problem. This field normally contains + the same information as the `>Synopsis:' field. + +`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, the same address as the `From:' field. + + +File: send-pr.info, Node: Problem Report fields, Prev: Mail header fields, Up: Fields + +Problem Report fields +--------------------- + +Field descriptions +------------------ + + 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:' + (TEXT) 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:' + (TEXT) Originator's real name. The default is the value of the + originator's environment variable `NAME'. + +`>Organization:' + (MULTITEXT) The originator's organization. The default value is + set with the variable `DEFAULT_ORGANIZATION' in the `send-pr' + shell script. + +`>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 provided are not made publicly available (e.g., in + regression test suites). The default value is `yes'. + +`>Synopsis:' + (TEXT) One-line summary of the problem. `send-pr' copies this + information to the `Subject:' line when you submit a Problem + Report. + +`>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 behavior, 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. + + `low' + The problem should be solved in a future release. + + The default value is `medium'. + +`>Category:' + (TEXT) The name of the product, component or concept where the + problem lies. The values for this field are defined by the Support + Site. + +`>Class:' + (ENUMERATED) The class of a problem can be one of the following: + + `sw-bug' + A general product problem. (`sw' stands for "software".) + + `doc-bug' + A problem with the documentation. + + `change-request' + A request for a change in behavior, etc. + + `support' + A support problem or question. + + `duplicate (PR-NUMBER)' + Duplicate PR. PR-NUMBER should be the number of the original + PR. + + The default is `sw-bug'. + +`>Release:' + (TEXT) Release or version number of the product, component or + concept. + +`>Environment:' + (MULTITEXT) Description of the environment where the problem + occured: machine architecture, operating system, host and target + types, libraries, pathnames, etc. + +`>Description:' + (MULTITEXT) Precise description of the problem. + +`>How-To-Repeat:' + (MULTITEXT) Example code, input, or activities to reproduce the + problem. The support organization uses example code both to + reproduce the problem and to test whether the problem is fixed. + Include all preconditions, inputs, outputs, conditions after the + problem, and symptoms. Any additional important information + should be included. Include all the details that would be + necessary for someone else to recreate the problem reported, + however obvious. Sometimes seemingly arbitrary or obvious + information can point the way toward a solution. See also *Note + Helpful hints: Helpful hints. + +`>Fix:' + (MULTITEXT) A description of a solution to the problem, or a patch + which solves the problem. (This field is most often filled in at + the Support Site; we provide it to the submitter in case she has + solved the problem.) + +GNATS adds the following fields when the PR arrives at the Support Site: + +`>Number:' + (ENUMERATED) The incremental identification number for this PR. + + The `>Number:' field is often paired with the `>Category:' field as + + CATEGORY/NUMBER + + in subsequent email messages. This is for historical reasons, as + well as because Problem Reports are stored in subdirectories which + are named by category. + +`>State:' + (ENUMERATED) The current state of the PR. Accepted values are: + + `open' + The PR has been filed and the responsible person notified. + + `analyzed' + The responsible person has analyzed the problem. + + `feedback' + The problem has been solved, and the originator has been + given a patch or other fix. + + `closed' + The changes have been integrated, documented, and tested, and + the originator has confirmed that the solution works. + + `suspended' + Work on the problem has been postponed. + + The initial state of a PR is `open'. *Note States of Problem + Reports: States. + +`>Responsible:' + (TEXT) The person responsible for this category. + +`>Arrival-Date:' + (TEXT) The time that this PR was received by GNATS. The date is + provided automatically by GNATS. + +`>Audit-Trail:' + (MULTITEXT) Tracks related electronic mail as well as changes in + the `>State:' and `>Responsible:' fields with the sub-fields: + + `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE' + The old and new `>State:' field values. + + `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP' + The old and new `>Responsible:' field values. + + `State-Changed-By: NAME' + `Responsible-Changed-By: NAME' + The name of the maintainer who effected the change. + + `State-Changed-When: TIMESTAMP' + `Responsible-Changed-When: TIMESTAMP' + The time the change was made. + + `State-Changed-Why: REASON...' + `Responsible-Changed-Why: REASON...' + The reason for the change. + + The `>Audit-Trail:' field also contains any mail messages received + by GNATS related to this PR, in the order received. + +`>Unformatted:' + (MULTITEXT) Any random text found outside the fields in the + original Problem Report. + + +File: send-pr.info, Node: Invoking send-pr, Next: An Example, Prev: send-pr in detail, Up: Top + +Editing and sending PRs +*********************** + + You can invoke `send-pr' from a shell prompt or from within GNU +Emacs using `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:: + + +File: send-pr.info, Node: using send-pr, Next: send-pr in Emacs, Up: Invoking send-pr + +Creating new Problem Reports +============================ + + Invoking `send-pr' presents a PR "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. + + A template consists of three sections: + +"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 + `>Category:' field. These comments are all preceded by the string + `SEND-PR:' and are erased automatically when the PR is submitted. + The instructional comments within `<' and `>' 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.) + +"Mail Header" + `send-pr' creates a standard mail header. `send-pr' completes all + fields except the `Subject:' line with default values. (*Note + Problem Report format: Fields.) + +"GNATS fields" + These are the informational fields that GNATS uses to route your + Problem Report to the responsible party for further action. They + should be filled out as completely as possible. (*Note Problem + Report format: Fields. Also see *Note Helpful hints: Helpful + hints.) + +For examples of a Problem Report template and complete Problem Report, +see *Note An Example::. + + The default template contains your preconfigured `>Submitter-Id:'. +`send-pr' attempts to determine values for the `>Originator:' and +`>Organization:' fields (*note Problem Report format: Fields.). +`send-pr' also attempts to find out some information about your system +and architecture, and places this information in the `>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 +`send-pr'. Each `site' has its own list of categories for which it +accepts Problem Reports. (*Note Setting a default SITE: default site.) + + `send-pr' also provides the mail header section of the template with +default values in the `To:', `From:', and `Reply-To:' fields. The +`Subject:' field is empty. + + The template begins with a comment section: + + 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: + +and also contains a list of valid `>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 `>Category:' field. A +complete sample bug report, from template to completed PR, is shown in +*Note An Example::. For a complete list of valid categories, type +`send-pr -L' at your prompt. *Note Valid Categories: Valid Categories, +for a sample list of categories, . + + The mail header is just below the comment section. Fill out the +`Subject:' field, if it is not already completed using the value of +`>Synopsis:'. The other mail header fields contain default values. + + To: SUPPORT-SITE + Subject: *complete this field* + From: YOUR-LOGIN@YOUR-SITE + Reply-To: YOUR-LOGIN@YOUR-SITE + X-send-pr-version: send-pr 3.2 + +where SUPPORT-SITE is an alias for the Support Site you wish to submit +this PR to. + + The rest of the template contains GNATS fields. Each field is +either automatically completed with valid information (such as your +`>Submitter-Id:') or contains a one-line instruction specifying the +information that field requires in order to be correct. For example, +the `>Confidential:' field expects a value of `yes' or `no', and the +answer must fit on one line; similarly, the `>Synopsis:' field expects +a short synopsis of the problem, which must also fit on one line. Fill +out the fields as completely as possible. *Note Helpful hints: Helpful +hints, for suggestions as to what kinds of information to include. + + In this example, words in *italics* are filled in with +pre-configured information: + + >Submitter-Id: *your submitter-id* + >Originator: *your name here* + >Organization: + *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 or tag (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)> + + When you finish editing the Problem Report, `send-pr' mails it to +the address named in the `To:' field in the mail header. `send-pr' +checks that the complete form contains a valid `>Category:'. + + Your copy of `send-pr' should have already been customized on +installation to reflect your `>Submitter-Id:'. (*Note Installing +`send-pr' on your system: Installing send-pr.) If you don't know your +`>Submitter-Id:', you can request it using `send-pr --request-id'. If +your organization is not affiliated with the site you send Problem +Reports to, a good generic `>Submitter-Id:' to use is `net'. + + If your PR has an invalid value in one of the ENUMERATED fields +(*note Problem Report format: Fields.), `send-pr' places the PR in a +temporary file named `/tmp/pbadNNNN' on your machine. NNNN is the +process identification number given to your current `send-pr' session. +If you are running `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 `send-pr' from Emacs, the Problem Report is placed +in the buffer `*send-pr-error*'; you can edit this file and then submit +it with + + M-x gnats-submit-pr + + Any further mail concerning this Problem Report should be +carbon-copied to the GNATS mailing address as well, with the category +and identification number in the `Subject:' line of the message. + + Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT + +Messages which arrive with `Subject:' lines of this form are +automatically appended to the Problem Report in the `>Audit-Trail:' +field in the order received. + + +File: send-pr.info, Node: send-pr in Emacs, Next: send-pr from the shell, Prev: using send-pr, Up: Invoking send-pr + +Using `send-pr' from within Emacs +================================= + + You can use an interactive `send-pr' interface from within GNU Emacs +to fill out your Problem Report. We recommend that you familiarize +yourself with Emacs before using this feature (*note Introduction: +(emacs)Introduction.). + + Call `send-pr' with `M-x send-pr'.(1) `send-pr' responds with a +Problem Report template preconfigured for the Support Site from which +you received `send-pr'. (If you use `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 `send-pr' with + + C-u M-x send-pr + + `send-pr' prompts you for the name of a SITE. SITE is an alias on +your local machine which points to an alternate Support Site. + + `send-pr' displays the template and prompts you in the minibuffer +with the line: + >Category: other + +Delete the default value `other' *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 GNU C compiler, +and your support organization accepts bugs submitted for this program +under the category `gcc', delete `other' and then type `gcc[RET]'. +`send-pr' replaces the line + + >Category: <name of the product (one line)> + +in the template with + + >Category: gcc + +and moves on to another field. + + `send-pr' provides name completion in the minibuffer. For instance, +you can also type `gc[TAB]', and `send-pr' attempts to complete the +entry for you. Typing `g[TAB]' may not have the same effect if several +possible entries begin with `g'. In that case `send-pr' cannot +complete the entry because it cannot determine whether you mean `gcc' +or, for example, `gdb', if both of those are possible categories. +`send-pr' continues to prompt you for a valid entry until you enter one. + + `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, `send-pr' responds +with `[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. + + `send-pr' prompts you for the following fields: + + >Category: + >Confidential: (*default*: no) + >Severity: (*default*: serious) + >Priority: (*default*: medium) + >Class: (*default*: sw-bug) + >Release: + >Synopsis: (*this value is copied to `Subject:'*) + +After you complete these fields, `send-pr' places the cursor in the +`>Description:' field and displays the message + + To send the problem report use: C-c C-c + +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. *Note An Example::, for a sample Problem Report. + + `send-pr' provides a few key bindings to make moving around in a +template buffer more simple: + +`C-c C-f' +`M-x change-field' + Changes the field under the cursor. `edit-pr' prompts you for a + new value. + +`M-C-b' +`M-x gnats-backward-field' + Moves the cursor to the beginning of the value of the current + field. + +`M-C-f' +`M-x gnats-forward-field' + Moves the cursor to the end of the value of the current field. + +`M-p' +`M-x gnats-previous-field' + Moves the cursor back one field to the beginning of the value of + the previous field. + +`M-n' +`M-x gnats-next-field' + Moves the cursor forward one field to the beginning of the value + of the next field. + + `send-pr' takes over again when you type `C-c C-c' to send the +message. `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 *Note Introduction: +(emacs)Introduction. + + ---------- Footnotes ---------- + + (1) If typing `M-x send-pr' doesn't work, see your system +administrator for help loading `send-pr' into Emacs. + + +File: send-pr.info, Node: send-pr from the shell, Next: Helpful hints, Prev: send-pr in Emacs, Up: Invoking send-pr + +Invoking `send-pr' from the shell +================================= + + send-pr [ SITE ] + [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ] + [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ] + [ --request-id ] + [ -L | --list ] [ -P | --print ] + [ -V | --version] [ -h | --help ] + + 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 +SITE is usually the site which you received `send-pr' from, or your +local site if you use GNATS locally. (*Note Setting a default SITE: +default site.) + + Invoking `send-pr' with no options calls the editor named in your +environment variable `EDITOR' on a default PR template. If the +environment variable `PR_FORM' is set, its value is used as a file name +which contains a valid template. If `PR_FORM' points to a missing or +unreadable file, or if the file is empty, `send-pr' generates an error +message and opens the editor on a default template. + +`-f PROBLEM-REPORT' +`--file PROBLEM-REPORT' + Specifies a file, PROBLEM-REPORT, where a completed Problem Report + already exists. `send-pr' sends the contents of the file without + invoking an editor. If PROBLEM-REPORT is `-', `send-pr' reads + from standard input. + +`-t MAIL-ADDRESS' +`--to MAIL-ADDRESS' + Sends the PR to MAIL-ADDRESS. The default is preset when `send-pr' + is configured. *This option is not recommended*; instead, use the + argument SITE on the command line. + +`--request-id' + Sends a request for a `>Submitter-Id:' to the Support Site. + +`-L' +`--list' + Prints the list of valid `>Category:' values on standard output. + No mail is sent. + +`-P' +`--print' + Displays the PR template. If the variable `PR_FORM' is set in your + environment, the file it specifies is printed. If `PR_FORM' is not + set, `send-pr' prints the standard blank form. If the file + specified by `PR_FORM' doesn't exist, `send-pr' displays an error + message. No mail is sent. + +`-V' +`--version' + Displays the `send-pr' version number and a usage summary. No mail + is sent. + +`-h' +`--help' + Displays a usage summary for `send-pr'. No mail is sent. + + +File: send-pr.info, Node: Helpful hints, Prev: send-pr from the shell, Up: Invoking send-pr + +Helpful hints +============= + + There is no orthodox standard for submitting effective bug reports, +though you might do well to consult the section on submitting bugs for +GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, 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. + * Include anything *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). + + * 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...") but be sure to include anything relevant. + + * Richard Stallman writes, "The fundamental principle of reporting + bugs usefully is this: *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.). + + * Submit only *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. + + * 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. + + * 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. + + +File: send-pr.info, Node: An Example, Next: Installing send-pr, Prev: Invoking send-pr, Up: Top + +An Example +********** + + Cygnus Support in Mountain View, CA, uses GNATS and `send-pr' +extensively for their support activities. As a support company, Cygnus +finds problem tracking to be a crucial part of everyday business. +Cygnus supports the GNU compiling tools (including GNATS and `send-pr') +over several many platforms + + With each shipment of the Cygnus Support Developer's Kit, customers +receive the latest version of `send-pr', which contains an up-to-date +listing of valid categories (values for the `>Category:' field). Using +these tools, Cygnus' customers can communicate their problems to Cygnus +effectively and receive automatic confirmation of receipt as well as +notification of changes in the status of their reported problems. Much +of Cygnus' support mechanism relies on electronic mail. + + As an example, let's pretend we're a customer of Cygnus Support, and +that we're having a problem compiling some of our software using the +GNU C compiler, which Cygnus supports. + + Assume that we're getting an error in our `bifrabulator' program +wherein the `prestidigitation' routines don't match with the +`whatsitsname'. We've made sure we're following the rules of the +program and checked the Release Notes from Cygnus and found that the bug +isn't already known. In other words, we're pretty sure we've found a +bug. + + Our first step is to call `send-pr'. It really doesn't matter +whether we use `send-pr' from the shell or from within Emacs. Indeed, +if we use Emacs as a primary editor, calling `send-pr' from the shell +is likely to start `send-pr' in an Emacs buffer anyway. So, since our +company, *Imaginary Software, Ltd.*, uses GNU software extensively, +we're pretty familiar with Emacs, so from within Emacs we type + M-x send-pr + +and we're greeted with the following screen: + + SEND-PR: -*- text -*- + 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: Please consult the manual if you are not sure + SEND-PR: how to fill out a problem report. + SEND-PR: + SEND-PR: Choose from the following categories: + SEND-PR: + SEND-PR: bfd binutils bison + SEND-PR: byacc clib config cvs diff + SEND-PR: doc emacs flex g++ gas + SEND-PR: gcc gdb glob gprof grep + SEND-PR: info ispell kerberos ld libg++ + SEND-PR: libiberty make makeinfo mas newlib + SEND-PR: other patch rcs readline send-pr + SEND-PR: test texindex texinfo texinfo.tex + SEND-PR: bifrabulator <---*note: this one is fake* + SEND-PR: + To: cygnus-bugs@cygnus.com + Subject: + From: jeffrey@imaginary.com + Reply-To: jeffrey@imaginary.com + X-send-pr-version: send-pr 3.2 + + >Submitter-Id: imaginary + >Originator: Jeffrey Osier + >Organization: + Imaginary Software, Ltd. + >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](oneline)> + >Release: <release number or tag (one line)> + >Environment: + <machine, os, target, libraries (multiple lines)> + System: SunOS imaginary.com 4.1.1 1 sun4 + Architecture: sun4 + + >Description: + <precise description of the problem (multiple lines)> + >How-To-Repeat: + <code/input/activities to reproduce (multiple lines)> + >Fix: + -----Emacs: *send-pr* (send-pr Fill)----All------------------ + >Category: other[] + + We know from past experience that we need to set certain information +into each field, so we compile all the information we know about our +problem. We have some sample code which we know should work, even +though it doesn't, so we'll include that. Below is the completed PR; +we send this using `C-c C-c'. (The comments have been truncated). + + SEND-PR: Lines starting with `SEND-PR' will be removed + SEND-PR: automatically as well as all comments (the text + SEND-PR: ... + SEND-PR: + To: cygnus-bugs@cygnus.com + Subject: bifrabulator routines don't match + From: jeffrey@imaginary.com + Reply-To: jeffrey@imaginary.com + X-send-pr-version: send-pr 3.2 + + >Submitter-Id: imaginary + >Originator: Jeffrey Osier + >Organization: + Imaginary Software, Ltd. + >Confidential: no + >Synopsis: bifrabulator routines don't match + >Severity: serious + >Priority: medium + >Category: bifrabulator + >Class: sw-bug + >Release: progressive-930101 + >Environment: + System: SunOS imaginary.com 4.1.1 1 sun4 + Architecture: sun4 (SPARC) + + >Description: + the following code I fed into the bifrabulator came back + with a strange error. apparently, the prestidigitation + routine doesn't match with the whatsitsname in all cases. + + >How-To-Repeat: + call the bifrabulator on the following code. + *code sample...* + + >Fix: + -----Emacs: *send-pr* (send-pr Fill)----All------------------ + To send the problem report use: C-c C-c + + We type `C-c C-c', and off it goes. Now, we depend on Cygnus +Support to figure out the answer to our problem. + + Soon afterward, we get the following message from Cygnus: + + From: gnats (GNATS management) + Sender: gnats-admin + Reply-To: hacker@cygnus.com + To: jeffrey@imaginary.com + Subject: Re: bifrabulator/1425: routines don't match + + Thank you very much for your problem report. + It has the internal identification: g++/1425. + The individual assigned to look at your bug is: hacker + (F.B. Hacker) + + Category: bifrabulator + Responsible: hacker + Synopsis: bifrabulator routines don't match + Arrival-Date: Sat Feb 30 03:12:55 1993 + +This is our receipt that the bug has been accepted and forwarded to the +responsible party. + +A while later, we get the analysis: + + To: jeffrey@imaginary.com + From: hacker@cygnus.com + Subject: Re: bifrabulator/1425: routines don't match + Reply-To: hacker@cygnus.com + + Got your message, Jeff. It seems that the bifrabulator was + confusing the prestidigitation routines with the realitychecker + when lexically parsing the whatsitsname. + + I'm working on robustisizing the bifrabulator now. + + How about lunch next week? + -- + F.B. Hacker + Cygnus Support, Mountain View, CA 415 903 1400 + #include <std-disclaimer.h> + +About the same time, we get another message from Cygnus. + + From: hacker@cygnus.com + To: jeffrey@imaginary.com + Subject: Re: bifrabulator/1425: doesn't match prestidig + Reply-To: hacker@cygnus.com + + + `F.B. Hacker' changed the state to `analyzed'. + + State-Changed-From-To: open-analyzed + State-Changed-By: hacker + State-Changed-When: Fri Feb 31 1993 08:59:16 1993 + State-Changed-Why: + figured out the problem, working on a patch this afternoon + -- + F.B. Hacker + Cygnus Support, Mountain View, CA 415 903 1400 + #include <std-disclaimer.h> + +The bug has now been analyzed, and Cygnus is working on a solution. + +Sometime later, we get more mail from F.B.: + + To: jeffrey@imaginary.com + From: hacker@cygnus.com + Subject: Re: bifrabulator/1425: routines don't match + Reply-To: hacker@cygnus.com + + There's a patch now that you can ftp over and check out. + + Hey, that joke you sent me was great! The one about the + strings walking into a bar... my boss laughed for an hour! + -- + F.B. Hacker + Cygnus Support, Mountain View, CA 415 903 1400 + #include <std-disclaimer.h> + + From: hacker@cygnus.com + To: jeffrey@imaginary.com + Subject: Re: bifrabulator/1425: doesn't match prestidig + Reply-To: hacker@cygnus.com + + + `F.B. Hacker' changed the state to `feedback'. + + State-Changed-From-To: analyzed-feedback + State-Changed-By: hacker + State-Changed-When: Fri Feb 31 1993 23:43:16 1993 + State-Changed-Why: + got the patch finished, notified Jeff at Imaginary Software + -- + F.B. Hacker + Cygnus Support, Mountain View, CA 415 903 1400 + #include <std-disclaimer.h> + +The bug has gone into "feedback" status now, until we get the patch, +install it and test it. When everything tests well, we can mail F.B. +back and tell him the bug's been fixed, and he can change the state of +the PR from "feedback" to "closed". + + Following is a list of valid `>Category:' entries that are supported +by Cygnus. + +* Menu: + +* Valid Categories:: + + +File: send-pr.info, Node: Valid Categories, Up: An Example + +Valid Categories +================ + +`bfd' + GNU binary file descriptor library. + +`bifrabulator' + This one doesn't actually exist. + +`binutils' + GNU utilities for binary files (`ar', `nm', `size'...). + +`bison' + GNU parser generator. + +`byacc' + Free parser generator. + +`config' + Cygnus Support Software configuration and installation. + +`cvs' + Concurrent Version System. + +`diff' + GNU `diff' program. + +`doc' + Documentation and manuals. + +`emacs' + GNU Emacs editor and related functions. + +`flex' + GNU lexical analyzer. + +`g++' + GNU C++ compiler. + +`gas' + GNU assembler. + +`gcc' + GNU C compiler. + +`gdb' + GNU source code debugger. + +`glob' + The filename globbing functions. + +`gprof' + GNU profiler. + +`grep' + GNU `grep' program. + +`info' + GNU `info' hypertext reader. + +`ispell' + GNU spelling checker. + +`kerberos' + Kerberos authentication system. + +`ld' + GNU linker. + +`libc' + Cygnus Support C Support Library. + +`libg++' + GNU C++ class library. + +`libiberty' + GNU `libiberty' library. + +`libm' + Cygnus Support C Math Library. + +`make' + GNU `make' program. + +`makeinfo' + GNU utility to build Info files from Texinfo documents. + +`mas' + GNU Motorola syntax assembler. + +`newlib' + Cygnus Support C Support and Math Libraries. + +`patch' + GNU bug patch program. + +`gnats' + GNU Problem Report Management System. + +`rcs' + Revision Control System. + +`readline' + GNU `readline' library. + +`send-pr' + GNU Problem Report submitting program. + +`test' + Category to use when testing `send-pr'. + +`texindex' + GNU documentation indexing utility. + +`texinfo' + GNU documentation macros. + +`other' + Anything which is not covered by the above categories. + + +File: send-pr.info, Node: Installing send-pr, Next: Index, Prev: An Example, Up: Top + +Installing `send-pr' on your system +*********************************** + + If you receive `send-pr' as part of a larger software distribution, +it probably gets installed when the full distribution is installed. If +you are using GNATS at your site as well, you must decide where +`send-pr' sends Problem Reports by default; see *Note Setting a default +SITE: default site. + +* Menu: + +* installation:: installing `send-pr' by itself +* default site:: setting a default site + + +File: send-pr.info, Node: installation, Next: default site, Up: Installing send-pr + +Installing `send-pr' by itself +============================== + + Install `send-pr' by following these steps (you may need `root' +access in order to change the `aliases' file and to install `send-pr'): + + * Unpack the distribution into a directory which we refer to as + SRCDIR. + + * Edit the file `Makefile' to reflect local conventions. + Specifically, you should edit the variable `prefix' to alter the + installation location. The default is `/usr/local'. All files are + installed under `prefix' (see below). + + * *Run* + make all install [ info ] [ install-info ] [ clean ] + + The targets mean the following: + + `all' + Builds `send-pr' and `install-sid' + + `install' + Installs the following: + + `install-sid' + `send-pr' + into `PREFIX/bin' + + `send-pr.1' + into `PREFIX/man/man1' + + `SITE' + the list of valid CATEGORIES for the Support Site from + which you received `send-pr', installed as + `PREFIX/lib/gnats/SITE' + + `send-pr.el' + into `PREFIX/lib/emacs/lisp'(1) + + `info (*optional*)' + Builds `send-pr.info' from `send-pr.texi' + (`send-pr.info' is included with this distribution) + + `install-info (*optional*)' + Installs `send-pr.info' into `PREFIX/info' + + `clean (*optional*)' + Removes all intermediary build files that can be rebuilt from + source code + + * Run + + install-sid YOUR-SID + + where YOUR-SID is the identification code you received with + `send-pr'. `send-pr' automatically inserts this value into the + template field `>Submitter-Id:'. If you've downloaded `send-pr' + from the Net, use `net' for this value. + + * Place the following line in `PREFIX/lib/emacs/lisp/default.el', or + instruct your users to place the following line in their `.emacs' + files: + + (autoload 'send-pr "send-pr" "Submit a Problem Report." t) + + * Create a mail alias for the Support Site from which you received + `send-pr', and for every site with which you wish to use `send-pr' + to communicate. Each alias must have a suffix of `-gnats'. The + Support Site(s) will provide the correct addresses where these + aliases should point. For instance, edit your mail aliases file + to contain something like: + + # support sites; for use with send-pr + cygnus-gnats: bugs@cygnus.com # Cygnus Support + bumblebee-gnats: bumblebugs@bumblebee.com # Bumblebee Inc. + mycompany-gnats: bugs@my.company.com (*if you use GNATS locally*) + + `send-pr' automatically searches for these aliases when you type + + send-pr cygnus + send-pr bumblebee + send-pr SITE... + + `send-pr' also uses SITE to determine the categories of problems + accepted by the site in question by looking in + + PREFIX/lib/gnats/SITE + + ---------- Footnotes ---------- + + (1) If your main Emacs lisp repository is in a different directory +from this, substitute that directory for `PREFIX/lib/emacs/lisp'. + + +File: send-pr.info, Node: default site, Prev: installation, Up: Installing send-pr + +Setting a default SITE +====================== + + `send-pr' is capable of sending Problem Reports to any number of +Support Sites, using mail aliases which have `-gnats' appended them. +`send-pr' automatically appends the suffix, so that when you type + + send-pr SITE + +the Problem Report goes to the address noted in the `aliases' file as +`SITE-gnats'. You can do this in the Emacs version of `send-pr' by +invoking the program with + + C-u M-x send-pr + +You are prompted for SITE. + + SITE is also used to error-check the `>Category:' field, as a +precaution against sending mistaken information (and against sending +information to the wrong site). + + You may also simply type + + send-pr + +from the shell (or `M-x send-pr' in Emacs), and the Problem Report you +generate will be sent to the SITE, which is usually the site from which +you received your distribution of `send-pr'. If you use GNATS at your +own organization, the default is usually your local address for +reporting problems. + + To change this, simply edit the file `Makefile' before installing +and change the line + + GNATS_SITE = SITE + +to reflect the site where you wish to send PRs by default. + + +File: send-pr.info, Node: Index, Prev: Installing send-pr, Up: Top + +Index +***** + +* Menu: + +* >Arrival-Date:: Problem Report fields. +* >Audit-Trail:: Problem Report fields. +* >Category:: Problem Report fields. +* >Class:: Problem Report fields. +* >Confidential:: Problem Report fields. +* >Description:: Problem Report fields. +* >Environment:: Problem Report fields. +* >Fix:: Problem Report fields. +* >How-To-Repeat:: Problem Report fields. +* >Number:: Problem Report fields. +* >Organization:: Problem Report fields. +* >Originator:: Problem Report fields. +* >Priority:: Problem Report fields. +* >Release:: Problem Report fields. +* >Responsible:: Problem Report fields. +* >Severity:: Problem Report fields. +* >State:: Problem Report fields. +* >Submitter-Id:: using send-pr. +* >Submitter-Id:: Problem Report fields. +* >Synopsis:: Problem Report fields. +* >Unformatted:: Problem Report fields. +* Arrival-Date field: Problem Report fields. +* Audit-Trail field: Problem Report fields. +* bifrabulator: An Example. +* Category field: Problem Report fields. +* Class field: Problem Report fields. +* Confidential field: Problem Report fields. +* Description field: Problem Report fields. +* Environment field: Problem Report fields. +* Fix field: Problem Report fields. +* From: header: Mail header fields. +* How-To-Repeat field: Problem Report fields. +* Number field: Problem Report fields. +* Organization field: Problem Report fields. +* Originator field: Problem Report fields. +* Priority field: Problem Report fields. +* Release field: Problem Report fields. +* Reply-To: header: Mail header fields. +* Responsible-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields. +* Responsible-Changed-By: in >Audit-Trail:: Problem Report fields. +* Responsible-Changed-When: in >Audit-Trail:: Problem Report fields. +* Responsible-Changed-Why: in >Audit-Trail:: Problem Report fields. +* Responsible field: Problem Report fields. +* send-pr fields: using send-pr. +* send-pr within Emacs: send-pr in Emacs. +* Severity field: Problem Report fields. +* State-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields. +* State-Changed-By: in >Audit-Trail:: Problem Report fields. +* State-Changed-When: in >Audit-Trail:: Problem Report fields. +* State-Changed-Why: in >Audit-Trail:: Problem Report fields. +* State field: Problem Report fields. +* Subject: header: Mail header fields. +* Submitter-Id field: Problem Report fields. +* Submitter-Id field: using send-pr. +* Synopsis field: Problem Report fields. +* To: header: Mail header fields. +* Unformatted field: Problem Report fields. +* *analyzed* state: States. +* *change-request* class: Problem Report fields. +* *closed* state: States. +* *critical* severity problems: Problem Report fields. +* *doc-bug* class: Problem Report fields. +* *duplicate* class: Problem Report fields. +* *Enumerated* data types: Fields. +* *feedback* state: States. +* *high* priority problems: Problem Report fields. +* *low* priority problems: Problem Report fields. +* *medium* priority problems: Problem Report fields. +* *MultiText* data types: Fields. +* *non-critical* severity problems: Problem Report fields. +* *open* state: States. +* *serious* severity problems: Problem Report fields. +* *support* class: Problem Report fields. +* *suspended* state: States. +* *sw-bug* class: Problem Report fields. +* *Text* data types: Fields. +* an example: An Example. +* appending PRs: using send-pr. +* appending PRs: Problem Report fields. +* automatic notification: States. +* bad Problem Reports: using send-pr. +* blank PR template: An Example. +* command line options: send-pr from the shell. +* comment section in the PR template: using send-pr. +* completed Problem Report: An Example. +* completion in Emacs: send-pr in Emacs. +* confidentiality in PRs: Problem Report fields. +* Cygnus Support: An Example. +* database similarities: Fields. +* default SITE: default site. +* default PR template: An Example. +* details about send-pr: send-pr in detail. +* editing and sending PRs: Invoking send-pr. +* effective problem reporting: Helpful hints. +* Emacs: send-pr in Emacs. +* errors: using send-pr. +* example of a completed PR: An Example. +* example of a default template: An Example. +* example of a list of valid categories: Valid Categories. +* example of a state change: An Example. +* example PR: An Example. +* example Problem Report: Fields. +* field format: Problem Report fields. +* fields: Fields. +* fields - list: Problem Report fields. +* final state ("closed"): States. +* foreword to send-pr: Top. +* format: Fields. +* generating new PRs: Invoking send-pr. +* GNATS: Top. +* GNATS database fields: Problem Report fields. +* GNATS fields - list: Problem Report fields. +* GNU software support: An Example. +* helpful hints: Helpful hints. +* Imaginary Software, Ltd.: An Example. +* information to submit: Helpful hints. +* initial state ("open"): States. +* installation: Installing send-pr. +* installation procedure: installation. +* interactive interface: send-pr in Emacs. +* Internet standard RFC-822: Mail header fields. +* introduction to send-pr: Top. +* invalid Problem Reports: using send-pr. +* invoking send-pr from Emacs: send-pr in Emacs. +* invoking send-pr from the shell: send-pr from the shell. +* invoking send-pr: Invoking send-pr. +* kinds of helpful information: Helpful hints. +* life-cycle of a Problem Report: States. +* listing valid categories: send-pr from the shell. +* mail header fields: Mail header fields. +* mail header section: using send-pr. +* name completion in Emacs: send-pr in Emacs. +* other mail: using send-pr. +* other mail: Problem Report fields. +* overview to send-pr: Top. +* PR confidentiality: Problem Report fields. +* Problem Report data types: Fields. +* Problem Report format: Fields. +* Problem Report states: States. +* Problem Report template: Fields. +* Problem Reports: send-pr in detail. +* related mail: Problem Report fields. +* related mail: using send-pr. +* Report all the facts!: Helpful hints. +* sample Problem Report: Fields. +* saving related mail: Problem Report fields. +* saving related mail: using send-pr. +* sending PRs: Invoking send-pr. +* setting a default SITE: default site. +* shell invocation: send-pr from the shell. +* state change example: An Example. +* state--"analyzed": States. +* state--"closed": States. +* state--"feedback": States. +* state--"open": States. +* state--"suspended": States. +* states of Problem Reports: States. +* subsequent mail: Problem Report fields. +* subsequent mail: using send-pr. +* template: using send-pr. +* template comment section: using send-pr. +* using send-pr from within Emacs: send-pr in Emacs. +* Using and Porting GNU CC: Helpful hints. +* using send-pr: Invoking send-pr. +* valid categories: Valid Categories. + + + +Tag Table: +Node: Top827 +Node: send-pr in detail2851 +Node: States3690 +Node: Fields5122 +Node: Mail header fields8791 +Node: Problem Report fields9656 +Node: Invoking send-pr17045 +Node: using send-pr17502 +Node: send-pr in Emacs24509 +Node: send-pr from the shell28914 +Node: Helpful hints31261 +Node: An Example34366 +Node: Valid Categories43466 +Node: Installing send-pr45285 +Node: installation45852 +Node: default site49077 +Node: Index50334 + +End Tag Table diff --git a/gnu/usr.bin/send-pr/send-pr.sh b/gnu/usr.bin/send-pr/send-pr.sh new file mode 100644 index 0000000..5354b98 --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr.sh @@ -0,0 +1,523 @@ +#!/bin/sh +# Submit a problem report to a GNATS site. +# Copyright (C) 1993 Free Software Foundation, Inc. +# Contributed by Brendan Kehoe (brendan@cygnus.com), based on a +# version written by Heinz G. Seidl (hgs@ide.com). +# +# This file is part of GNU GNATS. +# +# GNU GNATS is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; either version 2, or (at your option) +# any later version. +# +# GNU GNATS is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with GNU GNATS; see the file COPYING. If not, write to +# the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. + +# The version of this send-pr. +VERSION=3.2 + +# The submitter-id for your site. +SUBMITTER=unknown + +# Where the GNATS directory lives, if at all. +[ -z "$GNATS_ROOT" ] && +GNATS_ROOT= + +# The default mail address for PR submissions. +GNATS_ADDR=FreeBSD-gnats@freefall.cdrom.com + +# Where the gnats category tree lives. +DATADIR=@DATADIR@ + +# If we've been moved around, try using GCC_EXEC_PREFIX. +[ ! -d $DATADIR/gnats -a -d "$GCC_EXEC_PREFIX" ] && DATADIR=@DATADIR@ + +# The default release for this host. +DEFAULT_RELEASE="@DEFAULT_RELEASE@" + +# The default organization. +DEFAULT_ORGANIZATION= + +# The default site to look for. +GNATS_SITE=freefall + +# Newer config information? +[ -f ${GNATS_ROOT}/gnats-adm/config ] && . ${GNATS_ROOT}/gnats-adm/config + +# What mailer to use. This must come after the config file, since it is +# host-dependent. +MAIL_AGENT="/usr/sbin/sendmail -oi -t" + +ECHON=bsd + +if [ $ECHON = bsd ] ; then + ECHON1="echo -n" + ECHON2= +elif [ $ECHON = sysv ] ; then + ECHON1=echo + ECHON2='\c' +else + ECHON1=echo + ECHON2= +fi + +# + +[ -z "$TMPDIR" ] && TMPDIR=/tmp + +TEMP=$TMPDIR/p$$ +BAD=$TMPDIR/pbad$$ +REF=$TMPDIR/pf$$ + +if [ -z "$LOGNAME" -a -n "$USER" ]; then + LOGNAME=$USER +fi + +FROM="$LOGNAME" +REPLY_TO="$LOGNAME" + +# Find out the name of the originator of this PR. +if [ -n "$NAME" ]; then + ORIGINATOR="$NAME" +elif [ -f $HOME/.fullname ]; then + ORIGINATOR="`sed -e '1q' $HOME/.fullname`" +elif [ -f /bin/domainname ]; then + if [ "`/bin/domainname`" != "" -a -f /usr/bin/ypcat ]; then + # Must use temp file due to incompatibilities in quoting behavior + # and to protect shell metacharacters in the expansion of $LOGNAME + /usr/bin/ypcat passwd 2>/dev/null | cat - /etc/passwd | grep "^$LOGNAME:" | + cut -f5 -d':' | sed -e 's/,.*//' > $TEMP + ORIGINATOR="`cat $TEMP`" + rm -f $TEMP + fi +fi + +if [ "$ORIGINATOR" = "" ]; then + grep "^$LOGNAME:" /etc/passwd | cut -f5 -d':' | sed -e 's/,.*//' > $TEMP + ORIGINATOR="`cat $TEMP`" + rm -f $TEMP +fi + +if [ -n "$ORGANIZATION" ]; then + if [ -f "$ORGANIZATION" ]; then + ORGANIZATION="`cat $ORGANIZATION`" + fi +else + if [ -n "$DEFAULT_ORGANIZATION" ]; then + ORGANIZATION="$DEFAULT_ORGANIZATION" + elif [ -f $HOME/.organization ]; then + ORGANIZATION="`cat $HOME/.organization`" + elif [ -f $HOME/.signature ]; then + ORGANIZATION="`cat $HOME/.signature`" + fi +fi + +# If they don't have a preferred editor set, then use +if [ -z "$VISUAL" ]; then + if [ -z "$EDITOR" ]; then + EDIT=vi + else + EDIT="$EDITOR" + fi +else + EDIT="$VISUAL" +fi + +# Find out some information. +SYSTEM=`( [ -f /bin/uname ] && /bin/uname -a ) || \ + ( [ -f /usr/bin/uname ] && /usr/bin/uname -a ) || echo ""` +ARCH=`[ -f /bin/arch ] && /bin/arch` +MACHINE=`[ -f /bin/machine ] && /bin/machine` + +COMMAND=`echo $0 | sed -e 's,.*/,,'` +USAGE="Usage: $COMMAND [-PVL] [-t address] [-f filename] [--request-id] +[--version]" +REMOVE= +BATCH= + +while [ $# -gt 0 ]; do + case "$1" in + -r) ;; # Ignore for backward compat. + -t | --to) if [ $# -eq 1 ]; then echo "$USAGE"; exit 1; fi + shift ; GNATS_ADDR="$1" + EXPLICIT_GNATS_ADDR=true + ;; + -f | --file) if [ $# -eq 1 ]; then echo "$USAGE"; exit 1; fi + shift ; IN_FILE="$1" + if [ "$IN_FILE" != "-" -a ! -r "$IN_FILE" ]; then + echo "$COMMAND: cannot read $IN_FILE" + exit 1 + fi + ;; + -b | --batch) BATCH=true ;; + -p | -P | --print) PRINT=true ;; + -L | --list) FORMAT=norm ;; + -l | -CL | --lisp) FORMAT=lisp ;; + --request-id) REQUEST_ID=true ;; + -h | --help) echo "$USAGE"; exit 0 ;; + -V | --version) echo "$VERSION"; exit 0 ;; + -*) echo "$USAGE" ; exit 1 ;; + *) if [ -z "$USER_GNATS_SITE" ]; then + if [ ! -r "$DATADIR/gnats/$1" ]; then + echo "$COMMAND: the GNATS site $1 does not have a categories list." + exit 1 + else + # The site name is the alias they'll have to have created. + USER_GNATS_SITE=$1 + fi + else + echo "$USAGE" ; exit 1 + fi + ;; + esac + shift +done + +if [ -n "$USER_GNATS_SITE" ]; then + GNATS_SITE=$USER_GNATS_SITE + GNATS_ADDR=$USER_GNATS_SITE-gnats +fi + +if [ "$SUBMITTER" = "unknown" -a -z "$REQUEST_ID" -a -z "$IN_FILE" ]; then + cat << '__EOF__' +It seems that send-pr is not installed with your unique submitter-id. +You need to run + + install-sid YOUR-SID + +where YOUR-SID is the identification code you received with `send-pr'. +`send-pr' will automatically insert this value into the template field +`>Submitter-Id'. If you've downloaded `send-pr' from the Net, use `net' +for this value. If you do not know your id, run `send-pr --request-id' to +get one from your support site. +__EOF__ + exit 1 +fi + +if [ -r "$DATADIR/gnats/$GNATS_SITE" ]; then + CATEGORIES=`grep -v '^#' $DATADIR/gnats/$GNATS_SITE | sort` +else + echo "$COMMAND: could not read $DATADIR/gnats/$GNATS_SITE for categories list." + exit 1 +fi + +if [ -z "$CATEGORIES" ]; then + echo "$COMMAND: the categories list for $GNATS_SITE was empty!" + exit 1 +fi + +case "$FORMAT" in + lisp) echo "$CATEGORIES" | \ + awk 'BEGIN {printf "( "} {printf "(\"%s\") ",$0} END {printf ")\n"}' + exit 0 + ;; + norm) l=`echo "$CATEGORIES" | \ + awk 'BEGIN {max = 0; } { if (length($0) > max) { max = length($0); } } + END {print max + 1;}'` + c=`expr 70 / $l` + if [ $c -eq 0 ]; then c=1; fi + echo "$CATEGORIES" | \ + awk 'BEGIN {print "Known categories:"; i = 0 } + { printf ("%-'$l'.'$l's", $0); if ((++i % '$c') == 0) { print "" } } + END { print ""; }' + exit 0 + ;; +esac + +ORIGINATOR_C='<Name of the PR author (one line)>' +ORGANIZATION_C='<Organization of PR author (multiple lines)>' +CONFIDENTIAL_C='<[ yes | no ] (one line)>' +SYNOPSIS_C='<Synopsis of the problem (one line)>' +SEVERITY_C='<[ non-critical | serious | critical ] (one line)>' +PRIORITY_C='<[ low | medium | high ] (one line)>' +CATEGORY_C='<Problem category (as listed above)>' +CLASS_C='<[ sw-bug | doc-bug | change-request | support ] (one line)>' +RELEASE_C='<Release number or tag (one line)>' +ENVIRONMENT_C='<Relevant environment information (multiple lines)>' +DESCRIPTION_C='<Precise description of the problem (multiple lines)>' +HOW_TO_REPEAT_C='<Code/input/activities to reproduce the problem (multiple lines)>' +FIX_C='<How to correct or work around the problem, if known (multiple lines)>' + +# Catch some signals. ($xs kludge needed by Sun /bin/sh) +xs=0 +trap 'rm -f $REF $TEMP; exit $xs' 0 +trap 'echo "$COMMAND: Aborting ..."; rm -f $REF $TEMP; xs=1; exit' 1 2 3 13 15 + +# If they told us to use a specific file, then do so. +if [ -n "$IN_FILE" ]; then + if [ "$IN_FILE" = "-" ]; then + # The PR is coming from the standard input. + if [ -n "$EXPLICIT_GNATS_ADDR" ]; then + sed -e "s;^[Tt][Oo]:.*;To: $GNATS_ADDR;" > $TEMP + else + cat > $TEMP + fi + else + # Use the file they named. + if [ -n "$EXPLICIT_GNATS_ADDR" ]; then + sed -e "s;^[Tt][Oo]:.*;To: $GNATS_ADDR;" $IN_FILE > $TEMP + else + cat $IN_FILE > $TEMP + fi + fi +else + + if [ -n "$PR_FORM" -a -z "$PRINT_INTERN" ]; then + # If their PR_FORM points to a bogus entry, then bail. + if [ ! -f "$PR_FORM" -o ! -r "$PR_FORM" -o ! -s "$PR_FORM" ]; then + echo "$COMMAND: can't seem to read your template file (\`$PR_FORM'), ignoring PR_FORM" + sleep 1 + PRINT_INTERN=bad_prform + fi + fi + + if [ -n "$PR_FORM" -a -z "$PRINT_INTERN" ]; then + cp $PR_FORM $TEMP || + ( echo "$COMMAND: could not copy $PR_FORM" ; xs=1; exit ) + else + for file in $TEMP $REF ; do + cat > $file << '__EOF__' +SEND-PR: -*- send-pr -*- +SEND-PR: Lines starting with `SEND-PR' will be removed automatically, as +SEND-PR: will all comments (text enclosed in `<' and `>'). +SEND-PR: +SEND-PR: Please consult the send-pr man page `send-pr(1)' or the Texinfo +SEND-PR: manual if you are not sure how to fill out a problem report. +SEND-PR: +SEND-PR: Choose from the following categories: +SEND-PR: +__EOF__ + + # Format the categories so they fit onto lines. + l=`echo "$CATEGORIES" | \ + awk 'BEGIN {max = 0; } { if (length($0) > max) { max = length($0); } } + END {print max + 1;}'` + c=`expr 61 / $l` + if [ $c -eq 0 ]; then c=1; fi + echo "$CATEGORIES" | \ + awk 'BEGIN {printf "SEND-PR: "; i = 0 } + { printf ("%-'$l'.'$l's", $0); + if ((++i % '$c') == 0) { printf "\nSEND-PR: " } } + END { printf "\nSEND-PR:\n"; }' >> $file + + + + cat >> $file << __EOF__ + +To: $GNATS_ADDR +Subject: +From: $FROM +Reply-To: $REPLY_TO +X-send-pr-version: $VERSION + +>Submitter-Id: $SUBMITTER +>Originator: $ORIGINATOR +>Organization: `if [ -n "$ORGANIZATION" ]; then + echo "$ORGANIZATION" + else + echo "$ORGANIZATION_C" ; + fi ; ` +>Confidential: $CONFIDENTIAL_C +>Synopsis: $SYNOPSIS_C +>Severity: $SEVERITY_C +>Priority: $PRIORITY_C +>Category: $CATEGORY_C +>Release: `if [ -n "$DEFAULT_RELEASE" ]; then + echo "$DEFAULT_RELEASE" + else + echo "$RELEASE_C" + fi ; ` +>Class: $CLASS_C +>Environment: + + $ENVIRONMENT_C + +>Description: + + $DESCRIPTION_C + +>How-To-Repeat: + + $HOW_TO_REPEAT_C + +>Fix: + + $FIX_C + +__EOF__ + done + fi + + if [ "$PRINT" = true -o "$PRINT_INTERN" = true ]; then + cat $TEMP + xs=0; exit + fi + + chmod u+w $TEMP + if [ -z "$REQUEST_ID" ]; then + eval $EDIT $TEMP + else + ed -s $TEMP << '__EOF__' +/^Subject/s/^Subject:.*/Subject: request for a customer id/ +/^>Category/s/^>Category:.*/>Category: send-pr/ +w +q +__EOF__ + fi + + if cmp -s $REF $TEMP ; then + echo "$COMMAND: problem report not filled out, therefore not sent" + xs=1; exit + fi +fi + +# +# Check the enumeration fields + +# This is a "sed-subroutine" with one keyword parameter +# (with workaround for Sun sed bug) +# +SED_CMD=' +/$PATTERN/{ +s||| +s|<.*>|| +s|^[ ]*|| +s|[ ]*$|| +p +q +}' + + +while [ -z "$REQUEST_ID" ]; do + CNT=0 + + # 1) Confidential + # + PATTERN=">Confidential:" + CONFIDENTIAL=`eval sed -n -e "\"$SED_CMD\"" $TEMP` + case "$CONFIDENTIAL" in + ""|yes|no) CNT=`expr $CNT + 1` ;; + *) echo "$COMMAND: \`$CONFIDENTIAL' is not a valid value for \`Confidential'." ;; + esac + # + # 2) Severity + # + PATTERN=">Severity:" + SEVERITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP` + case "$SEVERITY" in + ""|non-critical|serious|critical) CNT=`expr $CNT + 1` ;; + *) echo "$COMMAND: \`$SEVERITY' is not a valid value for \`Severity'." + esac + # + # 3) Priority + # + PATTERN=">Priority:" + PRIORITY=`eval sed -n -e "\"$SED_CMD\"" $TEMP` + case "$PRIORITY" in + ""|low|medium|high) CNT=`expr $CNT + 1` ;; + *) echo "$COMMAND: \`$PRIORITY' is not a valid value for \`Priority'." + esac + # + # 4) Category + # + PATTERN=">Category:" + CATEGORY=`eval sed -n -e "\"$SED_CMD\"" $TEMP` + FOUND= + for C in $CATEGORIES + do + if [ "$C" = "$CATEGORY" ]; then FOUND=true ; break ; fi + done + if [ -n "$FOUND" ]; then + CNT=`expr $CNT + 1` + else + if [ -z "$CATEGORY" ]; then + echo "$COMMAND: you must include a Category: field in your report." + else + echo "$COMMAND: \`$CATEGORY' is not a known category." + fi + fi + # + # 5) Class + # + PATTERN=">Class:" + CLASS=`eval sed -n -e "\"$SED_CMD\"" $TEMP` + case "$CLASS" in + ""|sw-bug|doc-bug|change-request|support) CNT=`expr $CNT + 1` ;; + *) echo "$COMMAND: \`$CLASS' is not a valid value for \`Class'." + esac + + [ $CNT -lt 5 -a -z "$BATCH" ] && + echo "Errors were found with the problem report." + + while true; do + if [ -z "$BATCH" ]; then + $ECHON1 "a)bort, e)dit or s)end? $ECHON2" + read input + else + if [ $CNT -eq 5 ]; then + input=s + else + input=a + fi + fi + case "$input" in + a*) + if [ -z "$BATCH" ]; then + echo "$COMMAND: the problem report remains in $BAD and is not sent." + mv $TEMP $BAD + else + echo "$COMMAND: the problem report is not sent." + fi + xs=1; exit + ;; + e*) + eval $EDIT $TEMP + continue 2 + ;; + s*) + break 2 + ;; + esac + done +done +# +# Remove comments and send the problem report +# (we have to use patterns, where the comment contains regex chars) +# +# /^>Originator:/s;$ORIGINATOR;; +sed -e " +/^SEND-PR:/d +/^>Organization:/,/^>[A-Za-z-]*:/s;$ORGANIZATION_C;; +/^>Confidential:/s;<.*>;; +/^>Synopsis:/s;$SYNOPSIS_C;; +/^>Severity:/s;<.*>;; +/^>Priority:/s;<.*>;; +/^>Category:/s;$CATEGORY_C;; +/^>Class:/s;<.*>;; +/^>Release:/,/^>[A-Za-z-]*:/s;$RELEASE_C;; +/^>Environment:/,/^>[A-Za-z-]*:/s;$ENVIRONMENT_C;; +/^>Description:/,/^>[A-Za-z-]*:/s;$DESCRIPTION_C;; +/^>How-To-Repeat:/,/^>[A-Za-z-]*:/s;$HOW_TO_REPEAT_C;; +/^>Fix:/,/^>[A-Za-z-]*:/s;$FIX_C;; +" $TEMP > $REF + +if $MAIL_AGENT < $REF; then + echo "$COMMAND: problem report sent" + xs=0; exit +else + echo "$COMMAND: mysterious mail failure." + if [ -z "$BATCH" ]; then + echo "$COMMAND: the problem report remains in $BAD and is not sent." + mv $REF $BAD + else + echo "$COMMAND: the problem report is not sent." + fi + xs=1; exit +fi diff --git a/gnu/usr.bin/send-pr/send-pr.texi b/gnu/usr.bin/send-pr/send-pr.texi new file mode 100644 index 0000000..b9edd9c --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr.texi @@ -0,0 +1,657 @@ +\input texinfo @c -*-texinfo-*- +@setfilename send-pr.info +@settitle Reporting Problems Using send-pr + +@setchapternewpage odd + +@include version.texi +@set SENDPR + +@ifinfo +@format +START-INFO-DIR-ENTRY +* send-pr:: Reporting problems--using send-pr +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @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. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore + +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. +@end ifinfo + +@titlepage +@finalout +@title Reporting Problems +@subtitle Using @code{send-pr}, version @value{VERSION} +@subtitle October 1993 +@author Jeffrey M. Osier +@author Cygnus Support +@page + +@vskip 0pt plus 1filll + +Copyright @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. + +@end titlepage + +@c --------------------------------------------------------------- +@node Top +@top Overview +@cindex foreword to @code{send-pr} +@cindex overview to @code{send-pr} +@cindex introduction to @code{send-pr} + +This manual documents @code{send-pr}, +@ifinfo +version @value{VERSION}, +@end ifinfo +which uses electronic mail to submit support questions and problem +reports to a central Support Site. No body of work is perfect, and +support organizations understand this; @code{send-pr} is designed to +allow users who have problems to submit reports of these problems to +sites responsible for supporting the products in question, in a defined +form which can be read by an electronically managed database. + +@cindex GNATS +@code{send-pr} is part of a suite of programs known collectively as +@sc{gnats}, the @sc{gnu} Problem Report Management System. @sc{gnats} +consists of several programs which, used in concert, formulate and +partially administer a database of @dfn{Problem Reports}, or @dfn{PRs}, +at a central Support Site. A PR goes through several states in its +lifetime; @sc{gnats} tracks the PR and all information associated with it +through each state and finally acts as an archive for PRs which have +been @dfn{closed}. + +Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as +an Elisp file for use with @sc{gnu} Emacs, it can be used from any +machine on your network which can run a shell script and/or Emacs. + +In general, you can use any editor and mailer to submit valid Problem +Reports, as long as the format required by @sc{gnats} is preserved. +@code{send-pr} automates the process, however, and ensures that certain +fields necessary for automatic processing are present. @code{send-pr} +is strongly recommended for all initial problem-oriented correspondence +with your Support Site. The organization you submit Problem Reports to +supplies an address to which further information can be sent; the person +responsible for the category of the problem you report contacts you +directly. + +@menu +* send-pr in detail:: Details about send-pr and GNATS +* Invoking send-pr:: Editing and sending PRs +* An Example:: A working example +* Installing send-pr:: Installing send-pr on your system +* Index:: +@end menu + +@node send-pr in detail +@chapter Details about send-pr and GNATS + +@cindex details about @code{send-pr} +@cindex Problem Reports +A @dfn{Problem Report} is a message that describes a problem you are +having with a body of work. @code{send-pr} organizes this message into +a form which can be understood and automatically processed by @sc{gnats}, +the @sc{gnu} Problem Report Management System. A Problem Report is +organized into @dfn{fields} which contain data describing you, your +organization, and the problem you are announcing (@pxref{Fields,,Problem +Report format}). Problem Reports go through several defined states in +their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States +of Problem Reports}). + +@menu +* States:: States of Problem Reports +* Fields:: Problem Report format +@end menu + +@include states.texi + +@include fields.texi + +@node Invoking send-pr +@chapter Editing and sending PRs +@cindex editing and sending PRs +@cindex sending PRs +@cindex invoking send-pr +@cindex using send-pr +@cindex generating new PRs + +@include s-usage.texi + +@node An Example +@chapter An Example +@cindex an example +@cindex example PR +@cindex Cygnus Support +@cindex GNU software support + +Cygnus Support in Mountain View, CA, uses @sc{gnats} and @code{send-pr} +extensively for their support activities. As a support company, Cygnus +finds problem tracking to be a crucial part of everyday business. +Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and +@code{send-pr}) over several many platforms + +With each shipment of the Cygnus Support Developer's Kit, customers +receive the latest version of @code{send-pr}, which contains an +up-to-date listing of valid categories (values for the @code{>Category:} +field). Using these tools, Cygnus' customers can communicate their +problems to Cygnus effectively and receive automatic confirmation of +receipt as well as notification of changes in the status of their +reported problems. Much of Cygnus' support mechanism relies on +electronic mail. + +As an example, let's pretend we're a customer of Cygnus Support, and +that we're having a problem compiling some of our software using the +@sc{gnu} C compiler, which Cygnus supports. + +Assume that we're getting an error in our @code{bifrabulator} program +wherein the @samp{prestidigitation} routines don't match with the +@samp{whatsitsname}. We've made sure we're following the rules of the +program and checked the Release Notes from Cygnus and found that the bug +isn't already known. In other words, we're pretty sure we've found a +bug. + +@cindex Imaginary Software, Ltd. +Our first step is to call @code{send-pr}. It really doesn't matter +whether we use @code{send-pr} from the shell or from within Emacs. +Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from +the shell is likely to start @code{send-pr} in an Emacs buffer anyway. +So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu} +software extensively, we're pretty familiar with Emacs, so from within +Emacs we type +@smallexample +M-x send-pr +@end smallexample +@noindent +and we're greeted with the following screen: + +@cindex default PR template +@cindex example of a default template +@cindex blank PR template +@cindex @code{bifrabulator} +@cartouche +@smallexample +SEND-PR: -*- text -*- +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: Please consult the manual if you are not sure +SEND-PR: how to fill out a problem report. +SEND-PR: +SEND-PR: Choose from the following categories: +SEND-PR: +SEND-PR: bfd binutils bison +SEND-PR: byacc clib config cvs diff +SEND-PR: doc emacs flex g++ gas +SEND-PR: gcc gdb glob gprof grep +SEND-PR: info ispell kerberos ld libg++ +SEND-PR: libiberty make makeinfo mas newlib +SEND-PR: other patch rcs readline send-pr +SEND-PR: test texindex texinfo texinfo.tex +SEND-PR: bifrabulator <---@emph{note: this one is fake} +SEND-PR: +To: cygnus-bugs@@cygnus.com +Subject: +From: jeffrey@@imaginary.com +Reply-To: jeffrey@@imaginary.com +X-send-pr-version: send-pr @value{VERSION} + +>Submitter-Id: imaginary +>Originator: Jeffrey Osier +>Organization: +Imaginary Software, Ltd. +>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](oneline)> +>Release: <release number or tag (one line)> +>Environment: + <machine, os, target, libraries (multiple lines)> +System: SunOS imaginary.com 4.1.1 1 sun4 +Architecture: sun4 + +>Description: + <precise description of the problem (multiple lines)> +>How-To-Repeat: + <code/input/activities to reproduce (multiple lines)> +>Fix: +@iftex +@hrule +@end iftex +-----Emacs: *send-pr* (send-pr Fill)----All------------------ +@iftex +@hrule +@end iftex +>Category: other[] +@end smallexample +@end cartouche +@page +We know from past experience that we need to set certain information into +each field, so we compile all the information we know about our problem. +We have some sample code which we know should work, even though it +doesn't, so we'll include that. Below is the completed PR; we send this +using @kbd{C-c C-c}. (The comments have been truncated). + +@cindex completed Problem Report +@cindex example of a completed PR +@cartouche +@smallexample +SEND-PR: Lines starting with `SEND-PR' will be removed +SEND-PR: automatically as well as all comments (the text +SEND-PR: @dots{} +SEND-PR: +To: cygnus-bugs@@cygnus.com +Subject: bifrabulator routines don't match +From: jeffrey@@imaginary.com +Reply-To: jeffrey@@imaginary.com +X-send-pr-version: send-pr @value{VERSION} + +>Submitter-Id: imaginary +>Originator: Jeffrey Osier +>Organization: +Imaginary Software, Ltd. +>Confidential: no +>Synopsis: bifrabulator routines don't match +>Severity: serious +>Priority: medium +>Category: bifrabulator +>Class: sw-bug +>Release: progressive-930101 +>Environment: +System: SunOS imaginary.com 4.1.1 1 sun4 +Architecture: sun4 (SPARC) + +>Description: + the following code I fed into the bifrabulator came back + with a strange error. apparently, the prestidigitation + routine doesn't match with the whatsitsname in all cases. + +>How-To-Repeat: + call the bifrabulator on the following code. + @emph{code sample@dots{}} + +>Fix: +@iftex +@hrule +@end iftex +-----Emacs: *send-pr* (send-pr Fill)----All------------------ +@iftex +@hrule +@end iftex +To send the problem report use: C-c C-c +@end smallexample +@end cartouche + +We type @kbd{C-c C-c}, and off it goes. Now, we depend on Cygnus +Support to figure out the answer to our problem. + +Soon afterward, we get the following message from Cygnus: + +@smallexample +@group +From: gnats (GNATS management) +Sender: gnats-admin +Reply-To: hacker@@cygnus.com +To: jeffrey@@imaginary.com +Subject: Re: bifrabulator/1425: routines don't match + +Thank you very much for your problem report. +It has the internal identification: g++/1425. +The individual assigned to look at your bug is: hacker +(F.B. Hacker) + +Category: bifrabulator +Responsible: hacker +Synopsis: bifrabulator routines don't match +Arrival-Date: Sat Feb 30 03:12:55 1993 +@end group +@end smallexample + +@noindent +This is our receipt that the bug has been accepted and forwarded to the +responsible party. + +@noindent +A while later, we get the analysis: + +@smallexample +@group +To: jeffrey@@imaginary.com +From: hacker@@cygnus.com +Subject: Re: bifrabulator/1425: routines don't match +Reply-To: hacker@@cygnus.com + +Got your message, Jeff. It seems that the bifrabulator was +confusing the prestidigitation routines with the realitychecker +when lexically parsing the whatsitsname. + +I'm working on robustisizing the bifrabulator now. + +How about lunch next week? +-- +F.B. Hacker +Cygnus Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@end group +@end smallexample + +@noindent +About the same time, we get another message from Cygnus. + +@cindex state change example +@cindex example of a state change +@smallexample +@group +From: hacker@@cygnus.com +To: jeffrey@@imaginary.com +Subject: Re: bifrabulator/1425: doesn't match prestidig +Reply-To: hacker@@cygnus.com + + + `F.B. Hacker' changed the state to `analyzed'. + +State-Changed-From-To: open-analyzed +State-Changed-By: hacker +State-Changed-When: Fri Feb 31 1993 08:59:16 1993 +State-Changed-Why: + figured out the problem, working on a patch this afternoon +-- +F.B. Hacker +Cygnus Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@end group +@end smallexample + +@noindent +The bug has now been analyzed, and Cygnus is working on a solution. + +@noindent +Sometime later, we get more mail from F.B.: + +@smallexample +@group +To: jeffrey@@imaginary.com +From: hacker@@cygnus.com +Subject: Re: bifrabulator/1425: routines don't match +Reply-To: hacker@@cygnus.com + +There's a patch now that you can ftp over and check out. + +Hey, that joke you sent me was great! The one about the +strings walking into a bar... my boss laughed for an hour! +-- +F.B. Hacker +Cygnus Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@end group +@end smallexample +@sp 2 +@smallexample +@group +From: hacker@@cygnus.com +To: jeffrey@@imaginary.com +Subject: Re: bifrabulator/1425: doesn't match prestidig +Reply-To: hacker@@cygnus.com + + + `F.B. Hacker' changed the state to `feedback'. + +State-Changed-From-To: analyzed-feedback +State-Changed-By: hacker +State-Changed-When: Fri Feb 31 1993 23:43:16 1993 +State-Changed-Why: + got the patch finished, notified Jeff at Imaginary Software +-- +F.B. Hacker +Cygnus Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@end group +@end smallexample + +@noindent +The bug has gone into @dfn{feedback} status now, until we get the patch, +install it and test it. When everything tests well, we can mail F.B. +back and tell him the bug's been fixed, and he can change the state of +the PR from @dfn{feedback} to @dfn{closed}. + +Following is a list of valid @samp{>Category:} entries that are +supported by Cygnus. + +@menu +* Valid Categories:: +@end menu + +@c FIXME - is this list up to date? +@include categ.texi + +@node Installing send-pr +@appendix Installing @code{send-pr} on your system +@cindex installation + +If you receive @code{send-pr} as part of a larger software distribution, +it probably gets installed when the full distribution is installed. If +you are using @sc{gnats} at your site as well, you must decide where +@code{send-pr} sends Problem Reports by default; see @ref{default site,, +Setting a default @var{site}}. + +@menu +* installation:: installing `send-pr' by itself +* default site:: setting a default site +@end menu + +@node installation +@section Installing @code{send-pr} by itself +@cindex installation procedure + +Install @code{send-pr} by following these steps (you may need +@code{root} access in order to change the @file{aliases} file and to +install @code{send-pr}): + +@itemize @bullet +@item +Unpack the distribution into a directory which we refer to as +@var{srcdir}. + +@item +Edit the file @file{Makefile} to reflect local conventions. +Specifically, you should edit the variable @samp{prefix} to alter the +installation location. The default is @file{/usr/local}. All files are +installed under @samp{prefix} (see below). + +@item @emph{Run} +@smallexample +make all install [ info ] [ install-info ] [ clean ] +@end smallexample + +@noindent +The targets mean the following: + +@table @code +@item all +Builds @code{send-pr} and @code{install-sid} + +@item install +Installs the following: + +@table @code +@item install-sid +@itemx send-pr +into @file{@var{prefix}/bin} + +@item send-pr.1 +into @file{@var{prefix}/man/man1} + +@item @var{site} +the list of valid @var{categories} for the Support Site from which you +received @code{send-pr}, installed as +@w{@file{@var{prefix}/lib/gnats/@var{site}}} + +@item send-pr.el +into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs +lisp repository is in a different directory from this, substitute that +directory for @w{@file{@var{prefix}/lib/emacs/lisp}}.} +@end table + +@item info (@emph{optional}) +Builds @file{send-pr.info} from @file{send-pr.texi}@* +@c FIXME - is this still true? +(@file{send-pr.info} is included with this distribution) + +@item install-info (@emph{optional}) +Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}} + +@item clean (@emph{optional}) +Removes all intermediary build files that can be rebuilt from source +code +@end table + +@item +Run + +@smallexample +install-sid @var{your-sid} +@end smallexample + +@noindent +where @var{your-sid} is the identification code you received with +@w{@code{send-pr}}. @code{send-pr} automatically inserts this value +into the template field @samp{>Submitter-Id:}. If you've downloaded +@code{send-pr} from the Net, use @samp{net} for this value. + +@item +Place the following line in +@w{@file{@var{prefix}/lib/emacs/lisp/default.el}}, or instruct your +users to place the following line in their @file{.emacs} files: + +@smallexample +(autoload 'send-pr "send-pr" "Submit a Problem Report." t) +@end smallexample + +@item +Create a mail alias for the Support Site from which you received +@code{send-pr}, and for every site with which you wish to use +@code{send-pr} to communicate. Each alias must have a suffix of +@samp{-gnats}. The Support Site(s) will provide the correct addresses +where these aliases should point. For instance, edit your mail aliases +file to contain something like: + +@smallexample +# support sites; for use with send-pr +cygnus-gnats: bugs@@cygnus.com # Cygnus Support +bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc. +mycompany-gnats: bugs@@my.company.com (@emph{if you use @sc{gnats} locally}) +@end smallexample + +@code{send-pr} automatically searches for these aliases when you type + +@smallexample +send-pr cygnus +send-pr bumblebee +send-pr @var{site}@dots{} +@end smallexample + +@noindent +@code{send-pr} also uses @var{site} to determine the categories of +problems accepted by the site in question by looking in + +@smallexample +@var{prefix}/lib/gnats/@var{site} +@end smallexample + +@end itemize + +@node default site +@section Setting a default @var{site} +@cindex default @var{site} +@cindex setting a default @var{site} + +@code{send-pr} is capable of sending Problem Reports to any number of +Support Sites, using mail aliases which have @samp{-gnats} appended them. +@code{send-pr} automatically appends the suffix, so that when you type + +@smallexample +send-pr @var{site} +@end smallexample + +@noindent +the Problem Report goes to the address noted in the @file{aliases} file +as @w{@samp{@var{site}-gnats}}. You can do this in the Emacs version of +@code{send-pr} by invoking the program with + +@smallexample +C-u M-x send-pr +@end smallexample + +@noindent +You are prompted for @var{site}. + +@var{site} is also used to error-check the @samp{>Category:} field, as a +precaution against sending mistaken information (and against sending +information to the wrong site). + +You may also simply type + +@smallexample +send-pr +@end smallexample + +@noindent +from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem +Report you generate will be sent to the @var{site}, which is usually the +site from which you received your distribution of @w{@code{send-pr}}. +If you use @sc{gnats} at your own organization, the default is usually +your local address for reporting problems. + +To change this, simply edit the file @file{Makefile} before installing +and change the line + +@smallexample +GNATS_SITE = @var{site} +@end smallexample + +@noindent +to reflect the site where you wish to send PRs by default. + +@c --------------------------------------------------------------- +@node Index +@unnumbered Index + +@printindex cp + +@c --------------------------------------------------------------- +@contents +@bye |