Mercurial > hg > xemacs-beta
changeset 112:48d667d6f17f r20-1b8
Import from CVS: tag r20-1b8
line wrap: on
line diff
--- a/CHANGES-beta Mon Aug 13 09:19:47 2007 +0200 +++ b/CHANGES-beta Mon Aug 13 09:20:48 2007 +0200 @@ -1,4 +1,15 @@ -*- indented-text -*- +to 20.1 beta8 +-- GIF crash fix courtesy of David Moore +-- Fix for problem dumping comint with sparcworks +-- Fixes for problems during build with dynamic puresize +-- xpm background color patch courtesy of Darrell Kindred +-- Custom-1.64 +-- Gnus-5.4.28 +-- miscellaneous bug fixes +-- timer.el backed out, we're not ready for it. +-- GNATS-3.101 info documentation added, further integration of send-pr.el. + to 20.1 beta7 -- Update to time.el. -- htmlpro DTD, IE3 DTDs added to etc/sgml.
--- a/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,5 +1,13 @@ +Mon Mar 17 19:09:29 1997 Steven L Baur <steve@altair.xemacs.org> + + * XEmacs-20.1-b8 is released. + * XEmacs-19.15-b100 is released. + Sat Mar 15 17:15:18 1997 Steven L Baur <steve@altair.xemacs.org> + * XEmacs-20.1-b7 is released. + * XEmacs-19.15-b99 is released. + * etc/sgml/CATALOG: Added IE3 DTDs and htmlpro DTD. Thu Mar 13 10:40:11 1997 Steven L Baur <steve@altair.xemacs.org>
--- a/configure Mon Aug 13 09:19:47 2007 +0200 +++ b/configure Mon Aug 13 09:20:48 2007 +0200 @@ -6984,91 +6984,92 @@ Should XEmacs use the relocating allocator for buffers? ${rel_alloc} What window system should XEmacs use? ${window_system}${x_includes+ Where do we find X Windows header files? }${x_includes}${x_libraries+ - Where do we find X Windows libraries? }${x_libraries}" + Where do we find X Windows libraries? }${x_libraries}" >> Installation if test -n "$site_includes"; then - echo " Additional header files: ${site_includes}" + echo " Additional header files: ${site_includes}" >> Installation fi if test -n "$site_libraries" -a -n "$site_runtime_libraries"; then - echo " Additional libraries: ${site_libraries} ${site_runtime_libraries}" + echo " Additional libraries: ${site_libraries} ${site_runtime_libraries}" >> Installation elif test -n "$site_libraries"; then - echo " Additional libraries: ${site_libraries}" + echo " Additional libraries: ${site_libraries}" >> Installation elif test -n "$site_runtime_libraries"; then - echo " Additional libraries: ${site_runtime_libraries}" + echo " Additional libraries: ${site_runtime_libraries}" >> Installation fi if test "$with_wnn"; then - echo " Finding WNN includes with: ${wnn_includes}" - echo " Loading WNN libs with: ${wnn_libraries}" -fi -test "$with_socks" = yes && echo " Compiling in support for SOCKS." -test "$with_term" = yes && echo " Compiling in support for TERM." -test "$with_xauth" = yes && echo " Compiling in support for XAUTH." -test "$with_xpm" = yes && echo " Compiling in support for XPM." + echo " Finding WNN includes with: ${wnn_includes}" >> Installation + echo " Loading WNN libs with: ${wnn_libraries}" >> Installation +fi +test "$with_socks" = yes && echo " Compiling in support for SOCKS." >> Installation +test "$with_term" = yes && echo " Compiling in support for TERM." >> Installation +test "$with_xauth" = yes && echo " Compiling in support for XAUTH." >> Installation +test "$with_xpm" = yes && echo " Compiling in support for XPM." >> Installation if test "$with_xmu" != yes -a "$window_system" != none; then - echo " No Xmu; substituting equivalent routines." -fi -test "$with_xface" = yes && echo " Compiling in support for X-Face headers." -test "$with_gif" = yes && echo " Compiling in support for GIF image conversion." -test "$with_jpeg" = yes && echo " Compiling in support for JPEG image conversion." + echo " No Xmu; substituting equivalent routines." >> Installation +fi +test "$with_xface" = yes && echo " Compiling in support for X-Face headers." >> Installation +test "$with_gif" = yes && echo " Compiling in support for GIF image conversion." >> Installation +test "$with_jpeg" = yes && echo " Compiling in support for JPEG image conversion." >> Installation if test "$with_png" = yes -o "$with_png" = gnuz; then - echo " Compiling in support for PNG image conversion." + echo " Compiling in support for PNG image conversion." >> Installation fi if test "$with_png" = gnuz; then - echo " (Using -lgz instead of -lz.)" -fi -test "$with_tiff" = yes && echo " Compiling in support for TIFF image conversion (not implemented)." -test "$with_epoch" = yes && echo " Compiling in extra Epoch compatibility." - -test "$with_sound" = nas && echo " Compiling in network sound support." -test "$with_sound" = native && echo " Compiling in native sound support." -test "$with_sound" = both && echo " Compiling in both network and native sound support." -test "$old_nas" = true && echo " nas library lacks error trapping, will play synchronously" - -test "$with_database_berkdb" = yes && echo " Compiling in support for Berkeley DB." -test "$with_database_dbm" = yes && echo " Compiling in support for DBM." -test "$with_database_gnudbm" = yes && echo " Compiling in support for GNU DBM." - -test "$with_ncurses" = yes && echo " Compiling in support for ncurses." -test "$with_socks" = yes && echo " Compiling in support for SOCKS." - -test "$with_mule" = yes && echo " Compiling in Mule (multi-lingual) support." -test "$with_xim" != no && echo " Compiling in XIM (X11R5+ I18N input method) support." -test "$with_xim" = motif && echo " Using Motif to provide XIM support." -test "$with_xim" = xlib && echo " Using raw Xlib to provide XIM support." -test "$with_canna" = yes && echo " Compiling in support for Canna on Mule." -test "$with_wnn" = yes && echo " Compiling in support for WNN on Mule." -test "$with_wnn6" = yes && echo " WNN support for version 6." -test "$with_i18n3" = yes && echo " Compiling in I18N support, level 3 (doesn't currently work)." - -test "$with_cde" = yes && echo " Compiling in support for CDE." -test "$with_tooltalk" = yes && echo " Compiling in support for ToolTalk." -test "$with_offix" = yes && echo " Compiling in support for OffiX." -test "$with_mocklisp" = yes && echo " Compiling in support for Mocklisp." -test "$with_sparcworks" = yes && echo " Compiling in support for SparcWorks." -test "$with_energize" = yes && echo " Compiling in support for Lucid Energize (doesn't currently work)." -test "$with_menubars" = "lucid" && echo " Using the Lucid menubar." + echo " (Using -lgz instead of -lz.)" >> Installation +fi +test "$with_tiff" = yes && echo " Compiling in support for TIFF image conversion (not implemented)." >> Installation +test "$with_epoch" = yes && echo " Compiling in extra Epoch compatibility." >> Installation + +test "$with_sound" = nas && echo " Compiling in network sound support." >> Installation +test "$with_sound" = native && echo " Compiling in native sound support." >> Installation +test "$with_sound" = both && echo " Compiling in both network and native sound support." >> Installation +test "$old_nas" = true && echo " nas library lacks error trapping, will play synchronously" >> Installation + +test "$with_database_berkdb" = yes && echo " Compiling in support for Berkeley DB." >> Installation +test "$with_database_dbm" = yes && echo " Compiling in support for DBM." >> Installation +test "$with_database_gnudbm" = yes && echo " Compiling in support for GNU DBM." >> Installation + +test "$with_ncurses" = yes && echo " Compiling in support for ncurses." >> Installation +test "$with_socks" = yes && echo " Compiling in support for SOCKS." >> Installation + +test "$with_mule" = yes && echo " Compiling in Mule (multi-lingual) support." >> Installation +test "$with_xim" != no && echo " Compiling in XIM (X11R5+ I18N input method) support." >> Installation +test "$with_xim" = motif && echo " Using Motif to provide XIM support." >> Installation +test "$with_xim" = xlib && echo " Using raw Xlib to provide XIM support." >> Installation +test "$with_canna" = yes && echo " Compiling in support for Canna on Mule." >> Installation +test "$with_wnn" = yes && echo " Compiling in support for WNN on Mule." >> Installation +test "$with_wnn6" = yes && echo " WNN support for version 6." >> Installation +test "$with_i18n3" = yes && echo " Compiling in I18N support, level 3 (doesn't currently work)." >> Installation + +test "$with_cde" = yes && echo " Compiling in support for CDE." >> Installation +test "$with_tooltalk" = yes && echo " Compiling in support for ToolTalk." >> Installation +test "$with_offix" = yes && echo " Compiling in support for OffiX." >> Installation +test "$with_mocklisp" = yes && echo " Compiling in support for Mocklisp." >> Installation +test "$with_sparcworks" = yes && echo " Compiling in support for SparcWorks." >> Installation +test "$with_energize" = yes && echo " Compiling in support for Lucid Energize (doesn't currently work)." >> Installation +test "$with_menubars" = "lucid" && echo " Using the Lucid menubar." >> Installation if test "$with_menubars" = "motif"; then - echo " Using the Motif menubar." - echo " *WARNING* The Motif menubar is currently buggy. We recommend" - echo " that you use the Lucid menubar instead. Re-run" - echo " configure with --with-menubars='lucid'." -fi -test "$with_scrollbars" = lucid && echo " Using the Lucid scrollbar." -test "$with_scrollbars" = motif && echo " Using the Motif scrollbar." -test "$with_scrollbars" = athena && echo " Using the Athena scrollbar." -test "$with_scrollbars" = athena3d && echo " Using the Athena-3d scrollbar." -test "$with_dialogs" = motif && echo " Using the Motif dialog boxes." -test "$with_dialogs" = athena && echo " Using the Athena dialog boxes." -test "$with_dialogs" = athena3d && echo " Using the Athena-3d dialog boxes." - -test "${use_union_type}" = yes && echo " Using the union type for Lisp_Objects." -test "${debug}" = yes && echo " Compiling in extra code for debugging." -test "${memory_usage_stats}" = yes && echo " Compiling in code for checking XEmacs memory usage." -test "$usage_tracking" = yes && echo " Compiling with usage tracking active (Sun internal)." -echo " -" - + echo " Using the Motif menubar." >> Installation + echo " *WARNING* The Motif menubar is currently buggy. We recommend" >> Installation + echo " that you use the Lucid menubar instead. Re-run" >> Installation + echo " configure with --with-menubars='lucid'." >> Installation +fi +test "$with_scrollbars" = lucid && echo " Using the Lucid scrollbar." >> Installation +test "$with_scrollbars" = motif && echo " Using the Motif scrollbar." >> Installation +test "$with_scrollbars" = athena && echo " Using the Athena scrollbar." >> Installation +test "$with_scrollbars" = athena3d && echo " Using the Athena-3d scrollbar." >> Installation +test "$with_dialogs" = motif && echo " Using the Motif dialog boxes." >> Installation +test "$with_dialogs" = athena && echo " Using the Athena dialog boxes." >> Installation +test "$with_dialogs" = athena3d && echo " Using the Athena-3d dialog boxes." >> Installation + +test "${use_union_type}" = yes && echo " Using the union type for Lisp_Objects." >> Installation +test "${debug}" = yes && echo " Compiling in extra code for debugging." >> Installation +test "${memory_usage_stats}" = yes && echo " Compiling in code for checking XEmacs memory usage." >> Installation +test "$usage_tracking" = yes && echo " Compiling with usage tracking active (Sun internal)." >> Installation +echo " >> Installation +" + +test -r Installation && cat Installation # Remove any trailing slashes in these variables.
--- a/configure.in Mon Aug 13 09:19:47 2007 +0200 +++ b/configure.in Mon Aug 13 09:20:48 2007 +0200 @@ -3186,91 +3186,92 @@ Should XEmacs use the relocating allocator for buffers? ${rel_alloc} What window system should XEmacs use? ${window_system}${x_includes+ Where do we find X Windows header files? }${x_includes}${x_libraries+ - Where do we find X Windows libraries? }${x_libraries}" + Where do we find X Windows libraries? }${x_libraries}" >> Installation if test -n "$site_includes"; then - echo " Additional header files: ${site_includes}" + echo " Additional header files: ${site_includes}" >> Installation fi if test -n "$site_libraries" -a -n "$site_runtime_libraries"; then - echo " Additional libraries: ${site_libraries} ${site_runtime_libraries}" + echo " Additional libraries: ${site_libraries} ${site_runtime_libraries}" >> Installation elif test -n "$site_libraries"; then - echo " Additional libraries: ${site_libraries}" + echo " Additional libraries: ${site_libraries}" >> Installation elif test -n "$site_runtime_libraries"; then - echo " Additional libraries: ${site_runtime_libraries}" + echo " Additional libraries: ${site_runtime_libraries}" >> Installation fi if test "$with_wnn"; then - echo " Finding WNN includes with: ${wnn_includes}" - echo " Loading WNN libs with: ${wnn_libraries}" + echo " Finding WNN includes with: ${wnn_includes}" >> Installation + echo " Loading WNN libs with: ${wnn_libraries}" >> Installation fi -test "$with_socks" = yes && echo " Compiling in support for SOCKS." -test "$with_term" = yes && echo " Compiling in support for TERM." -test "$with_xauth" = yes && echo " Compiling in support for XAUTH." -test "$with_xpm" = yes && echo " Compiling in support for XPM." +test "$with_socks" = yes && echo " Compiling in support for SOCKS." >> Installation +test "$with_term" = yes && echo " Compiling in support for TERM." >> Installation +test "$with_xauth" = yes && echo " Compiling in support for XAUTH." >> Installation +test "$with_xpm" = yes && echo " Compiling in support for XPM." >> Installation if test "$with_xmu" != yes -a "$window_system" != none; then - echo " No Xmu; substituting equivalent routines." + echo " No Xmu; substituting equivalent routines." >> Installation fi -test "$with_xface" = yes && echo " Compiling in support for X-Face headers." -test "$with_gif" = yes && echo " Compiling in support for GIF image conversion." -test "$with_jpeg" = yes && echo " Compiling in support for JPEG image conversion." +test "$with_xface" = yes && echo " Compiling in support for X-Face headers." >> Installation +test "$with_gif" = yes && echo " Compiling in support for GIF image conversion." >> Installation +test "$with_jpeg" = yes && echo " Compiling in support for JPEG image conversion." >> Installation if test "$with_png" = yes -o "$with_png" = gnuz; then - echo " Compiling in support for PNG image conversion." + echo " Compiling in support for PNG image conversion." >> Installation fi if test "$with_png" = gnuz; then - echo " (Using -lgz instead of -lz.)" + echo " (Using -lgz instead of -lz.)" >> Installation fi -test "$with_tiff" = yes && echo " Compiling in support for TIFF image conversion (not implemented)." -test "$with_epoch" = yes && echo " Compiling in extra Epoch compatibility." - -test "$with_sound" = nas && echo " Compiling in network sound support." -test "$with_sound" = native && echo " Compiling in native sound support." -test "$with_sound" = both && echo " Compiling in both network and native sound support." -test "$old_nas" = true && echo " nas library lacks error trapping, will play synchronously" - -test "$with_database_berkdb" = yes && echo " Compiling in support for Berkeley DB." -test "$with_database_dbm" = yes && echo " Compiling in support for DBM." -test "$with_database_gnudbm" = yes && echo " Compiling in support for GNU DBM." - -test "$with_ncurses" = yes && echo " Compiling in support for ncurses." -test "$with_socks" = yes && echo " Compiling in support for SOCKS." - -test "$with_mule" = yes && echo " Compiling in Mule (multi-lingual) support." -test "$with_xim" != no && echo " Compiling in XIM (X11R5+ I18N input method) support." -test "$with_xim" = motif && echo " Using Motif to provide XIM support." -test "$with_xim" = xlib && echo " Using raw Xlib to provide XIM support." -test "$with_canna" = yes && echo " Compiling in support for Canna on Mule." -test "$with_wnn" = yes && echo " Compiling in support for WNN on Mule." -test "$with_wnn6" = yes && echo " WNN support for version 6." -test "$with_i18n3" = yes && echo " Compiling in I18N support, level 3 (doesn't currently work)." - -test "$with_cde" = yes && echo " Compiling in support for CDE." -test "$with_tooltalk" = yes && echo " Compiling in support for ToolTalk." -test "$with_offix" = yes && echo " Compiling in support for OffiX." -test "$with_mocklisp" = yes && echo " Compiling in support for Mocklisp." -test "$with_sparcworks" = yes && echo " Compiling in support for SparcWorks." -test "$with_energize" = yes && echo " Compiling in support for Lucid Energize (doesn't currently work)." -test "$with_menubars" = "lucid" && echo " Using the Lucid menubar." +test "$with_tiff" = yes && echo " Compiling in support for TIFF image conversion (not implemented)." >> Installation +test "$with_epoch" = yes && echo " Compiling in extra Epoch compatibility." >> Installation + +test "$with_sound" = nas && echo " Compiling in network sound support." >> Installation +test "$with_sound" = native && echo " Compiling in native sound support." >> Installation +test "$with_sound" = both && echo " Compiling in both network and native sound support." >> Installation +test "$old_nas" = true && echo " nas library lacks error trapping, will play synchronously" >> Installation + +test "$with_database_berkdb" = yes && echo " Compiling in support for Berkeley DB." >> Installation +test "$with_database_dbm" = yes && echo " Compiling in support for DBM." >> Installation +test "$with_database_gnudbm" = yes && echo " Compiling in support for GNU DBM." >> Installation + +test "$with_ncurses" = yes && echo " Compiling in support for ncurses." >> Installation +test "$with_socks" = yes && echo " Compiling in support for SOCKS." >> Installation + +test "$with_mule" = yes && echo " Compiling in Mule (multi-lingual) support." >> Installation +test "$with_xim" != no && echo " Compiling in XIM (X11R5+ I18N input method) support." >> Installation +test "$with_xim" = motif && echo " Using Motif to provide XIM support." >> Installation +test "$with_xim" = xlib && echo " Using raw Xlib to provide XIM support." >> Installation +test "$with_canna" = yes && echo " Compiling in support for Canna on Mule." >> Installation +test "$with_wnn" = yes && echo " Compiling in support for WNN on Mule." >> Installation +test "$with_wnn6" = yes && echo " WNN support for version 6." >> Installation +test "$with_i18n3" = yes && echo " Compiling in I18N support, level 3 (doesn't currently work)." >> Installation + +test "$with_cde" = yes && echo " Compiling in support for CDE." >> Installation +test "$with_tooltalk" = yes && echo " Compiling in support for ToolTalk." >> Installation +test "$with_offix" = yes && echo " Compiling in support for OffiX." >> Installation +test "$with_mocklisp" = yes && echo " Compiling in support for Mocklisp." >> Installation +test "$with_sparcworks" = yes && echo " Compiling in support for SparcWorks." >> Installation +test "$with_energize" = yes && echo " Compiling in support for Lucid Energize (doesn't currently work)." >> Installation +test "$with_menubars" = "lucid" && echo " Using the Lucid menubar." >> Installation if test "$with_menubars" = "motif"; then - echo " Using the Motif menubar." - echo " *WARNING* The Motif menubar is currently buggy. We recommend" - echo " that you use the Lucid menubar instead. Re-run" - echo " configure with --with-menubars='lucid'." + echo " Using the Motif menubar." >> Installation + echo " *WARNING* The Motif menubar is currently buggy. We recommend" >> Installation + echo " that you use the Lucid menubar instead. Re-run" >> Installation + echo " configure with --with-menubars='lucid'." >> Installation fi -test "$with_scrollbars" = lucid && echo " Using the Lucid scrollbar." -test "$with_scrollbars" = motif && echo " Using the Motif scrollbar." -test "$with_scrollbars" = athena && echo " Using the Athena scrollbar." -test "$with_scrollbars" = athena3d && echo " Using the Athena-3d scrollbar." -test "$with_dialogs" = motif && echo " Using the Motif dialog boxes." -test "$with_dialogs" = athena && echo " Using the Athena dialog boxes." -test "$with_dialogs" = athena3d && echo " Using the Athena-3d dialog boxes." - -test "${use_union_type}" = yes && echo " Using the union type for Lisp_Objects." -test "${debug}" = yes && echo " Compiling in extra code for debugging." -test "${memory_usage_stats}" = yes && echo " Compiling in code for checking XEmacs memory usage." -test "$usage_tracking" = yes && echo " Compiling with usage tracking active (Sun internal)." -echo " +test "$with_scrollbars" = lucid && echo " Using the Lucid scrollbar." >> Installation +test "$with_scrollbars" = motif && echo " Using the Motif scrollbar." >> Installation +test "$with_scrollbars" = athena && echo " Using the Athena scrollbar." >> Installation +test "$with_scrollbars" = athena3d && echo " Using the Athena-3d scrollbar." >> Installation +test "$with_dialogs" = motif && echo " Using the Motif dialog boxes." >> Installation +test "$with_dialogs" = athena && echo " Using the Athena dialog boxes." >> Installation +test "$with_dialogs" = athena3d && echo " Using the Athena-3d dialog boxes." >> Installation + +test "${use_union_type}" = yes && echo " Using the union type for Lisp_Objects." >> Installation +test "${debug}" = yes && echo " Compiling in extra code for debugging." >> Installation +test "${memory_usage_stats}" = yes && echo " Compiling in code for checking XEmacs memory usage." >> Installation +test "$usage_tracking" = yes && echo " Compiling with usage tracking active (Sun internal)." >> Installation +echo " >> Installation " +test -r Installation && cat Installation dnl ############################################################################ dnl # Now generate! # dnl ############################################################################
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/etc/categories Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,37 @@ +# Possible categories for a PR. +# +# Any line which begins with a `#' is considered a comment, and GNATS +# will ignore it. +# +# Each entry has the format: +# +# category:description:responsible:notify +# +# * `category' is the name of the classification for the PR. +# * `description' can be a normal text description for the +# category, like "Development Tools" for the `tools' category. +# * `responsible' gives the name (which can be found in the remote +# file) of the person who will be given responsibility for any PR +# appearing in this category. +# * `notify' are other email addresses which should be given copies of +# any PR in this category. +# +# The following category is mandatory for GNATS to work. +# +pending:Category for faulty PRs:gnats-admin: +# +# Sample categories: +# +auxillary:Auxillary Programs:gnats-admin: +configuration:Configuration:gnats-admin:mrb@eng.sun.com +documentation:Documentation Bug:gnats-admin:weiner@infodock.com +frames:X11 Frames:gnats-admin: +i18n:I18n Internationalization:gnats-admin:mrb@eng.sun.com +lisp:Emacs Lisp code:gnats-admin: +menubars:X11 menubars:gnats-admin: +misc:Miscellaneous:gnats-admin: +performance:Performance Issues:gnats-admin:dmoore@ucsd.edu +redisplay:Redisplay Issues:gnats-admin:cthomp@xemacs.org +scrollbars:X11 scrollbars:gnats-amdin:mrb@eng.sun.com +tooblbars:X11 toolbars:gnats-admin: +test:*Test Category:gnats-admin:
--- a/info/dir Mon Aug 13 09:19:47 2007 +0200 +++ b/info/dir Mon Aug 13 09:20:48 2007 +0200 @@ -43,6 +43,8 @@ XEmacs User's Guide for XEmacs 20.0. * XEmacs-FAQ:: XEmacs Frequently Asked Questions for 20.0. * Internals:: Guide to the internals of XEmacs. +* send-pr:: Submitting Bug Reports +* gnats:: GNU Problem Report Management System Packages:
--- a/lib-src/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/lib-src/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,17 @@ +Mon Mar 17 10:12:03 1997 Steven L Baur <steve@altair.xemacs.org> + + * Makefile.in.in (INSTALLABLE_SCRIPTS): Add install-sid and + send-pr (from GNATS). + + * update-elc.sh (prune_vc): Use full path to cleantree.el. + (NUMTOCOMPILE): Remove useless rule to recompile out-of-date .elcs. + +Sun Mar 16 21:13:29 1997 Steven L Baur <steve@altair.xemacs.org> + + * install-sid: New file (GNATS integration). + + * send-pr: New file (GNATS integration). + Fri Mar 14 17:59:57 1997 Steven L Baur <steve@altair.xemacs.org> * update-elc.sh (ignore_dirs): Build VM with `make autoload'.
--- a/lib-src/Makefile.in.in Mon Aug 13 09:19:47 2007 +0200 +++ b/lib-src/Makefile.in.in Mon Aug 13 09:20:48 2007 +0200 @@ -102,7 +102,7 @@ /* Things that a user might actually run, which should be installed in bindir. */ INSTALLABLES = etags ctags emacsclient b2m gnuclient gnuattach gnudoit -INSTALLABLE_SCRIPTS = rcs-checkin pstogif +INSTALLABLE_SCRIPTS = rcs-checkin pstogif install-sid send-pr /* Things that Emacs runs internally, or during the build process, which should not be installed in bindir. */ @@ -115,7 +115,7 @@ /* Like UTILITIES, but they are not system-dependent, and should not be deleted by the distclean target. */ TM_SCRIPTS=tm-au tm-file tm-html tm-image tm-mpeg tm-plain tm-ps tmdecode -SCRIPTS= rcs2log vcdiff $(TM_SCRIPTS) +SCRIPTS= rcs2log vcdiff install-sid send-pr $(TM_SCRIPTS) EXECUTABLES= ${UTILITIES} ${INSTALLABLES} ${SCRIPTS} ${INSTALLABLE_SCRIPTS}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lib-src/install-sid Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,88 @@ +#!/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.101 + +BINDIR=/usr/bin + +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=. + +examinebindir=yes + +if [ "$examinebindir" = yes ] && [ -f $BINDIR/send-pr ]; then + SPPATHLIST=$BINDIR/send-pr +else + if [ -f $path/send-pr ]; then + SPPATHLIST=$path/send-pr + else + echo "$COMMAND: cannot find \`$BINDIR/send-pr' or \`$path/send-pr'" >&2 + exit 1 + fi +fi + +trap 'rm -f $TEMP ; exit 0' 0 +trap 'echo "$COM: Aborting ..."; rm -f $TEMP ; exit 1' 1 2 3 13 15 + +for SPPATH in $SPPATHLIST; do + 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 +done + +echo "$COMMAND: \`$SUBMITTER' is now the default submitter ID for send-pr" + +exit 0
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lib-src/send-pr Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,529 @@ +#!/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@cygnus.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.101 + +# The submitter-id for your site. +SUBMITTER=unknown + +# Where the GNATS directory lives, if at all. +[ -z "$GNATS_ROOT" ] && +GNATS_ROOT=/usr/lib/gnats/gnats-db + +# The default mail address for PR submissions. +GNATS_ADDR=bugs@altair.xemacs.org + +# Where the gnats category tree lives. +DATADIR=/usr/share + +# If we've been moved around, try using GCC_EXEC_PREFIX. +[ ! -d $DATADIR/gnats -a -d "$GCC_EXEC_PREFIX" ] && + DATADIR=${GCC_EXEC_PREFIX}../../../lib + + +# The default release for this host. +DEFAULT_RELEASE="gnats-3.101" + +# The default organization. +DEFAULT_ORGANIZATION="XEmacs Users" + +# The default site to look for. +GNATS_SITE=altair.xemacs.org + +# 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/lib/sendmail -oi -t" + +# How to read the passwd database. +PASSWD="cat /etc/passwd" + +ECHON=bsd + +if [ $ECHON = bsd ] ; then + ECHON1="echo -n" + ECHON2= +elif [ $ECHON = sysv ] ; then + ECHON1=echo + ECHON2='\c' +else + ECHON1=echo + ECHON2= +fi + +# + +if [ -z "$TMPDIR" ]; then + TMPDIR=/tmp +else + if [ "`echo $TMPDIR | grep '/$'`" != "" ]; then + TMPDIR="`echo $TMPDIR | sed -e 's,/$,,'`" + fi +fi + +TEMP=$TMPDIR/p$$ +BAD=$TMPDIR/pbad$$ +REF=$TMPDIR/pf$$ + +# find a user name +if [ "$LOGNAME" = "" ]; then + if [ "$USER" != "" ]; then + LOGNAME="$USER" + else + LOGNAME="UNKNOWN" + fi +fi + +FROM="$LOGNAME" +if [ -z "$REPLYTO" ]; then + REPLYTO="$LOGNAME" +fi + +# 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`" +else + # Must use temp file due to incompatibilities in quoting behavior + # and to protect shell metacharacters in the expansion of $LOGNAME + $PASSWD | grep "^$LOGNAME:" | awk -F: '{print $5}' | 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] [-s severity] + [-c address] [--request-id] [--version]" +REMOVE= +BATCH= +CC= +SEVERITY_C= + +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 ;; + -c | --cc) if [ $# -eq 1 ]; then echo "$USAGE"; exit 1; fi + shift ; CC="$1" + ;; + -s | --severity) if [ $# -eq 1 ]; then echo "$USAGE"; exit 1; fi + shift ; SEVERITY_C="$1" + ;; + -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" ] && [ "$USER_GNATS_SITE" != "$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)>' +if [ -z "$SEVERITY_C" ]; then + SEVERITY_C='<[ non-critical | serious | critical ] (one line)>' +fi +PRIORITY_C='<[ low | medium | high ] (one line)>' +CATEGORY_C='<name of the product (one line)>' +CLASS_C='<[ sw-bug | doc-bug | change-request | support ] (one line)>' +RELEASE_C='<release number or tag (one line)>' +ENVIRONMENT_C='<machine, os, target, libraries (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: $REPLYTO +Cc: $CC +X-send-pr-version: $VERSION + + +>Submitter-Id: $SUBMITTER +>Originator: $ORIGINATOR +>Organization: +${ORGANIZATION- $ORGANIZATION_C} +>Confidential: $CONFIDENTIAL_C +>Synopsis: $SYNOPSIS_C +>Severity: $SEVERITY_C +>Priority: $PRIORITY_C +>Category: $CATEGORY_C +>Class: $CLASS_C +>Release: ${DEFAULT_RELEASE-$RELEASE_C} +>Environment: + $ENVIRONMENT_C +`[ -n "$SYSTEM" ] && echo System: $SYSTEM` +`[ -n "$ARCH" ] && echo Architecture: $ARCH` +`[ -n "$MACHINE" ] && echo Machine: $MACHINE` +>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
--- a/lib-src/update-elc.sh Mon Aug 13 09:19:47 2007 +0200 +++ b/lib-src/update-elc.sh Mon Aug 13 09:20:48 2007 +0200 @@ -54,7 +54,7 @@ prune_vc="( -name SCCS -o -name RCS -o -name CVS ) -prune -o" -$EMACS -batch -q -no-site-file -l cleantree -f batch-remove-old-elc lisp +$EMACS -batch -q -l `pwd`/lisp/prim/cleantree -f batch-remove-old-elc lisp # $els is a list of all .el files # $elcs is a list of all .elc files @@ -156,11 +156,4 @@ xargs -t -n$NUMTOCOMPILE $BYTECOMP -f batch-byte-compile echo "Compiling files without .elc... Done" - -echo "Compiling files with out-of-date .elc..." -find lisp/* $prune_vc -type d -print | \ - sed "$ignore_pattern" | \ - xargs -t $BYTECOMP -f batch-byte-recompile-directory -echo "Compiling files with out-of-date .elc... Done" - eval "$make_special_commands"
--- a/lisp/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,15 @@ +Mon Mar 17 15:34:06 1997 Steven L Baur <steve@altair.xemacs.org> + + * comint/comint.el (comint-input-setup): Require comint-xemacs. + + * utils/autoload.el (autoload-snarf-defcustom): Don't snarf from + auto-autoloads.el. + + * comint/comint-xemacs.el: New file. Contains face declarations + for comint. + + * comint/comint.el: Remove inline defface. + Sat Mar 15 15:14:06 1997 Steven L Baur <steve@altair.xemacs.org> * prim/loadup.el: Add prim/auto-customize.elc to dumped files.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lisp/comint/comint-xemacs.el Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,53 @@ +;;; comint-xemacs.el --- Face customizations for comint + +;; Copyright (C) 1997 by Free Software Foundation, Inc. + +;; Author: Steven L Baur <steve@altair.xemacs.org> +;; Keywords: help, faces + +;; This file is part of XEmacs. + +;; XEmacs 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. + +;; XEmacs 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 XEmacs; see the file COPYING. If not, write to the Free +;; Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +;; 02111-1307, USA. + +;;; Synched up with: Not in FSF + +;;; Commentary: + +;; Declare customizable faces for comint outside the main code so it can +;; be dumped with XEmacs. + +;;; Code: + +(defface comint-input-face '((((class color) + (background dark)) + (:foreground "red")) + (((class color) + (background light)) + (:foreground "blue")) + (((class mono)) + (:bold t)) + (((class grayscale)) + (:bold t)) + (t + (:bold t))) + "How to display user input for comint shells." + :group 'comint-input-face) + + + +(provide 'comint-xemacs) + +;;; comint-xemacs.el ends here
--- a/lisp/comint/comint.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/comint/comint.el Mon Aug 13 09:20:48 2007 +0200 @@ -355,21 +355,6 @@ (put 'comint-scroll-show-maximum-output 'permanent-local t) (put 'comint-ptyp 'permanent-local t) -(defface comint-input-face '((((class color) - (background dark)) - (:foreground "red")) - (((class color) - (background light)) - (:foreground "blue")) - (((class mono)) - (:bold t)) - (((class grayscale)) - (:bold t)) - (t - (:bold t))) - "How to display user input for comint shells." - :group 'comint-input-face) - (defun comint-mode () @@ -1385,6 +1370,7 @@ (defun comint-input-setup () "Insure the comint-input-extent is ready." + (require 'comint-xemacs) (setq comint-input-extent (make-extent (point) (point-max))) (set-extent-property comint-input-extent 'detachable nil) (set-extent-property comint-input-extent 'start-closed t)
--- a/lisp/custom/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,18 @@ +Mon Mar 17 11:32:51 1997 Per Abrahamsen <abraham@dina.kvl.dk> + + * Version 1.64 released. + +Mon Mar 17 10:43:10 1997 Per Abrahamsen <abraham@dina.kvl.dk> + + * cus-edit.el (custom-group-menu-create): Split definition into + XEmacs and Emacs. XEmacs uses :filter. Emacs limits + `custom-menu-nesting'. + (custom-menu-create): Do noy limit `custom-menu-nesting' here. + (custom-menu-update): Removed XEmacs support. + + * custom.el (custom-help-menu): Use `custom-menu-create' in XEmacs + :filter. + Fri Mar 14 18:03:55 1997 Per Abrahamsen <abraham@dina.kvl.dk> * Version 1.63 released.
--- a/lisp/custom/cus-edit.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/cus-edit.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: help, faces -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary: @@ -1803,9 +1803,19 @@ ':style 'toggle ':selected symbol))) -(defun custom-group-menu-create (widget symbol) - "Ignoring WIDGET, create a menu entry for customization group SYMBOL." - (custom-menu-create symbol)) +(if (string-match "XEmacs" emacs-version) + ;; XEmacs can create menus dynamically. + (defun custom-group-menu-create (widget symbol) + "Ignoring WIDGET, create a menu entry for customization group SYMBOL." + `( ,(custom-unlispify-menu-entry symbol t) + :filter (lambda (&rest junk) + (cdr (custom-menu-create ',symbol))))) + ;; But emacs can't. + (defun custom-group-menu-create (widget symbol) + "Ignoring WIDGET, create a menu entry for customization group SYMBOL." + ;; Limit the nesting. + (let ((custom-menu-nesting (1- custom-menu-nesting))) + (custom-menu-create symbol)))) (defun custom-menu-create (symbol &optional name) "Create menu for customization group SYMBOL. @@ -1817,10 +1827,9 @@ (let ((item (vector name `(custom-buffer-create '((,symbol custom-group))) t))) - (if (and (> custom-menu-nesting 0) + (if (and (>= custom-menu-nesting 0) (< (length (get symbol 'custom-group)) widget-menu-max-size)) - (let ((custom-menu-nesting (1- custom-menu-nesting)) - (custom-prefix-list (custom-prefix-add symbol + (let ((custom-prefix-list (custom-prefix-add symbol custom-prefix-list))) (custom-load-symbol symbol) `(,(custom-unlispify-menu-entry symbol t) @@ -1841,17 +1850,11 @@ (add-hook 'custom-define-hook 'custom-menu-reset) (let* ((emacs (widget-apply '(custom-group) :custom-menu 'emacs)) (menu `(,(car custom-help-menu) - ,emacs - ,@(cdr (cdr custom-help-menu))))) - (if (fboundp 'add-submenu) - (progn - (add-submenu '("Options") menu) - (cdr emacs)) - (let ((map (easy-menu-create-keymaps (car menu) (cdr menu)))) - (define-key global-map [menu-bar help-menu customize-menu] - (cons (car menu) map)) - (when (fboundp 'x-popup-menu) - (x-popup-menu event map)))))) + ,emacs + ,@(cdr (cdr custom-help-menu))))) + (let ((map (easy-menu-create-keymaps (car menu) (cdr menu)))) + (define-key global-map [menu-bar help-menu customize-menu] + (cons (car menu) map))))) ;;; Dependencies.
--- a/lisp/custom/cus-face.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/cus-face.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: help, faces -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary:
--- a/lisp/custom/custom.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/custom.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: help, faces -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary: @@ -297,15 +297,17 @@ ;;; Menu support -(defconst custom-help-menu `("Customize" - ,(if (string-match "XEmacs" emacs-version) - '("Emacs" :filter custom-menu-update) - ["Update menu..." custom-menu-update t]) - ["Group..." customize t] - ["Variable..." customize-variable t] - ["Face..." customize-face t] - ["Saved..." customize-customized t] - ["Apropos..." customize-apropos t]) +(defconst custom-help-menu + `("Customize" + ,(if (string-match "XEmacs" emacs-version) + '("Emacs" :filter (lambda (&rest junk) + (cdr (custom-menu-create 'emacs)))) + ["Update menu..." custom-menu-update t]) + ["Group..." customize t] + ["Variable..." customize-variable t] + ["Face..." customize-face t] + ["Saved..." customize-customized t] + ["Apropos..." customize-apropos t]) "Customize menu") (defun custom-menu-reset () @@ -319,7 +321,8 @@ (easy-menu-create-keymaps (car custom-help-menu) (cdr custom-help-menu)))))) -(unless (string-match "XEmacs" emacs-version) +(if (string-match "XEmacs" emacs-version) + (autoload 'custom-menu-create "cus-edit") (custom-menu-reset)) ;;; The End.
--- a/lisp/custom/wid-browse.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/wid-browse.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: extensions -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary:
--- a/lisp/custom/wid-edit.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/wid-edit.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: extensions -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary:
--- a/lisp/custom/widget-example.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/widget-example.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: help, extensions, faces, hypermedia -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ (require 'widget)
--- a/lisp/custom/widget.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/custom/widget.el Mon Aug 13 09:20:48 2007 +0200 @@ -4,7 +4,7 @@ ;; ;; Author: Per Abrahamsen <abraham@dina.kvl.dk> ;; Keywords: help, extensions, faces, hypermedia -;; Version: 1.63 +;; Version: 1.64 ;; X-URL: http://www.dina.kvl.dk/~abraham/custom/ ;;; Commentary:
--- a/lisp/gnats/send-pr.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnats/send-pr.el Mon Aug 13 09:20:48 2007 +0200 @@ -64,7 +64,7 @@ (defconst send-pr::version "3.101") -(defvar gnats:root "" +(defvar gnats:root "/usr/lib/gnats/gnats-db" "*The top of the tree containing the GNATS database.") ;;;;--------------------------------------------------------------------------- @@ -129,13 +129,13 @@ ret)) ;; const because it must match the script's value -(defconst send-pr:datadir (or (gnats::get-config "DATADIR") "/usr/local/share") +(defconst send-pr:datadir (or (gnats::get-config "DATADIR") "/usr/share") "*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") "cygnus") + (or (gnats::get-config "GNATS_SITE") "altair.xemacs.org") "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 @@ -274,8 +274,9 @@ (save-excursion ;; Clear cruft inserted by bdamaged .cshrcs (goto-char 1) - (re-search-forward "^SEND-PR:") - (delete-region 1 (match-beginning 0))))) + ;; XEmacs change + (when (re-search-forward "^SEND-PR:" nil t) + (delete-region 1 (match-beginning 0)))))) (set-buffer-modified-p nil) (send-pr:send-pr-mode) (setq send-pr:::site site)
--- a/lisp/gnus/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,80 @@ +Tue Mar 18 00:35:06 1997 Lars Magne Ingebrigtsen <larsi@menja.ifi.uio.no> + + * gnus.el: Gnus v5.4.28 is released. + +Mon Mar 17 18:36:11 1997 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * gnus-sum.el (gnus-update-marks): Use `list' instead of + `articles'. + + * nndoc.el (nndoc-rfc822-forward-type-p): Renamed. + (nndoc-rfc822-forward-body-end-function): Ditto. + +Mon Mar 17 17:35:35 1997 Lars Magne Ingebrigtsen <larsi@menja.ifi.uio.no> + + * gnus.el: Gnus v5.4.27 is released. + +Mon Mar 17 15:59:11 1997 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * nndoc.el (nndoc-x400-forward-type-p): New function. + (nndoc-x400-forward-body-end-function): Ditto. + + * nnfolder.el (nnfolder-adjust-min-active): Be in the right + buffer. + +Sat Mar 15 16:09:44 1997 Steven L Baur <steve@altair.xemacs.org> + + * message.el (message-post-method): Fix typo. + + * gnus-load.el (message-sending): Fix typo. + +Mon Mar 17 15:47:59 1997 Gordon Matzigkeit <gord@m-tech.ab.ca> + + * message.el (message-set-auto-save-file-name): Expand before + temping. + +Mon Mar 17 15:05:44 1997 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * gnus-sum.el (gnus-update-marks): Get rid of article entries of + articles with the default score. + + * gnus-group.el (gnus-group-read-ephemeral-group): Be more careful + when uniquifying methods. + + * gnus-sum.el (gnus-execute-command): Insert asynch into buffer. + + * nnfolder.el (nnfolder-possibly-change-group): Didn't set the + current group. + +Mon Mar 17 15:03:02 1997 Paul Stodghill <stodghil@cs.cornell.edu> + + * gnus-srvr.el (gnus-server-prepare): Would infloop. + +Mon Mar 17 06:37:07 1997 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * nnmail.el (nnmail-crosspost-link-function): Change default on + NT. + +Fri Mar 14 12:07:12 1997 Steven L Baur <steve@altair.xemacs.org> + + * gnus-msg.el (gnus-extended-version): Add XEmacs beta # to + default X-Mailer/X-Newsreader. + +Fri Mar 14 20:57:03 1997 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * nnfolder.el (nnfolder-possibly-change-group): Check folder + buffer. + + * nnheader.el (nnheader-parse-head): Understand Message-ID with + spaces. + * gnus-sum.el (gnus-get-newsgroup-headers): Ditto. + (gnus-group-make-articles-read): Doc fix. + + * nnml.el (nnml-generate-nov-databases-1): Made interactive. + + * gnus-msg.el (gnus-inews-narrow-to-headers): Removed. + (gnus-post-news): Add `to-list' to the right group. + Fri Mar 14 20:11:01 1997 Lars Magne Ingebrigtsen <larsi@menja.ifi.uio.no> * gnus.el: Gnus v5.4.26 is released. @@ -74,11 +151,6 @@ * nnfolder.el (nnfolder-generate-active-file): Didn't work. -Fri Mar 14 12:07:12 1997 Steven L Baur <steve@altair.xemacs.org> - - * gnus-msg.el (gnus-extended-version): Add XEmacs beta # to - default X-Mailer/X-Newsreader. - Sun Mar 9 18:38:37 1997 Lars Magne Ingebrigtsen <larsi@menja.ifi.uio.no> * gnus.el: Gnus v5.4.25 is released.
--- a/lisp/gnus/gnus-group.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus-group.el Mon Aug 13 09:20:48 2007 +0200 @@ -1560,10 +1560,12 @@ ;; Transform the select method into a unique server. (let ((saddr (intern (format "%s-address" (car method))))) (setq method (gnus-copy-sequence method)) - (unless (assq saddr method) - (nconc method `((,saddr ,(cadr method))))) - (setf (cadr method) (format "%s-%d" (cadr method) - (incf gnus-ephemeral-group-server)))) + (require (car method)) + (when (boundp saddr) + (unless (assq saddr method) + (nconc method `((,saddr ,(cadr method))))) + (setf (cadr method) (format "%s-%d" (cadr method) + (incf gnus-ephemeral-group-server))))) (let ((group (if (gnus-group-foreign-p group) group (gnus-group-prefixed-name group method)))) (gnus-sethash
--- a/lisp/gnus/gnus-load.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus-load.el Mon Aug 13 09:20:48 2007 +0200 @@ -5,12 +5,10 @@ (put 'nnmail 'custom-loads '("nnmail")) (put 'gnus-article-emphasis 'custom-loads '("gnus-art")) (put 'gnus-article-headers 'custom-loads '("gnus-sum" "gnus-art")) -(put 'gnus-newsrc 'custom-loads '("gnus-start")) (put 'nnmail-procmail 'custom-loads '("nnmail")) (put 'gnus-score-kill 'custom-loads '("gnus-kill")) (put 'gnus-visual 'custom-loads '("smiley" "gnus" "gnus-picon" "gnus-art" "earcon")) (put 'gnus-score-expire 'custom-loads '("gnus-score" "gnus-kill")) -(put 'gnus-exit 'custom-loads '("gnus-group")) (put 'gnus-summary-maneuvering 'custom-loads '("gnus-sum")) (put 'gnus-start 'custom-loads '("gnus" "gnus-util" "gnus-start" "gnus-int" "gnus-group")) (put 'gnus-extract-view 'custom-loads '("gnus-uu" "gnus-sum")) @@ -28,7 +26,6 @@ (put 'gnus-summary-exit 'custom-loads '("gnus-sum")) (put 'news 'custom-loads '("message" "gnus")) (put 'gnus 'custom-loads '("nnmail" "gnus" "gnus-win" "gnus-uu" "gnus-eform" "gnus-dup" "gnus-demon" "gnus-cache" "gnus-async" "gnus-art")) -(put 'gnus-server 'custom-loads '("gnus")) (put 'gnus-summary-visual 'custom-loads '("gnus-sum")) (put 'gnus-group-listing 'custom-loads '("gnus-group")) (put 'gnus-score 'custom-loads '("gnus" "gnus-nocem")) @@ -38,7 +35,6 @@ (put 'gnus-score-decay 'custom-loads '("gnus-score")) (put 'help 'custom-loads '("cus-edit")) (put 'gnus-nocem 'custom-loads '("gnus-nocem")) -(put 'gnus-group-visual 'custom-loads '("gnus-group")) (put 'gnus-cite 'custom-loads '("gnus-cite")) (put 'gnus-demon 'custom-loads '("gnus-demon")) (put 'gnus-message 'custom-loads '("message")) @@ -56,6 +52,7 @@ (put 'external 'custom-loads '("cus-edit")) (put 'message-headers 'custom-loads '("message")) (put 'message-forwarding 'custom-loads '("message")) +(put 'message-faces 'custom-loads '("message")) (put 'environment 'custom-loads '("cus-edit")) (put 'gnus-article-mime 'custom-loads '("gnus-sum" "gnus-art")) (put 'gnus-duplicate 'custom-loads '("gnus-dup")) @@ -63,7 +60,7 @@ (put 'widgets 'custom-loads '("wid-edit" "wid-browse")) (put 'earcon 'custom-loads '("earcon")) (put 'hypermedia 'custom-loads '("wid-edit")) -(put 'gnus-group-levels 'custom-loads '("gnus-start" "gnus-group")) +(put 'gnus-group-levels 'custom-loads '("gnus-group")) (put 'gnus-summary-format 'custom-loads '("gnus-sum")) (put 'gnus-files 'custom-loads '("nnmail" "gnus")) (put 'gnus-windows 'custom-loads '("gnus-win")) @@ -76,10 +73,9 @@ (put 'gnus-article-saving 'custom-loads '("gnus-art")) (put 'nnmail-expire 'custom-loads '("nnmail")) (put 'message-mail 'custom-loads '("message")) -(put 'faces 'custom-loads '("wid-edit" "cus-edit" "gnus")) +(put 'faces 'custom-loads '("wid-edit" "cus-edit" "message" "gnus")) (put 'gnus-summary-various 'custom-loads '("gnus-sum")) (put 'applications 'custom-loads '("cus-edit")) -(put 'gnus-start-server 'custom-loads '("gnus-start")) (put 'gnus-extract-archive 'custom-loads '("gnus-uu")) (put 'message 'custom-loads '("message")) (put 'message-sending 'custom-loads '("message")) @@ -89,17 +85,14 @@ (put 'gnus-extract-post 'custom-loads '("gnus-uu")) (put 'mail 'custom-loads '("message" "gnus")) (put 'gnus-summary-sort 'custom-loads '("gnus-sum")) -(put 'gnus-group-new 'custom-loads '("gnus-start")) (put 'customize 'custom-loads '("wid-edit" "custom" "cus-face" "cus-edit")) (put 'nnmail-split 'custom-loads '("nnmail")) (put 'gnus-asynchronous 'custom-loads '("gnus-async")) -(put 'gnus-dribble-file 'custom-loads '("gnus-start")) (put 'gnus-article-highlight 'custom-loads '("gnus-art")) (put 'gnus-extract 'custom-loads '("gnus-uu")) (put 'gnus-article 'custom-loads '("gnus-cite" "gnus-art")) (put 'gnus-group-foreign 'custom-loads '("gnus-group")) (put 'programming 'custom-loads '("cus-edit")) -(put 'message-sending 'custom-loads '("message")) (put 'nnmail-prepare 'custom-loads '("nnmail")) (put 'picons 'custom-loads '("gnus-picon")) (put 'gnus-article-signature 'custom-loads '("gnus-art"))
--- a/lisp/gnus/gnus-msg.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus-msg.el Mon Aug 13 09:20:48 2007 +0200 @@ -407,7 +407,7 @@ (message-mail (or to-address to-list)) ;; Arrange for mail groups that have no `to-address' to ;; get that when the user sends off the mail. - (push (list 'gnus-inews-add-to-address group) + (push (list 'gnus-inews-add-to-address pgroup) message-send-actions)) (set-buffer gnus-article-copy) (message-wide-reply to-address))) @@ -471,16 +471,6 @@ ;; Use the normal select method. (t gnus-select-method)))) -(defun gnus-inews-narrow-to-headers () - (widen) - (narrow-to-region - (goto-char (point-min)) - (or (and (re-search-forward - (concat "^" (regexp-quote mail-header-separator) "$") nil t) - (match-beginning 0)) - (point-max))) - (goto-char (point-min))) - ;;; ;;; Check whether the message has been sent already. ;;; @@ -490,7 +480,7 @@ (defun gnus-inews-reject-message () "Check whether this message has already been sent." (when gnus-sent-message-ids-file - (let ((message-id (save-restriction (gnus-inews-narrow-to-headers) + (let ((message-id (save-restriction (message-narrow-to-headers) (mail-fetch-field "message-id"))) end) (when message-id @@ -754,7 +744,7 @@ (save-excursion (save-restriction (widen) - (gnus-inews-narrow-to-headers) + (message-narrow-to-headers) (let (gnus-deletable-headers) (if (message-news-p) (message-generate-headers message-required-news-headers) @@ -955,7 +945,7 @@ "Insert Gcc headers based on `gnus-outgoing-message-group'." (save-excursion (save-restriction - (gnus-inews-narrow-to-headers) + (message-narrow-to-headers) (let* ((group gnus-outgoing-message-group) (gcc (cond ((gnus-functionp group) @@ -1014,7 +1004,7 @@ (setq groups (list groups))) (save-excursion (save-restriction - (gnus-inews-narrow-to-headers) + (message-narrow-to-headers) (goto-char (point-max)) (insert "Gcc: ") (if (and gnus-newsgroup-name
--- a/lisp/gnus/gnus-srvr.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus-srvr.el Mon Aug 13 09:20:48 2007 +0200 @@ -211,7 +211,9 @@ (push (cdar alist) done) (cdr (setq server (pop alist))) (when (and server (car server) (cdr server)) - (gnus-server-insert-server-line (car server) (cdr server))))) + (gnus-server-insert-server-line (car server) (cdr server)))) + (when (member (cdar alist) done) + (pop alist))) ;; Then we insert the list of servers that have been opened in ;; this session. (while opened
--- a/lisp/gnus/gnus-sum.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus-sum.el Mon Aug 13 09:20:48 2007 +0200 @@ -126,7 +126,8 @@ (const more) (sexp :menu-tag "all" t))) -(defcustom gnus-summary-thread-gathering-function 'gnus-gather-threads-by-subject +(defcustom gnus-summary-thread-gathering-function + 'gnus-gather-threads-by-subject "Function used for gathering loose threads. There are two pre-defined functions: `gnus-gather-threads-by-subject', which only takes Subjects into consideration; and @@ -3819,12 +3820,28 @@ type list newmarked symbol) (when info ;; Add all marks lists that are non-nil to the list of marks lists. - (while types - (setq type (pop types)) + (while (setq type (pop types)) (when (setq list (symbol-value (setq symbol (intern (format "gnus-newsgroup-%s" (car type)))))) + + ;; Get rid of the entries of the articles that have the + ;; default score. + (when (and (eq (cdr type) 'score) + gnus-save-score + list) + (let* ((arts list) + (prev (cons nil articles)) + (all prev)) + (while arts + (if (or (not (consp (car arts))) + (= (cdar arts) gnus-summary-default-score)) + (setcdr prev (cdr arts)) + (setq prev arts)) + (setq arts (cdr arts))) + (setq list (cdr all)))) + (push (cons (cdr type) (if (memq (cdr type) uncompressed) list (gnus-compress-sequence @@ -3972,7 +3989,7 @@ xref-hashtb))))) (defun gnus-group-make-articles-read (group articles) - "Update the info of GROUP to say that only ARTICLES are unread." + "Update the info of GROUP to say that ARTICLES are read." (let* ((num 0) (entry (gnus-gethash group gnus-newsrc-hashtb)) (info (nth 2 entry)) @@ -4104,8 +4121,10 @@ ;; Message-ID. (progn (goto-char p) - (setq id (if (search-forward "\nmessage-id: " nil t) - (nnheader-header-value) + (setq id (if (search-forward "\nmessage-id:" nil t) + (buffer-substring + (1- (or (search-forward "<" nil t) (point))) + (or (search-forward ">" nil t) (point))) ;; If there was no message-id, we just fake one ;; to make subsequent routines simpler. (nnheader-generate-fake-message-id)))) @@ -8344,16 +8363,11 @@ (gnus-article-setup-buffer) (set-buffer gnus-article-buffer) (setq buffer-read-only nil) - (let ((command (if automatic command (read-string "Command: " command))) - ;; Just binding this here doesn't help, because there might - ;; be output from the process after exiting the scope of - ;; this `let'. - ;; (buffer-read-only nil) - ) + (let ((command (if automatic command (read-string "Command: " command)))) (erase-buffer) (insert "$ " command "\n\n") (if gnus-view-pseudo-asynchronously - (start-process "gnus-execute" nil shell-file-name + (start-process "gnus-execute" (current-buffer) shell-file-name shell-command-switch command) (call-process shell-file-name nil t nil shell-command-switch command)))))
--- a/lisp/gnus/gnus.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/gnus.el Mon Aug 13 09:20:48 2007 +0200 @@ -226,7 +226,7 @@ :link '(custom-manual "(gnus)Exiting Gnus") :group 'gnus) -(defconst gnus-version-number "5.4.26" +(defconst gnus-version-number "5.4.28" "Version number for this version of Gnus.") (defconst gnus-version (format "Gnus v%s" gnus-version-number)
--- a/lisp/gnus/message.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/message.el Mon Aug 13 09:20:48 2007 +0200 @@ -2905,8 +2905,9 @@ (unless (file-exists-p message-autosave-directory) (make-directory message-autosave-directory t)) (let ((name (make-temp-name - (concat (file-name-as-directory message-autosave-directory) - "msg.")))) + (expand-file-name + (concat (file-name-as-directory message-autosave-directory) + "msg."))))) (setq buffer-auto-save-file-name (save-excursion (prog1
--- a/lisp/gnus/nndoc.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nndoc.el Mon Aug 13 09:20:48 2007 +0200 @@ -37,8 +37,8 @@ (defvoo nndoc-article-type 'guess "*Type of the file. One of `mbox', `babyl', `digest', `news', `rnews', `mmdf', `forward', -`rfc934', `mime-digest', `standard-digest', `slack-digest', -`clari-briefs' or `guess'.") +`rfc934', `rfc822-forward', `mime-digest', `standard-digest', +`slack-digest', `clari-briefs' or `guess'.") (defvoo nndoc-post-type 'mail "*Whether the nndoc group is `mail' or `post'.") @@ -99,15 +99,18 @@ (prepare-body-function . nndoc-unquote-dashes) (subtype digest guess)) (lanl-gov-announce - (article-begin . "^\\\\\\\\\n") - (head-begin . "^Paper.*:") - (head-end . "\\(^\\\\\\\\.*\n\\|-----------------\\)") - (body-begin . "") - (body-end . "-------------------------------------------------") - (file-end . "^Title: Recent Seminal") - (generate-head-function . nndoc-generate-lanl-gov-head) - (article-transform-function . nndoc-transform-lanl-gov-announce) - (subtype preprints guess)) + (article-begin . "^\\\\\\\\\n") + (head-begin . "^Paper.*:") + (head-end . "\\(^\\\\\\\\.*\n\\|-----------------\\)") + (body-begin . "") + (body-end . "-------------------------------------------------") + (file-end . "^Title: Recent Seminal") + (generate-head-function . nndoc-generate-lanl-gov-head) + (article-transform-function . nndoc-transform-lanl-gov-announce) + (subtype preprints guess)) + (rfc822-forward + (article-begin . "^\n") + (body-end-function . nndoc-rfc822-forward-body-end-function)) (guess (guess . t) (subtype nil)) @@ -116,8 +119,7 @@ (subtype nil)) (preprints (guess . t) - (subtype nil)) - )) + (subtype nil)))) @@ -418,6 +420,15 @@ (not (re-search-forward "^From:" nil t 2))) t)) +(defun nndoc-rfc822-forward-type-p () + (save-restriction + (message-narrow-to-head) + (when (re-search-forward "^Content-Type: *message/rfc822" nil t) + t))) + +(defun nndoc-rfc822-forward-body-end-function () + (goto-char (point-max))) + (defun nndoc-clari-briefs-type-p () (when (let ((case-fold-search nil)) (re-search-forward "^\t[^a-z]+ ([^a-z]+) --" nil t))
--- a/lisp/gnus/nneething.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nneething.el Mon Aug 13 09:20:48 2007 +0200 @@ -24,10 +24,6 @@ ;;; Commentary: -;; Based on nnspool.el by Masanobu UMEDA <umerin@flab.flab.fujitsu.junet>. -;; For an overview of what the interface functions do, please see the -;; Gnus sources. - ;;; Code: (require 'nnheader) @@ -39,13 +35,13 @@ (nnoo-declare nneething) (defvoo nneething-map-file-directory "~/.nneething/" - "*Where nneething stores the map files.") + "Where nneething stores the map files.") (defvoo nneething-map-file ".nneething" - "*Name of the map files.") + "Name of the map files.") (defvoo nneething-exclude-files nil - "*Regexp saying what files to exclude from the group. + "Regexp saying what files to exclude from the group. If this variable is nil, no files will be excluded.") @@ -64,7 +60,6 @@ (defvoo nneething-message-id-number 0) (defvoo nneething-work-buffer " *nneething work*") -(defvoo nneething-directory nil) (defvoo nneething-group nil) (defvoo nneething-map nil) (defvoo nneething-read-only nil) @@ -130,8 +125,8 @@ (insert "\n")) t)))) -(deffoo nneething-request-group (group &optional dir dont-check) - (nneething-possibly-change-directory group dir) +(deffoo nneething-request-group (group &optional server dont-check) + (nneething-possibly-change-directory group server) (unless dont-check (nneething-create-mapping) (if (> (car nneething-active) (cdr nneething-active))
--- a/lisp/gnus/nnfolder.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nnfolder.el Mon Aug 13 09:20:48 2007 +0200 @@ -353,7 +353,8 @@ (nnfolder-delete-mail)) (when last (nnfolder-save-buffer) - (nnfolder-adjust-min-active group)))) + (nnfolder-adjust-min-active group) + (nnmail-save-active nnfolder-group-alist nnfolder-active-file)))) result)) (deffoo nnfolder-request-accept-article (group &optional server last) @@ -449,14 +450,16 @@ (marker (concat "\n" nnfolder-article-marker)) (number "[0-9]+") (activemin (cdr active))) - (goto-char (point-min)) - (while (and (search-forward marker nil t) - (re-search-forward number nil t)) - (setq activemin (min activemin - (string-to-number (buffer-substring - (match-beginning 0) - (match-end 0)))))) - (setcar active activemin))) + (save-excursion + (set-buffer nnfolder-current-buffer) + (goto-char (point-min)) + (while (and (search-forward marker nil t) + (re-search-forward number nil t)) + (setq activemin (min activemin + (string-to-number (buffer-substring + (match-beginning 0) + (match-end 0)))))) + (setcar active activemin)))) (defun nnfolder-article-string (article) (if (numberp article) @@ -484,6 +487,9 @@ (when (and server (not (nnfolder-server-opened server))) (nnfolder-open-server server)) + (unless (gnus-buffer-live-p nnfolder-current-buffer) + (setq nnfolder-current-buffer nil + nnfolder-current-group nil)) ;; Change group. (when (and group (not (equal group nnfolder-current-group))) @@ -495,7 +501,8 @@ (push (list group (cons 1 0)) nnfolder-group-alist) (nnmail-save-active nnfolder-group-alist nnfolder-active-file)) - (unless dont-check + (if dont-check + (setq nnfolder-current-group group) (let (inf file) ;; If we have to change groups, see if we don't already have the ;; folder in memory. If we do, verify the modtime and destroy
--- a/lisp/gnus/nnheader.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nnheader.el Mon Aug 13 09:20:48 2007 +0200 @@ -178,7 +178,7 @@ ;; a case (which basically was the old function) is actually ;; about twice as fast, even though it looks messier. You ;; can't have everything, I guess. Speed and elegance - ;; doesn't always go hand in hand. + ;; don't always go hand in hand. (vector ;; Number. (if naked @@ -211,8 +211,10 @@ ;; Message-ID. (progn (goto-char p) - (if (search-forward "\nmessage-id: " nil t) - (nnheader-header-value) + (if (search-forward "\nmessage-id:" nil t) + (buffer-substring + (1- (or (search-forward "<" nil t) (point))) + (or (search-forward ">" nil t) (point))) ;; If there was no message-id, we just fake one to make ;; subsequent routines simpler. (nnheader-generate-fake-message-id)))
--- a/lisp/gnus/nnmail.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nnmail.el Mon Aug 13 09:20:48 2007 +0200 @@ -207,7 +207,10 @@ :group 'nnmail-files :type 'function) -(defcustom nnmail-crosspost-link-function 'add-name-to-file +(defcustom nnmail-crosspost-link-function + (if (string-match "windows-nt\\|emx" (format "%s" system-type)) + 'copy-file + 'add-name-to-file) "Function called to create a copy of a file. This is `add-name-to-file' by default, which means that crossposts will use hard links. If your file system doesn't allow hard
--- a/lisp/gnus/nnml.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/gnus/nnml.el Mon Aug 13 09:20:48 2007 +0200 @@ -674,7 +674,7 @@ ;;;###autoload (defun nnml-generate-nov-databases () - "Generate nov databases in all nnml directories." + "Generate NOV databases in all nnml directories." (interactive) ;; Read the active file to make sure we don't re-use articles ;; numbers in empty groups. @@ -687,6 +687,8 @@ (nnmail-save-active nnml-group-alist nnml-active-file)) (defun nnml-generate-nov-databases-1 (dir &optional seen) + "Regenerate the NOV database in DIR." + (interactive "DRegenerate NOV in: ") (setq dir (file-name-as-directory dir)) ;; Only scan this sub-tree if we haven't been here yet. (unless (member (file-truename dir) seen)
--- a/lisp/mule/mule-files.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/mule/mule-files.el Mon Aug 13 09:20:48 2007 +0200 @@ -41,6 +41,8 @@ (setq-default buffer-file-coding-system 'iso-2022-8) (put 'buffer-file-coding-system 'permanent-local t) +(define-obsolete-variable-alias 'file-coding-system 'buffer-file-coding-system) + (defvar coding-system-for-write nil "Overriding coding system used when writing a file. You should *bind* this, not set it. If this is non-nil, it specifies @@ -66,11 +68,13 @@ `coding-system-for-read' rather than setting this variable, which is intended to be used for global environment specification.") +(define-obsolete-variable-alias + 'file-coding-system-for-read + 'buffer-file-coding-system-for-read) + (defvar buffer-file-coding-system-alist - '(("\\.el$" . iso-2022-8) - ("\\.info$" . iso-2022-8) - ("ChangeLog$" . iso-2022-8) - ("\\.texi$" . iso-2022-8) + '(("\\.\\(el\\|emacs\\|info\\|texi\\)$" . iso-2022-8) + ("\\(ChangeLog\\|CHANGES-beta\\)$" . iso-2022-8) ("\\.\\(gz\\|Z\\)$" . no-conversion) ("/spool/mail/.*$" . convert-mbox-coding-system)) "Alist specifying the coding system used for particular files. @@ -84,6 +88,10 @@ called with four arguments: FILENAME, VISIT, START, and END, the same as the first four arguments to `insert-file-contents'.") +(define-obsolete-variable-alias + 'file-coding-system-alist + 'buffer-file-coding-system-alist) + (defun set-buffer-file-coding-system (coding-system &optional force) "Set buffer-file-coding-system of the current buffer to CODING-SYSTEM. If optional argument FORCE (interactively, the prefix argument) is not @@ -99,6 +107,10 @@ (setq buffer-file-coding-system coding-system) (redraw-modeline t)) +(define-obsolete-function-alias + 'set-file-coding-system + 'set-buffer-file-coding-system) + (defun set-buffer-file-coding-system-for-read (coding-system) "Set the coding system used when reading in a file. This is equivalent to setting the variable @@ -109,6 +121,10 @@ (get-coding-system coding-system) ;; correctness check (setq buffer-file-coding-system-for-read coding-system)) +(define-obsolete-function-alias + 'set-file-coding-system-for-read + 'set-buffer-file-coding-system-for-read) + (defun set-default-buffer-file-coding-system (coding-system) "Set the default value of `buffer-file-coding-system' to CODING-SYSTEM. The default value is used both for buffers without associated files @@ -118,6 +134,10 @@ (setq-default buffer-file-coding-system coding-system) (redraw-modeline t)) +(define-obsolete-function-alias + 'set-default-file-coding-system + 'set-default-buffer-file-coding-system) + (defun find-buffer-file-coding-system-from-filename (filename) "Look up a file in `buffer-file-coding-system-alist'. The return value will be nil (no applicable entry), a coding system @@ -137,6 +157,10 @@ (cond ((find-coding-system codesys)) (t codesys))))) +(define-obsolete-function-alias + 'find-file-coding-system-from-filename + 'find-buffer-file-coding-system-from-filename) + (defun convert-mbox-coding-system (filename visit start end) "Decoding function for Unix mailboxes. Does separate detection and decoding on each message, since each
--- a/lisp/prim/auto-autoloads.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/prim/auto-autoloads.el Mon Aug 13 09:20:48 2007 +0200 @@ -2389,7 +2389,7 @@ ;;;### (autoloads (nnml-generate-nov-databases) "nnml" "gnus/nnml.el") (autoload 'nnml-generate-nov-databases "nnml" "\ -Generate nov databases in all nnml directories." t nil) +Generate NOV databases in all nnml directories." t nil) ;;;*** @@ -3840,7 +3840,7 @@ ;;;### (autoloads (ksh-mode) "ksh-mode" "modes/ksh-mode.el") (autoload 'ksh-mode "ksh-mode" "\ -ksh-mode $Revision: 1.15 $ - Major mode for editing (Bourne, Korn or Bourne again) +ksh-mode $Revision: 1.16 $ - Major mode for editing (Bourne, Korn or Bourne again) shell scripts. Special key bindings and commands: \\{ksh-mode-map} @@ -5192,7 +5192,7 @@ (autoload 'vhdl-mode "vhdl-mode" "\ Major mode for editing VHDL code. -vhdl-mode $Revision: 1.15 $ +vhdl-mode $Revision: 1.16 $ To submit a problem report, enter `\\[vhdl-submit-bug-report]' from a vhdl-mode buffer. This automatically sets up a mail buffer with version information already added. You just need to add a description of the @@ -8363,48 +8363,6 @@ ;;;*** -;;;### (autoloads (with-timeout run-with-idle-timer run-with-timer run-at-time) "timer" "prim/timer.el") - -(autoload 'run-at-time "timer" "\ -Perform an action after a delay of SECS seconds. -Repeat the action every REPEAT seconds, if REPEAT is non-nil. -TIME should be a string like \"11:23pm\", nil meaning now, a number of seconds -from now, or a value from `encode-time'. -REPEAT may be an integer or floating point number. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." t nil) - -(autoload 'run-with-timer "timer" "\ -Perform an action after a delay of SECS seconds. -Repeat the action every REPEAT seconds, if REPEAT is non-nil. -SECS and REPEAT may be integers or floating point numbers. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." t nil) - -(autoload 'run-with-idle-timer "timer" "\ -Perform an action the next time Emacs is idle for SECS seconds. -If REPEAT is non-nil, do this each time Emacs is idle for SECS seconds. -SECS may be an integer or a floating point number. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." t nil) - -(put 'with-timeout 'lisp-indent-function 1) - -(autoload 'with-timeout "timer" "\ -Run BODY, but if it doesn't finish in SECONDS seconds, give up. -If we give up, we run the TIMEOUT-FORMS and return the value of the last one. -The call should look like: - (with-timeout (SECONDS TIMEOUT-FORMS...) BODY...) -The timeout is checked whenever Emacs waits for some kind of external -event (such as keyboard input, input from subprocesses, or a certain time); -if the program loops without waiting in any way, the timeout will not -be detected." nil 'macro) - -;;;*** - ;;;### (autoloads (ask-user-about-supersession-threat ask-user-about-lock) "userlock" "prim/userlock.el") (autoload 'ask-user-about-lock "userlock" "\
--- a/lisp/prim/custom-load.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/prim/custom-load.el Mon Aug 13 09:20:48 2007 +0200 @@ -20,14 +20,14 @@ (put 'gnus-article-washing 'custom-loads '("gnus-art")) (put 'mail 'custom-loads '("gnus" "message")) (put 'gnus-summary-exit 'custom-loads '("gnus-sum")) -(put 'comint-input-face 'custom-loads '("comint")) +(put 'comint-input-face 'custom-loads '("comint-xemacs")) (put 'gnus-article-saving 'custom-loads '("gnus-art")) (put 'gnus-extract-view 'custom-loads '("gnus-sum" "gnus-uu")) (put 'gnus-group-listing 'custom-loads '("gnus-group")) (put 'gnus-summary 'custom-loads '("gnus-sum" "gnus")) -(put 'message-headers 'custom-loads '("auto-autoloads" "message")) +(put 'message-headers 'custom-loads '("message")) (put 'gnus-group-select 'custom-loads '("gnus-sum")) -(put 'display-time 'custom-loads '("time" "auto-autoloads")) +(put 'display-time 'custom-loads '("time")) (put 'hypermedia 'custom-loads '("wid-edit")) (put 'w3-advanced 'custom-loads '("w3-cus")) (put 'w3-menus 'custom-loads '("w3-cus")) @@ -43,7 +43,7 @@ (put 'help 'custom-loads '("cus-edit")) (put 'nnmail-split 'custom-loads '("nnmail")) (put 'gnus-article-various 'custom-loads '("gnus-art" "gnus-sum")) -(put 'message-sending 'custom-loads '("auto-autoloads" "message")) +(put 'message-sending 'custom-loads '("message")) (put 'w3-files 'custom-loads '("w3-cus")) (put 'widget-browse 'custom-loads '("wid-browse")) (put 'gnus-article 'custom-loads '("gnus-art" "gnus-cite")) @@ -79,8 +79,8 @@ (put 'gnus-summary-choose 'custom-loads '("gnus-sum")) (put 'development 'custom-loads '("cus-edit")) (put 'gnus-windows 'custom-loads '("gnus-win")) -(put 'message-mail 'custom-loads '("auto-autoloads" "message")) -(put 'message-various 'custom-loads '("auto-autoloads" "message")) +(put 'message-mail 'custom-loads '("message")) +(put 'message-various 'custom-loads '("message")) (put 'gnus-group-levels 'custom-loads '("gnus-group")) (put 'languages 'custom-loads '("cus-edit")) (put 'gnus-summary-format 'custom-loads '("gnus-sum")) @@ -92,7 +92,7 @@ (put 'emacs 'custom-loads '("cus-edit" "dired-faces")) (put 'news 'custom-loads '("gnus" "message")) (put 'w3-hooks 'custom-loads '("w3-cus")) -(put 'message-insertion 'custom-loads '("auto-autoloads" "message")) +(put 'message-insertion 'custom-loads '("message")) (put 'wp 'custom-loads '("cus-edit")) (put 'message-faces 'custom-loads '("message")) (put 'gnus-score-files 'custom-loads '("gnus-score"))
--- a/lisp/prim/fill.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/prim/fill.el Mon Aug 13 09:20:48 2007 +0200 @@ -1,6 +1,6 @@ ;;; fill.el --- fill commands for XEmacs. -;; Copyright (C) 1985, 86, 92, 94, 95, 1996 Free Software Foundation, Inc. +;; Copyright (C) 1985, 86, 92, 94, 95, 1997 Free Software Foundation, Inc. ;; Keywords: wp @@ -91,7 +91,7 @@ nil ;; we have skipped backward SPC or WAN (word-across-newline). So move point forward again. (forward-char) - (if (<= opoint (point)) + (if (< opoint (point)) (forward-char -1))))) ;; Added for kinsoku processing. Use instead of @@ -103,7 +103,7 @@ (if (not (re-search-forward regexp lim 'move)) nil (forward-char -1) - (if (<= (point) opoint) + (if (< (point) opoint) (forward-char)))) (if (featurep 'mule) (kinsoku-process-extend)))
--- a/lisp/prim/timer.el Mon Aug 13 09:19:47 2007 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,308 +0,0 @@ -;;; timer.el --- run a function with args at some time in future. - -;; Copyright (C) 1996 Free Software Foundation, Inc. - -;; Maintainer: FSF - -;; This file is part of GNU Emacs. - -;; GNU Emacs 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 Emacs 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 Emacs; see the file COPYING. If not, write to the -;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, -;; Boston, MA 02111-1307, USA. - -;;; Commentary: - -;; This package gives you the capability to run Emacs Lisp commands at -;; specified times in the future, either as one-shots or periodically. - -;;; Code: - -(require 'itimer) - -(fset 'timer-create 'make-itimer) - -(fset 'timerp 'itimerp) - -;(defvar timer-idle-list nil -; "List of active idle-time timers in order of increasing time") -(defvaralias 'timer-idle-list 'itimer-list) -(defvaralias 'timer-list 'itimer-list) - - -(defun timer-set-time (timer time &optional delta) - "Set the trigger time of TIMER to TIME. -TIME must be in the internal format returned by, e.g., `current-time'. -If optional third argument DELTA is a non-zero integer, make the timer -fire repeatedly that many seconds apart." - (set-itimer-value timer (itimer-time-difference time (current-time))) - (and delta (check-nonnegative-number delta)) - (and delta (set-itimer-restart timer delta)) - timer) - -(defun timer-set-idle-time (timer secs &optional repeat) - "Set the trigger idle time of TIMER to SECS. -If optional third argument REPEAT is non-nil, make the timer -fire each time Emacs is idle for that many seconds." - (set-itimer-is-idle timer t) - (set-itimer-value timer secs) - (when repeat - (set-itimer-restart timer secs)) - timer) - -(defun timer-relative-time (time secs &optional usecs) - "Advance TIME by SECS seconds and optionally USECS microseconds. -SECS may be a fraction." - (let ((high (car time)) - (low (if (consp (cdr time)) (nth 1 time) (cdr time))) - (micro (if (numberp (car-safe (cdr-safe (cdr time)))) - (nth 2 time) - 0))) - ;; Add - (if usecs (setq micro (+ micro usecs))) - (if (floatp secs) - (setq micro (+ micro (floor (* 1000000 (- secs (floor secs))))))) - (setq low (+ low (floor secs))) - - ;; Normalize - (setq low (+ low (/ micro 1000000))) - (setq micro (mod micro 1000000)) - (setq high (+ high (/ low 65536))) - (setq low (logand low 65535)) - - (list high low (and (/= micro 0) micro)))) - -(defun timer-inc-time (timer secs &optional usecs) - "Increment the time set in TIMER by SECS seconds and USECS microseconds. -SECS may be a fraction." - (let ((time (itimer-value timer))) - (setq time (+ time secs (if (and usecs (fboundp 'lisp-float-type)) - (/ usecs (float 1000000)) - 0))) - (set-itimer-value timer time))) - -(defun timer-set-time-with-usecs (timer time usecs &optional delta) - "Set the trigger time of TIMER to TIME. -TIME must be in the internal format returned by, e.g., `current-time'. -If optional third argument DELTA is a non-zero integer, make the timer -fire repeatedly that many seconds apart." - (let ((list (list nil nil nil))) - (setcar list (car time)) - (setcar (nthcdr 1 list) (if (consp (cdr time)) - (car (cdr time)) - (cdr time))) - (setcar (nthcdr 2 list) usecs) - (set-itimer-value timer (itimer-time-difference list (current-time))) - (set-itimer-restart timer delta) - timer)) - -(defun timer-set-function (timer function &optional args) - "Make TIMER call FUNCTION with optional ARGS when triggering." - (set-itimer-function timer function) - (set-itimer-function-arguments timer args) - (set-itimer-uses-arguments timer t) - timer) - -(defun timer-activate (timer) - "Put TIMER on the list of active timers." - (activate-itimer timer)) - -(defun timer-activate-when-idle (timer) - "Arrange to activate TIMER whenever Emacs is next idle." - (set-itimer-is-idle timer t) - (set-itimer-uses-arguments timer nil) - ;(unless (memq timer timer-idle-list) - ;(setq timer-idle-list (cons timer timer-idle-list))) - (activate-itimer timer)) - -;; can't do this, different kind of timer -;;(defalias 'disable-timeout 'cancel-timer) - -(defun cancel-timer (timer) - "Remove TIMER from the list of active timers." - ;(setq timer-idle-list (delq timer timer-idle-list)) - (delete-itimer timer)) - -(defun cancel-function-timers (function) - "Cancel all timers scheduled by `run-at-time' which would run FUNCTION." - (interactive "aCancel timers of function: ") - (let ((p itimer-list)) - (while p - (if (eq function (itimer-function p)) - (progn - (setq p (cdr p)) - (delete-itimer (car p))) - (setq p (cdr p)))))) - -;;;###autoload -(defun run-at-time (time repeat function &rest args) - "Perform an action after a delay of SECS seconds. -Repeat the action every REPEAT seconds, if REPEAT is non-nil. -TIME should be a string like \"11:23pm\", nil meaning now, a number of seconds -from now, or a value from `encode-time'. -REPEAT may be an integer or floating point number. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." - (interactive "sRun at time: \nNRepeat interval: \naFunction: ") - - ;; Special case: nil means "now" and is useful when repeating. - (if (null time) - (setq time (current-time))) - - ;; Handle numbers as relative times in seconds. - (if (numberp time) - (setq time (timer-relative-time (current-time) time))) - - ;; Handle relative times like "2 hours and 35 minutes" - (if (stringp time) - (let ((secs (timer-duration time))) - (if secs - (setq time (timer-relative-time (current-time) secs))))) - - ;; Handle "11:23pm" and the like. Interpret it as meaning today - ;; which admittedly is rather stupid if we have passed that time - ;; already. (Though only Emacs hackers hack Emacs at that time.) - (if (stringp time) - (progn - (require 'diary-lib) - (let ((hhmm (diary-entry-time time)) - (now (decode-time))) - (if (>= hhmm 0) - (setq time - (encode-time 0 (% hhmm 100) (/ hhmm 100) (nth 3 now) - (nth 4 now) (nth 5 now) (nth 8 now))))))) - - (or (consp time) - (error "Invalid time format")) - - (or (null repeat) - (numberp repeat) - (error "Invalid repetition interval")) - - (let ((timer (timer-create))) - (timer-set-time timer time repeat) - (timer-set-function timer function args) - (timer-activate timer) - timer)) - -;;;###autoload -(defun run-with-timer (secs repeat function &rest args) - "Perform an action after a delay of SECS seconds. -Repeat the action every REPEAT seconds, if REPEAT is non-nil. -SECS and REPEAT may be integers or floating point numbers. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." - (interactive "sRun after delay (seconds): \nNRepeat interval: \naFunction: ") - (apply 'run-at-time secs repeat function args)) - -;;;###autoload -(defun run-with-idle-timer (secs repeat function &rest args) - "Perform an action the next time Emacs is idle for SECS seconds. -If REPEAT is non-nil, do this each time Emacs is idle for SECS seconds. -SECS may be an integer or a floating point number. -The action is to call FUNCTION with arguments ARGS. - -This function returns a timer object which you can use in `cancel-timer'." - (interactive - (list (read-from-minibuffer "Run after idle (seconds): " nil nil t) - (y-or-n-p "Repeat each time Emacs is idle? ") - (intern (completing-read "Function: " obarray 'fboundp t)))) - (let ((timer (timer-create))) - (timer-set-function timer function args) - (timer-set-idle-time timer secs repeat) - (timer-activate-when-idle timer) - timer)) - -(defun with-timeout-handler (tag) - (throw tag 'timeout)) - -;;;###autoload (put 'with-timeout 'lisp-indent-function 1) - -;;;###autoload -(defmacro with-timeout (list &rest body) - "Run BODY, but if it doesn't finish in SECONDS seconds, give up. -If we give up, we run the TIMEOUT-FORMS and return the value of the last one. -The call should look like: - (with-timeout (SECONDS TIMEOUT-FORMS...) BODY...) -The timeout is checked whenever Emacs waits for some kind of external -event \(such as keyboard input, input from subprocesses, or a certain time); -if the program loops without waiting in any way, the timeout will not -be detected." - (let ((seconds (car list)) - (timeout-forms (cdr list))) - `(let ((with-timeout-tag (cons nil nil)) - with-timeout-value with-timeout-timer) - (if (catch with-timeout-tag - (progn - (setq with-timeout-timer - (run-with-timer ,seconds nil - 'with-timeout-handler - with-timeout-tag)) - (setq with-timeout-value (progn . ,body)) - nil)) - (progn . ,timeout-forms) - (cancel-timer with-timeout-timer) - with-timeout-value)))) - -(defun y-or-n-p-with-timeout (prompt seconds default-value) - "Like (y-or-n-p PROMPT), with a timeout. -If the user does not answer after SECONDS seconds, return DEFAULT-VALUE." - (with-timeout (seconds default-value) - (y-or-n-p prompt))) - -(defvar timer-duration-words - (list (cons "microsec" 0.000001) - (cons "microsecond" 0.000001) - (cons "millisec" 0.001) - (cons "millisecond" 0.001) - (cons "sec" 1) - (cons "second" 1) - (cons "min" 60) - (cons "minute" 60) - (cons "hour" (* 60 60)) - (cons "day" (* 24 60 60)) - (cons "week" (* 7 24 60 60)) - (cons "fortnight" (* 14 24 60 60)) - (cons "month" (* 30 24 60 60)) ; Approximation - (cons "year" (* 365.25 24 60 60)) ; Approximation - ) - "Alist mapping temporal words to durations in seconds") - -(defun timer-duration (string) - "Return number of seconds specified by STRING, or nil if parsing fails." - (let ((secs 0) - (start 0) - (case-fold-search t)) - (while (string-match - "[ \t]*\\([0-9.]+\\)?[ \t]*\\([a-z]+[a-rt-z]\\)s?[ \t]*" - string start) - (let ((count (if (match-beginning 1) - (string-to-number (match-string 1 string)) - 1)) - (itemsize (cdr (assoc (match-string 2 string) - timer-duration-words)))) - (if itemsize - (setq start (match-end 0) - secs (+ secs (* count itemsize))) - (setq secs nil - start (length string))))) - (if (= start (length string)) - secs - (if (string-match "\\`[0-9.]+\\'" string) - (string-to-number string))))) - -(provide 'timer) - -;;; timer.el ends here
--- a/lisp/utils/autoload.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/utils/autoload.el Mon Aug 13 09:20:48 2007 +0200 @@ -344,7 +344,9 @@ (let ((visited (get-file-buffer file))) (save-excursion (set-buffer (or visited (find-file-noselect file))) - (when (and file (string-match "\\`\\(.*\\)\\.el\\'" file)) + (when (and file + (string-match "\\`\\(.*\\)\\.el\\'" file) + (not (buffer-modified-p))) (goto-char (point-min)) (condition-case nil (let ((name (file-name-nondirectory (match-string 1 file))))
--- a/lisp/utils/eldoc.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/utils/eldoc.el Mon Aug 13 09:20:48 2007 +0200 @@ -7,7 +7,7 @@ ;; Keywords: extensions ;; Created: 1995-10-06 -;; $Id: eldoc.el,v 1.3 1997/03/16 03:05:48 steve Exp $ +;; $Id: eldoc.el,v 1.4 1997/03/18 03:27:00 steve Exp $ ;; This file is part of GNU Emacs. @@ -240,7 +240,7 @@ ;; timer, we're still in the middle of executing a command, ;; e.g. a query-replace where it would be annoying to ;; overwrite the echo area. - (and ;(not this-command) + (and (not this-command) (symbolp last-command) (intern-soft (symbol-name last-command) eldoc-message-commands)))
--- a/lisp/version.el Mon Aug 13 09:19:47 2007 +0200 +++ b/lisp/version.el Mon Aug 13 09:20:48 2007 +0200 @@ -25,7 +25,7 @@ (defconst emacs-version "20.1" "Version numbers of this version of Emacs.") -(setq emacs-version (purecopy (concat emacs-version " XEmacs Lucid (beta7)"))) +(setq emacs-version (purecopy (concat emacs-version " XEmacs Lucid (beta8)"))) (defconst emacs-major-version (progn (or (string-match "^[0-9]+" emacs-version)
--- a/man/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/man/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,7 @@ +Sun Mar 16 18:48:14 1997 Steven L Baur <steve@altair.xemacs.org> + + * gnats/Makefile (gnats_srcs): New manuals for GNATS. + Wed Mar 12 14:39:43 1997 Steven L Baur <steve@altair.xemacs.org> * lispref/strings.texi (Text Comparison): Correct example for
--- a/man/custom.texi Mon Aug 13 09:19:47 2007 +0200 +++ b/man/custom.texi Mon Aug 13 09:20:48 2007 +0200 @@ -13,7 +13,7 @@ @comment node-name, next, previous, up @top The Customization Library -Version: 1.63 +Version: 1.64 @menu * Introduction::
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/Makefile Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,61 @@ +# Makefile for the XEmacs Internals Manual. + +# This file is part of XEmacs. + +# XEmacs 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. + +# XEmacs 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 XEmacs; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 59 Temple Place - Suite 330, +# Boston, MA 02111-1307, USA. + +VERSION=1.0 +NAME=gnats + +# Uncomment this line for permuted index. +# permuted_index = 1 + +# List of all the texinfo files in the manual: + +srcs = categ.texi fields.texi flowchart.txt gnats.texi p-admin.texi \ + p-inst.texi p-usage.texi s-usage.texi send-pr.texi states.text \ + version.texi + +gnats_srcs = flowchart.txt gnats.texi p-admin.texi p-inst.texi \ + p-usage.texi version.texi + +send_pr_srcs = categ.texi fields.texi s-usage.texi send-pr.texi states.texi \ + version.texi + +all : info +info : ../../info/$(NAME).info ../../info/send-pr.info + +../../info/$(NAME).info: ${gnats_srcs} + ${MAKEINFO} $(NAME).texi -o ../../info/${NAME}.info + +../../info/send-pr.info: ${seend_pr_srcs} + ${MAKEINFO} send-pr.texi -o ../../info/send-pr.info + +dvi : $(NAME).dvi send-pr.dvi + +$(NAME).dvi: $(srcs) index.texi + texi2dvi gnats.texi + texi2dvi send-pr.texi + +mostlyclean: + rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \ + *.vr *.vrs *.pg *.pgs *.ky *.kys +clean: mostlyclean + rm -f *.dvi *.ps make.out core index.texi +distclean: clean +realclean: clean +extraclean: clean + -rm -f *~ \#*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/categ.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,123 @@ +@node Valid Categories +@unnumberedsec Valid Categories +@cindex valid categories +@cindex example of a list of valid categories + +@table @code +@item bfd +@sc{gnu} binary file descriptor library. + +@item bifrabulator +This one doesn't actually exist. + +@item binutils +@sc{gnu} utilities for binary files (@code{ar}, @code{nm}, @code{size}@dots{}). + +@item bison +@sc{gnu} parser generator. + +@item byacc +Free parser generator. + +@item config +Cygnus Support Software configuration and installation. + +@item cvs +Concurrent Version System. + +@item diff +@sc{gnu} @code{diff} program. + +@item doc +Documentation and manuals. + +@item emacs +@sc{gnu} Emacs editor and related functions. + +@item flex +@sc{gnu} lexical analyzer. + +@item g++ +@sc{gnu} C++ compiler. + +@item gas +@sc{gnu} assembler. + +@item gcc +@sc{gnu} C compiler. + +@item gdb +@sc{gnu} source code debugger. + +@item glob +The filename globbing functions. + +@item gprof +@sc{gnu} profiler. + +@item grep +@sc{gnu} @code{grep} program. + +@item info +@sc{gnu} @code{info} hypertext reader. + +@item ispell +@sc{gnu} spelling checker. + +@item kerberos +Kerberos authentication system. + +@item ld +@sc{gnu} linker. + +@item libc +Cygnus Support C Support Library. + +@item libg++ +@sc{gnu} C++ class library. + +@item libiberty +@sc{gnu} @samp{libiberty} library. + +@item libm +Cygnus Support C Math Library. + +@item make +@sc{gnu} @code{make} program. + +@item makeinfo +@sc{gnu} utility to build Info files from Texinfo documents. + +@item mas +@sc{gnu} Motorola syntax assembler. + +@item newlib +Cygnus Support C Support and Math Libraries. + +@item patch +@sc{gnu} bug patch program. + +@item gnats +@sc{gnu} Problem Report Management System. + +@item rcs +Revision Control System. + +@item readline +@sc{gnu} @code{readline} library. + +@item send-pr +@sc{gnu} Problem Report submitting program. + +@item test +Category to use when testing @code{send-pr}. + +@item texindex +@sc{gnu} documentation indexing utility. + +@item texinfo +@sc{gnu} documentation macros. + +@item other +Anything which is not covered by the above categories. +@end table
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/fields.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,520 @@ +@node Fields +@section Problem Report format +@cindex Problem Report format +@cindex format +@cindex database similarities +@cindex fields + +The format of a PR is designed to reflect the nature of @sc{gnats} as a +database. Information is arranged into @dfn{fields}, and kept in +individual records (Problem Reports). + +Problem Report fields are denoted by a keyword which begins with +@samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields +belong to one of three data types: + +@table @asis +@cindex Problem Report data types +@cindex @emph{Enumerated} data types +@item @sc{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). + +@ifset SENDPR +For each @sc{Enumerated} keyword, the possible choices are listed in the +@code{send-pr} template as a comment. +@end ifset +The following fields are @sc{Enumerated} format; see the descriptions of +fields below for explanations of each field in detail: + +@smallexample +@group +>Confidential: >Severity: >Priority: +>Class: >State: >Number: +@end group +@end smallexample + +@cindex @emph{Text} data types +@item @sc{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 +@sc{Text} format: + +@smallexample +@group +>Submitter-Id: >Originator: >Synopsis: +>Category: >Release: >Responsible: +>Arrival-Date: +@end group +@end smallexample + +@cindex @emph{MultiText} data types +@item @sc{MultiText} +Text of any length may occur in this field. @sc{MultiText} may span +multiple lines and may also include blank lines. A @sc{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 @sc{MultiText} format: + +@smallexample +@group +>Organization: >Environment: >Description: +>How-To-Repeat: >Fix: >Audit-Trail: +>Unformatted: +@end group +@end smallexample + +@end table + +A Problem Report contains two different types of fields: @dfn{Mail +Header} fields, which are used by the mail handler for delivery, and +@dfn{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. + +@ifclear SENDPR +@subheading Example Problem Report +@end ifclear + +The following is an example Problem Report. Mail headers are at the +top, followed by @sc{gnats} fields, which begin with @samp{>} and end +with @samp{:}. The @samp{Subject:} line in the mail header and the +@samp{>Synopsis:} field are usually duplicates of each other. + +@cindex sample Problem Report +@cindex example Problem Report +@cindex Problem Report template +@cartouche +@smallexample +@group +Message-Id: @var{message-id} +Date: @var{date} +From: @var{address} +Reply-To: @var{address} +To: @var{bug-address} +Subject: @var{subject} + +>Number: @var{gnats-id} +>Category: @var{category} +>Synopsis: @var{synopsis} +>Confidential: yes @emph{or} no +>Severity: critical, serious, @emph{or} non-critical +>Priority: high, medium @emph{or} low +>Responsible: @var{responsible} +>State: open, analyzed, suspended, feedback, @emph{or} closed +>Class: sw-bug, doc-bug, change-request, support, +@ifset SENDPR +@emph{or} duplicate +@end ifset +@ifclear SENDPR +duplicate, @emph{or} mistaken +@end ifclear +>Submitter-Id: @var{submitter-id} +>Arrival-Date: @var{date} +>Originator: @var{name} +>Organization: @var{organization} +>Release: @var{release} +>Environment: + @var{environment} +>Description: + @var{description} +>How-To-Repeat: + @var{how-to-repeat} +>Fix: + @var{fix} +>Audit-Trail: +@var{appended-messages@dots{}} +State-Changed-From-To: @var{from}-@var{to} +State-Changed-When: @var{date} +State-Changed-Why: + @var{reason} +Responsible-Changed-From-To: @var{from}-@var{to} +Responsible-Changed-When: @var{date} +Responsible-Changed-Why: + @var{reason} +>Unformatted: + @var{miscellaneous} +@end group +@end smallexample +@end cartouche + +@menu +* Mail header fields:: +* Problem Report fields:: +@end menu + +@c ---------------------- +@node Mail header fields +@subsection Mail header fields +@cindex mail header fields +@cindex Internet standard RFC-822 + +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 @code{send-pr}: + +@table @code +@cindex @code{To:} header +@item To: +The preconfigured mail address for the Support Site where the PR is to +be sent, automatically supplied by @code{send-pr}. + +@cindex @code{Subject:} header +@item Subject: +A terse description of the problem. This field normally contains the +same information as the @samp{>Synopsis:} field. + +@cindex @code{From:} header +@item From: +Usually supplied automatically by the originator's mailer; should +contain the originator's electronic mail address. + +@cindex @code{Reply-To:} header +@item Reply-To: +A return address to which electronic replies can be sent; in most cases, +the same address as the @code{From:} field. +@end table + +@ifclear SENDPR +@cindex @code{Received-By:} headers +One of the configurable options for @sc{gnats} is whether or not to +retain @w{@samp{Received-By:}} headers, which often consume a lot of +space and are not often used. @xref{Local configuration,,Changing your +local configuration}. +@end ifclear + +@c ---------------------- +@node Problem Report fields +@subsection Problem Report fields +@cindex GNATS database fields +@cindex field format + +@c FIXME - this node is loooooooooooooooong... + +@subheading Field descriptions + +The following fields are present whenever a PR is submitted via the +program @code{send-pr}. @sc{gnats} adds additional fields when the PR +arrives at the Support Site; explanations of these follow this list. + +@cindex fields - list +@cindex GNATS fields - list +@table @code +@cindex @code{Submitter-Id} field +@cindex @code{>Submitter-Id:} +@item >Submitter-Id: +(@sc{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 +@code{send-pr} with the @samp{--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 @samp{net} +for this field.) + +@cindex @code{Originator} field +@cindex @code{>Originator:} +@item >Originator: +(@sc{Text}) Originator's real name. The default is the value of the +originator's environment variable @code{NAME}. + +@cindex @code{>Organization:} +@cindex @code{Organization} field +@item >Organization: +(@sc{MultiText}) The originator's organization. The default value is +set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the +@ifclear SENDPR +@file{config} file (@pxref{config,,The @code{config} file}). +@end ifclear +@ifset SENDPR +@code{send-pr} shell script. +@end ifset + +@cindex @code{Confidential} field +@cindex @code{>Confidential:} +@cindex confidentiality in PRs +@cindex PR confidentiality +@item >Confidential: +(@sc{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 @samp{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 @samp{yes}. + +@cindex @code{Synopsis} field +@cindex @code{>Synopsis:} +@item >Synopsis: +(@sc{Text}) One-line summary of the problem. @w{@code{send-pr}} copies +this information to the @samp{Subject:} line when you submit a Problem +Report. + +@cindex @code{Severity} field +@cindex @code{>Severity:} +@item >Severity: +(@sc{Enumerated}) The severity of the problem. Accepted values include: + +@table @code +@cindex @emph{critical} severity problems +@item critical +The product, component or concept is completely non-operational or some +essential functionality is missing. No workaround is known. + +@cindex @emph{serious} severity problems +@item serious +The product, component or concept is not working properly or significant +functionality is missing. Problems that would otherwise be considered +@samp{critical} are rated @samp{serious} when a workaround is known. + +@cindex @emph{non-critical} severity problems +@item 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. +@end table +@noindent +The default value is @samp{serious}. +@sp 1 + +@cindex @code{Priority} field +@cindex @code{>Priority:} +@item >Priority: +(@sc{Enumerated}) How soon the originator requires a solution. Accepted +values include: + +@table @code +@cindex @emph{high} priority problems +@item high +A solution is needed as soon as possible. + +@cindex @emph{medium} priority problems +@item medium +The problem should be solved in the next release. + +@cindex @emph{low} priority problems +@item low +The problem should be solved in a future release. +@end table +@noindent +The default value is @samp{medium}. +@sp 1 + +@cindex @code{Category} field +@cindex @code{>Category:} +@item >Category: +(@sc{Text}) The name of the product, component or concept where +the problem lies. The values for this field are defined by the Support +Site. +@ifclear SENDPR +@xref{categories,,The @code{categories} file}, for details. +@end ifclear + +@cindex @code{Class} field +@cindex @code{>Class:} +@item >Class: +(@sc{Enumerated}) The class of a problem can be one of the following: + +@table @code +@cindex @emph{sw-bug} class +@item sw-bug +A general product problem. (@samp{sw} stands for ``software''.) + +@cindex @emph{doc-bug} class +@item doc-bug +A problem with the documentation. + +@cindex @emph{change-request} class +@item change-request +A request for a change in behavior, etc. + +@cindex @emph{support} class +@item support +A support problem or question. + +@cindex @emph{duplicate} class +@item duplicate (@var{pr-number}) +Duplicate PR. @var{pr-number} should be the number of the original PR. + +@ifclear SENDPR +@cindex @emph{mistaken} class +@item mistaken +No problem, user error or misunderstanding. This value is valid only at +the Support Site. +@end ifclear +@end table + +@noindent +The default is @samp{sw-bug}. +@sp 1 + +@cindex @code{Release} field +@cindex @code{>Release:} +@item >Release: +(@sc{Text}) Release or version number of the product, component or +concept. + +@cindex @code{Environment} field +@cindex @code{>Environment:} +@item >Environment: +(@sc{MultiText}) Description of the environment where the problem occured: +machine architecture, operating system, host and target types, +libraries, pathnames, etc. + +@cindex @code{Description} field +@cindex @code{>Description:} +@item >Description: +(@sc{MultiText}) Precise description of the problem. + +@cindex @code{How-To-Repeat} field +@cindex @code{>How-To-Repeat:} +@item >How-To-Repeat: +(@sc{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 @ref{Helpful hints,,Helpful hints}. + +@cindex @code{Fix} field +@cindex @code{>Fix:} +@item >Fix: +(@sc{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.) + +@end table + +@noindent +@sc{gnats} adds the following fields when the PR arrives at the Support +Site: + +@table @code +@cindex @code{Number} field +@cindex @code{>Number:} +@item >Number: +(@sc{Enumerated}) The incremental identification number for this PR. +@ifclear SENDPR +This is included in the automated reply to the submitter (if that +feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing +your local configuration}). It is also included in the copy of the PR +that is sent to the maintainer. +@end ifclear + +The @samp{>Number:} field is often paired with the @samp{>Category:} +field as + +@smallexample +@var{category}/@var{number} +@end smallexample + +@noindent +in subsequent email messages. This is for historical reasons, as well +as because Problem Reports are stored in subdirectories which are named +by category. + +@cindex @code{State} field +@cindex @code{>State:} +@item >State: +(@sc{Enumerated}) The current state of the PR. Accepted values are: + +@table @code +@item open +The PR has been filed and the responsible person notified. + +@item analyzed +The responsible person has analyzed the problem. + +@item feedback +The problem has been solved, and the originator has been given a patch +or other fix. + +@item closed +The changes have been integrated, documented, and tested, and the +originator has confirmed that the solution works. + +@item suspended +Work on the problem has been postponed. +@end table + +@noindent +The initial state of a PR is @samp{open}. @xref{States,,States of +Problem Reports}. + +@cindex @code{Responsible} field +@cindex @code{>Responsible:} +@item >Responsible: +(@sc{Text}) The person responsible for this category. +@ifclear SENDPR +@sc{gnats} retrieves this information from the @file{categories} file +(@pxref{categories,,The @code{categories} file}). +@end ifclear + +@cindex @code{>Arrival-Date:} +@cindex @code{Arrival-Date} field +@item >Arrival-Date: +(@sc{Text}) The time that this PR was received by @sc{gnats}. The date +is provided automatically by @sc{gnats}. + +@cindex @code{>Audit-Trail:} +@cindex @code{Audit-Trail} field +@item >Audit-Trail: +(@sc{MultiText}) Tracks related electronic mail as well as changes in +the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields: + +@table @code +@cindex @code{State-Changed-<From>-<To>:} in @code{>Audit-Trail:} +@item @w{State-Changed-<From>-<To>: @var{oldstate}>-<@var{newstate}} +The old and new @samp{>State:} field values. + +@cindex @code{Responsible-Changed-<From>-<To>:} in @code{>Audit-Trail:} +@item @w{Responsible-Changed-<From>-<To>: @var{oldresp}>-<@var{newresp}} +The old and new @samp{>Responsible:} field values. + +@cindex @code{State-Changed-By:} in @code{>Audit-Trail:} +@cindex @code{Responsible-Changed-By:} in @code{>Audit-Trail:} +@item State-Changed-By: @var{name} +@itemx Responsible-Changed-By: @var{name} +The name of the maintainer who effected the change. + +@cindex @code{State-Changed-When:} in @code{>Audit-Trail:} +@cindex @code{Responsible-Changed-When:} in @code{>Audit-Trail:} +@item State-Changed-When: @var{timestamp} +@itemx Responsible-Changed-When: @var{timestamp} +The time the change was made. + +@cindex @code{State-Changed-Why:} in @code{>Audit-Trail:} +@cindex @code{Responsible-Changed-Why:} in @code{>Audit-Trail:} +@item State-Changed-Why: @var{reason@dots{}} +@itemx Responsible-Changed-Why: @var{reason@dots{}} +The reason for the change. +@end table + +@cindex subsequent mail +@cindex other mail +@cindex appending PRs +@cindex saving related mail +@cindex related mail +@noindent +The @samp{>Audit-Trail:} field also contains any mail messages received +by @sc{gnats} related to this PR, in the order received. + +@cindex @code{>Unformatted:} +@cindex @code{Unformatted} field +@item + >Unformatted: +(@sc{MultiText}) Any random text found outside the fields in the +original Problem Report. +@end table +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/flowchart.txt Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,35 @@ ++===========+ +===========+ +===========+ +# USER SITE # # USER SITE # # USER SITE # +# # # # # # +# *send-pr* # # *send-pr* # # *send-pr* # ++=====|=====+ +=====|=====+ +=====|=====+ + | V | + `---------> Email.... <-------' + ,---> | ++===============|=========|===================+ +# SUPPORT SITE | `---> /etc/aliases # +# *send-pr* | # +# +-----------------------------V--------+# +# | GNATS GNATS_ROOT/gnats-queue/|# +# | | |# +# | _________ V |# +# | |*file-pr*|<--- *queue-pr -r* |# +# | | | |# +# _ | | valid | |# +# |M| | |Category?|N--. |# +# |A| | |_________| | GNATS |# +# |I| | Y| | ADMINISTRATOR |# +# |N| | | | |# +# |T|<----------------| | |# +# |A| | | | .-> *edit-pr* |# +# |I|--->*edit-pr*-. | V | | |# +# |N| | | |GNATS_ROOT/pending | |# +# |E|<--*query-pr* | | | |# +# |R| | | | | | |# +# |S| | | V V V |# +# |_| |+------------------------------------+|# +# || GNATS Database ||# +# || GNATS_ROOT/CATEGORY/GNATS-ID ||# +# |+------------------------------------+|# +# +--------------------------------------+# ++=============================================+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/gnats.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,905 @@ +\input texinfo @c -*-texinfo-*- +@setfilename gnats.info + +@include version.texi + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Keeping Track: (gnats). GNU Problem Report Management System +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1993, 1995 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 + +@c NOTE TO ANYONE FORMATTING THIS DOCUMENT FOR PRINTING... +@c Comment the following line out if you don't have access to a +@c PostScript printer or viewer + +@set POSTSCRIPT + +@settitle Keeping Track +@setchapternewpage odd +@finalout +@titlepage +@title Keeping Track +@subtitle Managing Messages With GNATS +@subtitle The @sc{gnu} Problem Report Management System +@subtitle Version @value{VERSION} +@subtitle January 1996 +@author Jeffrey M. Osier +@author Brendan Kehoe +@author Cygnus Support +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 1995 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 + +@node Top +@top Overview +@cindex overview to GNATS +@cindex foreword + +This manual documents @sc{gnats}, the @sc{gnu} Problem Report Management +System, version @value{VERSION}. @sc{gnats} is a bug-tracking tool +designed for use at a central @dfn{Support Site}. Users who experience +problems use electronic mail to communicate these problems to +@dfn{maintainers} at that Support Site. @sc{gnats} partially automates +the tracking of these @dfn{Problem Reports} (@dfn{PR}s) by: + +@itemize @bullet +@item +organizing problem reports into a database and notifying responsible +parties of suspected bugs; + +@item +allowing support personnel and their managers to edit and query +accumulated bugs; and + +@item +providing a reliable archive of problems (and their subsequent +solutions) with a given program. +@end itemize + +@sc{gnats} offers many of the same features offered by more generalized +databases, including editing, querying, and basic reporting. The +@sc{gnats} database itself is an ordered repository for problem reports; +each PR receives a unique, incremental @dfn{PR number} which identifies +it throughout its lifetime. For a discussion on the working system +adopted by @sc{gnats}, see @ref{Paradigm,,The database paradigm}. + +You can access the submitting, editing, and querying functions of +@sc{gnats} from within @sc{gnu} Emacs. @xref{Invoking the +tools,,Invoking the @sc{gnats} tools}. + +@menu +* Introduction:: Introducing GNATS +* Invoking the tools:: Invoking the GNATS tools +* Management:: GNATS Administration +* Installation:: Installing GNATS +* Locations:: Where @sc{gnats} lives +* Regexps:: Querying using regular expressions +* Index:: +@end menu + +@c =============================================================== +@node Introduction +@chapter Introducing @sc{gnats} +@cindex introduction to GNATS +@cindex rationale +@cindex database rationale + +Any support organization realizes that a large amount of data flows back +and forth between the maintainers and the users of their products. This +data often takes the form of problem reports and communication via +electronic mail. @sc{gnats} addresses the problem of organizing this +communication by defining a database made up of archived and indexed +electronic mail messages. + +@sc{gnats} was designed as a tool for software maintainers. It consists +of several utilities which, when used in concert, formulate and +administer a database of Problem Reports grouped by site-defined +@dfn{problem categories}. It allows a support organization to keep +track of problems (hence the term @dfn{Problem Report}) in an organized +fashion. Essentially, @sc{gnats} acts as an active archive for +field-separated textual data submitted through electronic mail. + +@menu +* Paradigm:: The database paradigm +* Flowchart:: Flowchart of GNATS activities +* States:: States of Problem Reports +* Fields:: Problem Report format +@end menu + +@node Paradigm +@section The database paradigm +@cindex paradigm +@cindex database paradigm +@cindex why GNATS +@cindex support site +@cindex maintenance +@cindex so what does it do + +It is in your best interest as the maintainer of a body of work to +organize the feedback you receive on that work, and to make it easy for +users of your work to report problems and suggestions. + +@sc{gnats} makes this easy by automatically filing incoming problem +reports into appropriate places, by notifying responsible parties of the +existence of the problem and (optionally) sending an acknowledgement to +the submitter that the report was received, and by making these Problem +Reports accessible to queries and easily editable. @sc{gnats} is a +database specialized for a specific task. + +@sc{gnats} was designed for use at a Support Site that handles a high +level of problem-related traffic though electronic mail. It maintains +Problem Reports in the form of text files with defined @dfn{fields} +(@pxref{Fields,,@sc{gnats} data fields}). The location of the database, +as well as the categories it accepts as valid, the maintainers for whom +it provides service, and the submitters from whom it accepts Problem +Reports, are all definable by the @dfn{Support Site}. +@xref{Management,,@sc{gnats} administration}. + +@cindex what is a PR +Each PR is a separate file within a main repository +(@pxref{Locations,,Where @sc{gnats} lives}). Editing access to the +database is regulated to maintain consistency, but anyone with +electronic mail access may submit Problem Reports. To make queries on +the database faster, an index is kept automatically (@pxref{index +file,,The @code{index} file}). + +We provide several software tools so that users may submit new Problem +Reports, edit existing Problem Reports, and query the database. + +@itemize @bullet +@item +@w{@code{send-pr}} is used by both product maintainers and the end users +of the products they support to submit PRs to the database. + +@item +@w{@code{edit-pr}} is used by maintainers to use when editing problem +reports in the database. + +@item +Maintainers, managers and administrators can use @w{@code{query-pr}} to +make inquiries about indidvidual PRs or groups of PRs. + +@end itemize + +@code{send-pr} can also be packaged by itself and distributed to anyone +you wish to receive Problem Reports from; see @ref{mkdist,,Configuring +@code{send-pr} for the outside world}. + +@cindex GNATS administrator +At the Support Site, a @sc{gnats} @dfn{administrator} is charged with the +duty of maintaining @sc{gnats}. These duties are discussed in detail in +@ref{Management,,@sc{gnats} Administration}, and generally include +configuring @sc{gnats} for the Support Site, editing PRs that @sc{gnats} +cannot process, pruning log files, setting up new problem categories, +backing up the database, and distributing @code{send-pr} so that others +may submit Problem Reports. + +Responsibility for a given Problem Report depends on the category of the +problem. Optionally, an automated reminder can be sent to the +responsible person if a problem report is neglected for a requisite time +period. @xref{Local configuration,,Changing your local configuration}. + +@cindex @code{pending} directory +@cindex unparseable incoming PRs +@cindex incoming PRs that @sc{gnats} cannot parse +@sc{gnats} does not have the ability to decipher random text, so any +problem reports which arrive in a format @sc{gnats} does not recognize +are placed in a separate directory pending investigation by the +@sc{gnats} administrator (@pxref{Management,,@sc{gnats} Administration}). + +Once a problem is recorded in the database, work can begin toward a +solution. A problem's initial @dfn{state} is @samp{open} +(@pxref{States,,States of Problem Reports}). An acknowledgement is sent +to the originator of the bug report (if that feature of @sc{gnats} is +activated). @sc{gnats} forwards copies of the report to the party +responsible for that problem category and to the person responsible for +problems arriving from that @dfn{Submitter Site}. +@c (@pxref{Glossary,,Glossary}). + +When a problem has been identified, the maintainer can change its state +to @samp{analyzed}, and then to @samp{feedback} when a solution is +found. Each time the state of a PR changes, the submitter of the +problem report is notified of the reason for the change. If the party +responsible for the PR changes, the previous responsible party and the +new responsible party receive notice of the change. The change and +reason are also recorded in the @samp{>Audit-Trail:} field of the +Problem Report. (@xref{edit-pr,,Editing existing Problem Reports}. For +information on the @samp{>Audit-Trail:} field, see @ref{Fields,,Problem +Report format}.) + +When the originator of the Problem Report confirms that the solution +works, the maintainer can change the state to @dfn{closed}. If the PR +cannot be closed, the maintainer can change its state to @dfn{suspended} +as a last resort. (For a more detailed description of these states, see +@ref{States,,States of Problem Reports}.) + +@node Flowchart +@section Flowchart of @sc{gnats} activities +@cindex flowchart of GNATS activities +@cindex visual map of data flow + +This informal flowchart shows the relationships of the @sc{gnats} tools +to each other and to the files with which they interoperate. + +@sp 2 + +@ifset POSTSCRIPT +@tex +\input epsf +\epsffile{flowchart.eps} +@end tex +@end ifset + +@ifinfo +@clear POSTSCRIPT +@end ifinfo + +@ifclear POSTSCRIPT +@cartouche +@smallexample +@include flowchart.txt +@end smallexample +@end cartouche + +@end ifclear + +@sp 2 + +@c --------------------------------------------------------------- + +@include states.texi + +@c --------------------------------------------------------------- +@include fields.texi + +@c =============================================================== + +@include p-usage.texi + +@c =============================================================== + +@include p-admin.texi + +@c =============================================================== + +@node Installation +@appendix Installing @sc{gnats} + +@include p-inst.texi + +@c =============================================================== + +@node Locations +@appendix Where @sc{gnats} lives +@cindex locations +@cindex where GNATS lives +@cindex default installation locations + +We use a few conventions when referring to the installation structure +@sc{gnats} uses. These values are adjustable when you build and install +@sc{gnats} (@pxref{Installation,,Installing @sc{gnats}}). + +@menu +* prefix:: +* exec-prefix:: +* GNATS_ROOT:: +* defaults:: Default installation locations +@end menu + +@node prefix +@section @var{prefix} +@cindex @var{prefix} + +@var{prefix} corresponds to the variable @samp{prefix} for +@code{configure}, which passes it on to the @file{Makefile} it creates. +@var{prefix} sets the root installation directory for +@dfn{host-independent} files as follows: + +@c FIXME - check these +@table @asis +@item libraries +@file{@var{prefix}/lib}@* + +@item @code{man} pages +@file{@var{prefix}/man} + +@item @code{info} documents +@file{@var{prefix}/info} + +@item @code{include} files +@file{@var{prefix}/include} + +@item @emph{etc@dots{}} +@end table + +The default value for @var{prefix} is @w{@file{/usr/local}}, which can +be changed on the command line to @code{configure} using + +@smallexample +configure --prefix=@var{prefix} @dots{} +@end smallexample + +@noindent +@xref{Configure and make,,Configuring and compiling the software}. + +@node exec-prefix +@section @var{exec-prefix} +@cindex @var{exec-prefix} + +@var{exec-prefix} corresponds to the variable @samp{exec_prefix} for +@code{configure}, which passes it on to the @file{Makefile} it creates. +@w{@var{exec-prefix}} sets the root installation for +@dfn{host-dependent} files as follows: + +@c FIXME - check these +@table @asis +@item binary tools +@file{@var{exec-prefix}/bin} + +@item binary support utilities +@file{@var{exec-prefix}/lib/gnats} + +@item compiled libraries +@file{@var{exec-prefix}/lib}@* + +@item @emph{etc@dots{}} +@end table + +Since most installations are not intended to be distributed around a +network, the default value for @w{@var{exec-prefix}} is the value of +@samp{prefix}, i.e., @w{@file{/usr/local}}. However, using +@var{exec-prefix} saves space when you are installing a package on +several different platforms for which many files are identical; rather +than duplicate them for each host, these files can be shared in a common +repository, and you can use symbolic links on each host to find the +host-dependent files. @emph{It is not necessary to use this paradigm +when building the @sc{gnats} tools}. @xref{Configure and +make,,Configuring and compiling the software}. + +Use @var{exec-prefix} in conjunction with @var{prefix} to share +host-independent files, like libraries and @code{info} documents. For +example: + +@smallexample + @emph{for each host:} +configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-@var{host} +make all install @dots{} +@end smallexample + +@noindent +Using this paradigm, all host-dependent binary files are installed into +@w{@file{/usr/gnu/H-@var{host}/bin}}, while files which do not depend on +the host type for which they were configured are installed into +@w{@file{/usr/gnu}}. + +You can then use a different symbolic link for @w{@file{/usr/gnu}} +on each host (@file{/usr} is usually specific to a particular machine; +it is always specific to a particular architecture). + +@smallexample + @emph{on host-1:} +ln -s /usr/gnu/H-@var{host-1} /usr/gnu + @emph{on host-2:} +ln -s /usr/gnu/H-@var{host-2} /usr/gnu +@end smallexample + +@noindent +To the end user, then, placing @w{@file{/usr/gnu/bin}} in her or his +@code{PATH} simply works transparently for each @var{host} type. + +You can change @w{@var{exec-prefix}} on the command line to +@code{configure} using + +@smallexample +configure --exec-prefix=@var{exec-prefix} @dots{} +@end smallexample + +We recommend that you consult @ref{Using configure,,Using +@code{configure},configure,Cygnus configure}, before attempting this. +Again, @emph{it is not necessary to use this paradigm when building the +@sc{gnats} tools}. + +@node GNATS_ROOT +@section @var{GNATS_ROOT} +@cindex @var{GNATS_ROOT} + +The location of the database and the administrative data files, by +default @w{@file{@var{prefix}/lib/gnats/gnats-db}}. You can change this +value on the command line to @code{configure} using + +@smallexample +configure --with-gnats-root=@w{@var{GNATS_ROOT}} +@end smallexample + +@noindent +Administrative data files reside in @w{@file{@var{GNATS_ROOT}/gnats-adm}}. +These include @file{categories}, @file{submitters}, @file{responsible}, +and @file{config}, as well as two files generated and maintained by +@sc{gnats}, @file{index} and @file{current}. @xref{Local configuration,, +Changing your local configuration}, and @ref{Admin files,,Administrative +data files}. + +@node defaults +@section Default installation locations +@cindex default installation locations + +@table @asis +@item @var{prefix} +defaults to @file{/usr/local}; change using @code{configure} +(@pxref{Configure and make,,Configuring and compiling the software}). + +@item @var{exec-prefix} +defaults to @var{prefix}; change using @code{configure} +(@pxref{Configure and make,,Configuring and compiling the software}). + +@item @w{@var{GNATS_ROOT}} +defaults to @w{@file{@var{prefix}/lib/gnats/gnats-db}}; change using +@code{configure} (@pxref{Configure and make,,Configuring and compiling +the software}). +@end table + +@noindent +@sc{gnats} installs tools, utilities, and files into the following +locations. + +@table @code + +@item @var{exec-prefix}/bin + +@table @code +@item send-pr +@xref{send-pr,,Submitting Problem Reports}. +@item edit-pr +@xref{edit-pr,,Editing existing Problem Reports}. +@item query-pr +@xref{query-pr,,Querying the database}. +@item nquery-pr +@xref{query-pr,,Querying the database over the network}. +@end table + +@item @var{exec-prefix}/lib/gnats + +@table @code +@item mkcat +@xref{mkcat,,Adding a problem category}. +@item rmcat +@xref{rmcat,,Removing a problem category}. +@item mkdist +@xref{mkdist,,Configuring @code{send-pr} for the outside world}. +@item gen-index +@xref{gen-index,,Regenerating the index}. +@item queue-pr +@xref{queue-pr,,Handling incoming traffic}. +@item file-pr +@xref{file-pr,,Processing incoming traffic}. +@ignore +@item gnatsd +@xref{gnats,,Remote @sc{gnats} daemon}. +@end ignore +@item at-pr +@xref{at-pr,,Timely reminders}. +@item pr-edit +@xref{pr-edit,,The @code{edit-pr} driver}. +@ignore +@item npr-edit +@xref{npr-edit,,The remote @code{edit-pr} driver}. +@end ignore +@item pr-addr +@xref{pr-addr,,Address retrieval}. +@item libiberty.a +The @sc{gnu} @code{libiberty} library. +@end table + +@item @var{prefix}/lib/gnats/dist + +@table @asis +@item A packageable distribution of @code{send-pr}. +@xref{mkdist,,Configuring @code{send-pr} for the outside world}. +@end table + +@item @var{prefix}/lib/gnats + +@table @var +@item site +The local list of valid categories, used by @code{send-pr}; @var{site} +is the value of @samp{GNATS_SITE} (@pxref{config,,The @code{config} +file}). +@end table + +@item @var{prefix}/lib/emacs/lisp + +@table @code +@item gnats.el +@itemx gnats.elc +The Emacs versions of the programs @code{query-pr}, @code{edit-pr}, and +@code{view-pr}. @xref{Invoking the tools,,Invoking the @sc{gnats} +tools}. To change this directory you must alter @file{Makefile.in}; see +@ref{Configure and make,,Configuring and compiling the software}. +@item send-pr.el +The Emacs version of the program @code{send-pr}. +@xref{send-pr,,Submitting Problem Reports}. +@end table + +@item @var{prefix}/info + +@table @code +@item gnats.info +@itemx send-pr.info +The @sc{gnats} manuals, in a form readable by @code{info} (the @sc{gnu} +hypertext browser). @xref{Info,,Reading GNU Online +Documentation,infoman,GNU Online Documentation}. +@end table + +@item @var{prefix}/man/man1 +@itemx @var{prefix}/man/man8 + +@table @asis +@item @code{man} pages for all the @sc{gnats} tools and utilities. +@xref{Invoking the tools,,Invoking the @sc{gnats} tools}. +@end table + +@c FIXME - does this happen? +@item @var{prefix}/src + +@table @asis +@item Source code for @sc{gnats}. +@end table + +@item @var{prefix}/sample + +@table @asis +@item Example administrative files, including @file{categories}, +@file{submitters}, @file{responsible}, and @file{config}. @xref{Local +configuration,,Changing your local configuration}. +@end table + +@item @w{@var{GNATS_ROOT}} + +@table @code +@item gnats-adm +Administration and configuration data files. The files +@table @code +@item config +@item categories +@item submitters +@item responsible +@item gnatsd.conf +@item index +(@emph{This file is created by @sc{gnats}.}) +@item current +(@emph{This file is created by @sc{gnats}.}) +@end table +@noindent +exist here. @xref{Local configuration,,Changing your local +configuration}, and @ref{Admin files,,Administrative data files}. +@item gnats-queue +Incoming Problem Reports are queued here until the next iteration of +@w{@samp{queue-pr -r}} (@pxref{queue-pr,,Handling incoming traffic}). +@item pending +Problem Reports which arrive without a valid category value are +reassigned to the category @samp{pending} and placed here pending +intervention by the @sc{gnats} administrator. +@xref{Management,,@sc{gnats} administration}. +@item @var{category} +Each valid category has a corresponding subdirectory in the database. +All Problem Reports associated with that category are kept in that +subdirectory, along with lock files for PRs which are being edited. +@end table + +@end table + +@c =============================================================== +@node Regexps +@appendix Querying using regular expressions +@cindex querying using regexps +@cindex regular expressions +@cindex syntax of regexps + +@c FIXME - all my examples just use . and * +@sc{gnats} uses @sc{gnu} regular expression syntax with these settings: + +@smallexample +RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE +@end smallexample + +@noindent +This means that parentheses (@samp{(} and @samp{)}) and pipe symbols +(@samp{|}) do not need to be used with the escape symbol @samp{\}. The +tokens @samp{+} and @samp{?} do need the escape symbol, however. + +Unfortunately, we do not have room in this manual for an adequate +tutorial on regular expressions. The following is a basic summary of +some regular expressions you might wish to use. + +@xref{Regular Expression Syntax,,Regular Expression Syntax,regex,Regex}, +for details on regular expression syntax. Also see @ref{Regexps,,Syntax +of Regular Expressions,emacs,GNU Emacs Manual}, but beware that the +syntax for regular expressions in Emacs is slightly different. + +All search criteria options to @code{query-pr} rely on regular +expression syntax to construct their search patterns. For example, + +@smallexample +query-pr --state=open +@end smallexample + +@noindent +matches all PRs whose @samp{>State:} values match with the regular +expression @samp{open}. + +We can substitute the expression @samp{o} for @samp{open}, according +to @sc{gnu} regular expression syntax. This matches all values of +@samp{>State:} which begin with the letter @samp{o}. + +@smallexample +query-pr --state=o +@end smallexample + +is equivalent to + +@smallexample +query-pr --state=open +@end smallexample + +@noindent +in this case, since the only value for @samp{>State:} which matches the +expression @samp{o} is @samp{open}. (Double quotes (@kbd{"}) are used +to protect the asterix (@kbd{*}) from the shell.) @samp{--state=o} also +matches @samp{o}, @samp{oswald}, and even @samp{oooooo}, but none of +those values are valid states for a Problem Report. + +Regular expression syntax considers a regexp token surrounded with +parentheses, as in @w{@samp{(@var{regexp})}}, to be a @dfn{group}. This +means that @w{@samp{(ab)*}} matches any number of contiguous instances +of @samp{ab}, including zero. Matches include @samp{}, @samp{ab}, and +@samp{ababab}. + +Regular expression syntax considers a regexp token surrounded with +square brackets, as in @w{@samp{[@var{regexp}]}}, to be a @dfn{list}. +This means that @w{@samp{Char[(ley)(lene)(broiled)}} matches any of the +words @samp{Charley}, @samp{Charlene}, or @samp{Charbroiled} (case is +significant; @samp{charbroiled} is not matched). + +Using groups and lists, we see that + +@smallexample +query-pr --category="gcc|gdb|gas" +@end smallexample + +@noindent +is equivalent to + +@smallexample +query-pr --category="g(cc|db|as)" +@end smallexample + +@noindent +and is also very similar to + +@smallexample +query-pr --category="g[cda]" +@end smallexample + +@noindent +with the exception that this last search matches any values which begin +with @samp{gc}, @samp{gd}, or @samp{ga}. + +The @samp{.} character is known as a @dfn{wildcard}. @samp{.} matches +on any single character. @samp{*} matches the previous character +(except newlines), list, or group any number of times, including zero. +Therefore, we can understand @samp{.*} to mean ``match zero or more +instances of any character.'' For this reason, we never specify it at +the end of a regular expression, as that would be redundant. The +expression @samp{o} matches any instance of the letter @samp{o} +(followed by anything) at the beginning of a line, while the expression +@samp{o.*} matches any instance of the letter @samp{o} at the beginning +of a line followed by any number (including zero) of any characters. + +We can also use the expression operator @samp{|} to signify a logical +@code{OR}, such that + +@smallexample +query-pr --state="o|a" +@end smallexample + +@noindent +matches all @samp{open} or @samp{analyzed} Problem Reports. (Double +quotes (@kbd{"}) are used to protect the pipe symbol (@kbd{|}) from the +shell.) + +By the same token,@footnote{No pun intended.} using + +@smallexample +query-pr --state=".*a" +@end smallexample + +@noindent +matches all values for @samp{>State:} which contain an @samp{a}. (These +include @samp{analyzed} and @samp{feedback}.) + +Another way to understand what wildcards do is to follow them on their +search for matching text. By our syntax, @samp{.*} matches any +character any number of times, including zero. Therefore, @samp{.*a} +searches for any group of characters which end with @samp{a}, ignoring +the rest of the field. @samp{.*a} matches @samp{analyzed} (stopping at +the first @samp{a}) as well as @samp{feedback}. + +@emph{Note:} When using @samp{--text} or @samp{--multitext}, you do not +have to specify the token @samp{.*} at the beginning of @var{text} to +match the entire field. For the technically minded, this is because +@samp{--text} and @samp{--multitext} use @samp{re_search} rather than +@samp{re_match}. @samp{re_match} @dfn{anchors} the search at the +beginning of the field, while @samp{re_search} does not anchor the +search. + +For example, to search in the @code{>Description:} field for the text + +@smallexample +The defrobulator component returns a nil value. +@end smallexample + +@noindent +we can use + +@smallexample +query-pr --multitext="defrobulator.*nil" +@end smallexample + +To also match newlines, we have to include the expression @samp{(.|^M)} +instead of just a dot (@samp{.}). @samp{(.|^M)} matches ``any single +character except a newline (@samp{.}) @emph{or} (@samp{|}) any newline +(@samp{^M}).'' This means that to search for the text + +@smallexample +The defrobulator component enters the bifrabulator routine +and returns a nil value. +@end smallexample + +@noindent +we must use + +@smallexample +query-pr --multitext="defrobulator(.|^M)*nil" +@end smallexample + +To generate the newline character @samp{^M}, type the following +depending on your shell: + +@table @code +@item csh +@samp{@emph{control}-V @emph{control}-M} + +@item tcsh +@samp{@emph{control}-V @emph{control}-J} + +@item sh (@emph{or} bash) +Use the @key{RETURN} key, as in + +@smallexample +(.| +) +@end smallexample +@end table + +Again, see @ref{Regular Expression Syntax,,Regular Expression +Syntax,regex,Regex}, for a much more complete discussion on regular +expression syntax. + +@c =============================================================== + +@ignore +@c complete this someday... +@node Glossary +@unnumbered Glossary + +@table @strong +@item PR +Short for ``Problem Report''. An electronic mail message which reports +a problem. A @dfn{record} in the @sc{gnats} database. + +@item Support Site +A central site that provides resources for maintainers of a body of +work, such as a software package. We refer to the Support Site as the +location where @sc{gnats} is installed and functional. + +@item Database +An organized collection of information. + +@item @sc{gnats} +The @sc{gnu} Problem Report Management System. + +@item Field +A location for specific information. A group of fields make up a +Problem Report. + +@item Mail header +Defined by the Internet Internet standard RFC-822 + +@item Category +@item Submitter +@item Originator +@item Query +@item Report +@item Site +@item Edit +@item Submit +@item Bug +@item State +@item ID Number +@item Synopsis +@item Confidential +@item Severity +@item Priority +@item Responsible +@item Configuration +@item Class +@item Environment +@item Description +@item Audit-Trail +@item Unformatted +@item Fix +@item Release +@item Makefile +@item gnats-admin +@item pending +@item send-pr +@item edit-pr +@item Maintainers +@item timestamp +@item utility +@item tool + +@end table + +@end ignore + +@node Index +@unnumbered Index + +@printindex cp + +@contents + +@bye +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/p-admin.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,1262 @@ +@node Management +@chapter @sc{gnats} Administration +@cindex administering @sc{gnats} +@cindex managing @sc{gnats} +@cindex GNATS management +@cindex duties for @code{gnats-admin} + +In daily usage, @sc{gnats} is self-maintaining. However, there are +various administrative duties which need to be performed periodically: + +@table @emph +@item emptying the @code{pending} directory +@cindex emptying the @code{pending} directory +If a Problem Report arrives with a @samp{>Category:} value that is +unrecognized by the @file{categories} file, or if that field is missing, +@sc{gnats} places the PR in the @w{@file{pending}} directory +(@pxref{Locations,,Where the tools and utilities reside}). @sc{gnats} +has no way of knowing which subdirectory the PR should be filed under. +@sc{gnats} sends a notice to the @code{gnats-admin} and to the party +responsible for that submitter (as listed in the @file{submitters} file) +when this occurs. + +To file these PRs, simply use @code{edit-pr} to repair the problematic +fields in each file in the @file{pending} directory. Be sure to change +the @samp{>Category:} field of the PR from @samp{pending} to an +appropriate category. In many cases the culprit is simply a +typographical error, although it may be necessary sometimes to contact +the submitter of the PR to decipher her or his intentions. + +Should you run out of disk space, there may be an empty PR in the +@file{pending} directory. In that case, look in the file +@w{@file{@var{GNATS_ROOT}/gnats-adm/bug.log}}, which should still contain +the full message that was submitted. + +@item adding new categories +@cindex adding a problem category +@cindex @code{mkcat} +To add a new category, simply insert a new line in the +@w{@file{categories}} file and then run the program @code{mkcat}. + +@emph{Note}: this causes all category lists for @code{send-pr} (except +the one on the local machine) to become outdated. Copy the new list on +to every machine on your network that has @code{send-pr} installed, and +make sure you advise remote submitters that the category list has +changed. @xref{mkcat,,Adding a problem category}. Also +@ref{categories,,The @code{categories} file}. + +@item removing categories +@cindex removing a problem category +@cindex @code{rmcat} +To remove a category, you need to make sure the relevant subdirectory is +empty (in other words, make sure no PRs exist for the category you wish +to remove). You can then remove the category listing from the +@file{categories} file, and invoke + +@smallexample +rmcat @var{category@dots{}} +@end smallexample + +@noindent +to remove @var{category} (any number of categories may be specified on +the command line to @code{rmcat}, so long as they abide by the above +constraints). + +@emph{Note}: this causes all category lists for @code{send-pr} (except +the one on the local machine) to become outdated. Copy the new list on +to every machine on your network that has @code{send-pr} installed, and +make sure you advise remote submitters that the category list has +changed. @xref{rmcat,,Removing a problem category}. Also +@ref{categories,,The @code{categories} file}. + +@item adding and removing maintainers +@cindex adding and removing maintainers +Edit the @file{responsible} file to add a new maintainer or to remove an +existing maintainer. @xref{responsible,,The @code{responsible} file}. + +@item building a distribution of @code{send-pr} +@cindex building a distribution of @code{send-pr} +@cindex @code{mkdist} +You can build a distribution of @code{send-pr} which contains valid +information for your site by invoking the command @code{mkdist}. +@xref{mkdist,,Configuring @code{send-pr} for the outside world}. You +can then distribute your customized @w{@code{send-pr}} to your +customers, friends, relatives, etc., so that they can submit Problem +Reports to your database. + +@item building a new index +@cindex building a new index +@cindex @code{gen-index} +If your index becomes corrupted, or if you wish to generate a new one +for some reason, use the program @code{gen-index} +(@pxref{gen-index,,Regenerating the index}). + +@item pruning log files +@cindex pruning log files +Log files often grow to unfathomable proportions. As with gardening, it +is best to prune these as they grow, lest they take over your disk and +leave you with no room to gather more Problem Reports. If you keep log +files, be sure to keep an eye on them. (@xref{Aliases,,Setting up mail +aliases}.) +@c "gather ye rosebugs while ye may..." + +@item BACKING UP YOUR DATA +@cindex BACK UP YOUR DATA +Any database is only useful if its data remains uncorrupted and safe. +Performing periodic backups ensures that problems like disk crashes and +data corruption are reversible. + +@end table + +@xref{Locations,,Where @sc{gnats} lives}. + +@menu +* Networked management:: Managing GNATS over a network +* Local configuration:: Changing your local configuration +* Admin files:: Administrative data files +* Admin utils:: Administrative utilities +* Internal utils:: Internal utilities +@end menu + +@node Networked management +@section Managing @sc{gnats} over a network +@cindex networked management +@cindex managing @sc{gnats} over a network + +If you have installed the @sc{gnats} user tools on machines around your +local network, there are a few things you need to remember. + +@code{mkcat} and @code{rmcat} do not update the categories list for +other machines on your network which have @code{send-pr} installed, +unless those machines share @var{prefix} with the host machine). To +update these lists, copy the @code{send-pr} categories list to each of +the other hosts. This categories list is +@w{@file{@var{prefix}/lib/gnats/@var{site}}}, where @var{site} is the +name tag for your local site, as specified in the @file{config} file as +@samp{GNATS_SITE} (@pxref{config,,The @code{config} file}). + +It is also important to note that only your local @code{send-pr} has +access to this new information; any copies of @code{send-pr} which you +have distributed to outside submitters now have outdated category lists. +You must either contact your submitters and instruct them to update +their copy of the categories list, which they installed in +@w{@file{@var{prefix}/lib/gnats/@var{support-site}}} from the +distribution you provided, or you must build another distribution of +@code{send-pr} with this new information and redistribute it. + +If you need to use @sc{gnats} utilities, like @code{query-pr} and +@code{edit-pr}, on other systems besides the one where @sc{gnats} itself +resides, @pxref{Installing tools,,Installing the user tools}. + +@c FIXME - anything else? + +@node Local configuration +@section Changing your local configuration +@cindex local configuration +@cindex changing your local configuration + +@xref{Locations,,Where @sc{gnats} lives}. + +Your local configuration is determined by the data files in the +directory @w{@file{@var{GNATS_ROOT}/gnats-adm}}. These can be altered at +any time by editing the pertinent file. + +@table @code +@cindex @code{config} file +@item config +Variables which control certain behavior. @xref{config,,The +@code{config} file}. Behaviors you can change here include + +@itemize @bullet +@item +The address where your site receives Problem Reports. + +@item +The address of the @sc{gnats} administrator. + +@item +The nametag for your Support Site (your organization, company, +group, etc.). + +@item +The nametag for your local Submitter Site. + +@item +The default release for your site. + +@item +The default value for the @samp{>Organization:} field (this value +appears as the default when you run @code{send-pr}). + +@item +Whether or not to remind maintainers if a requisite time period has +passed before they change the state of a Problem Report to +@samp{analyzed}. (Also see @ref{submitters,,The @code{submitters} +file}, and @ref{at-pr,,Timely Reminders}. + +@item +Whether or not to send an automatic acknowledgement to the originator of +a problem report when the @sc{gnats} first receives the PR. + +@item +The value @sc{gnats} assigns to PRs which come in with missing or unknown +values for the @samp{>Submitter-Id:} field. + +@item +Whether or not @sc{gnats} should retain @samp{Received:} +mail headers from incoming mail. + +@item +Whether or not @sc{gnats} is in a mode for debugging. + +@item +The values which define business hours. +@end itemize + +@cindex @code{categories} file +@item categories +The list of categories that @sc{gnats} accepts as valid for the +@samp{>Category:} field, and the maintainers responsible for each +category. Update this file whenever you have a new category, or +whenever a category is no longer valid. You must also update this file +whenever responsiblility for a category changes, or if a maintainer is +no longer valid. @xref{categories,,The @code{categories} file}. Also +see @ref{mkcat,,Adding a new problem category}, and @ref{rmcat,,Removing +a problem category}. + +@cindex @code{responsible} file +@item responsible +The list of maintainers. Update this file whenever you have a new +maintainer, or whenever a maintainer is no longer valid. +@xref{responsible,,The @code{responsible} file}. + +@cindex @code{submitters} file +@item submitters +The list of Submitter Sites from whom @sc{gnats} accepts Problem Reports. +This file is mandatory, although the feature it provides is not; see +@ref{submitters,,The @code{submitters} file}. +@end table + +@menu +* default behavior:: +* config:: The `config' file +* categories:: The `categories' file +* responsible:: The `responsible' file +* submitters:: The `submitters' file +@end menu + +@node default behavior +@subsection Default behavior + +The default behavior for @sc{gnats} is as follows: + +@cindex default behavior +@itemize @bullet +@item +The address where your site receives Problem Reports is @samp{bugs} (a +local address). + +@item +The address of the @sc{gnats} administrator is @samp{gnats-admin} (a local +address). + +@item +The nametag for your Support Site (your organization, company, group, +etc.) is the second-to-last field in your domain name. + +@item +The nametag for your local Submitter Site is the nametag for your +Support Site. + +@item +The default release for your site is @samp{unknown-1.0}. + +@item +The default value for the @samp{>Organization:} field (this value appears as the +default when you run @code{send-pr}) is the nametag for your Support +Site. + +@item +@sc{gnats} reminds maintainers if a requisite time period has passed +before they change the state of a Problem Report to @samp{analyzed}. + +@item +An automatic acknowledgement is sent to the originator of a problem +report when the @sc{gnats} first receives the PR. + +@item +The value @sc{gnats} assigns to the @samp{>Submitter-Id:} field in PRs +which arrive with missing or unknown values for that field is +@samp{unknown}. + +@item +@samp{Received@dots{}} mail headers are retained. + +@item +@sc{gnats} is not in a debugging mode. + +@item +@dfn{business hours} are defined as 8:00am to 5:00pm, Monday through +Friday. +@end itemize + + +@node config +@subsection The @code{config} file +@cindex @code{config} file + +Much of the behavior @sc{gnats} exhibits depends on the values of fields +in the file @w{@file{@var{GNATS_ROOT}/gnats-adm/config}}. The +@file{config} file contains a list of variables (using Bourne-shell +syntax) which control the following behavior. These values can be +changed at any time; the new values take effect for all subsequent +iterations of the tools. + +@table @code +@cindex @code{GNATS_ADDR} +@item GNATS_ADDR="@var{address}" +The address where your site receives Problem Reports. This address is +aliased in the file @w{@file{/etc/aliases}} so that it directs incoming +mail into @code{queue-pr} (@pxref{Installing utils,,Installing the +utilities}). + +The default is @samp{bugs} (a local address). + +@cindex @code{GNATS_ADMIN} +@item GNATS_ADMIN="@var{address}" +The address of the @sc{gnats} administrator. Normally this is set to +@samp{gnats-admin}, which is an alias in @file{/etc/aliases} that points +toward the person responsible for administrating @sc{gnats}. +@xref{Installing utils,,Installing the utilities}. + +The default is @samp{gnats-admin} (a local address). + +@cindex @code{GNATS_SITE} +@item GNATS_SITE="@var{site}" +The nametag for your Support Site (your organization, company, group, +etc.). This nametag should also appear in the @file{submitters} file, +so that users at your site can submit Problem Reports locally. + +@var{site} is also used as the name of the file containing a valid +category list for your site. This file is installed locally as +@w{@file{@var{prefix}/lib/gnats/@var{site}}}. @emph{Warning:} if you +change this variable after @sc{gnats} is installed, you must also change +the name of this file, as well as the name of the alias for your local +submitters (@pxref{Aliases,,Setting up mail aliases}). + +The default is the second-to-last field in your domain name. For +example, if your domain name is @w{@samp{unleaded.truckstop.org}}, your +default @var{site} is @w{@samp{truckstop}}. + +@cindex @code{SUBMITTER} +@item SUBMITTER="@var{submitter-id}" +The nametag for your local Submitter Site (this value appears as the +default value for @samp{>Submitter-Id} when you run @code{send-pr}). +Even though you are a Support Site, if you submit Problem Reports to +your own organization you become a Submitter Site. The value +@var{submitter-id} is the default value for the @samp{>Submitter-Id:} +field that your maintainers see when they submit Problem Reports +locally. + +The default is the value of @samp{GNATS_SITE}. + +@cindex @code{DEFAULT_RELEASE} +@item DEFAULT_RELEASE="@var{release}" +The default release for your site (this value appears as the default +value for @samp{>Release:} when you run @code{send-pr}). + +The default is @samp{unknown-1.0}. + +@cindex @code{DEFAULT_ORGANIZATION} +@item DEFAULT_ORGANIZATION="@var{text}" +The default value for the @samp{>Organization:} field (this value +appears as the default when you run @code{send-pr}). + +The default is the value of @samp{GNATS_SITE}. + +@c FIXME - where else to mention this stuff? +@cindex @code{NOTIFY} +@item NOTIFY=@var{boolean} +Determines whether or not to remind maintainers if a requisite time +period has passed before they change the state of a Problem Report to +@samp{analyzed}. This feature uses the program @code{at-pr}; see +@ref{at-pr,,Timely Reminders}. + +This requisite time is determined for each submitter individually; see +@ref{submitters,,The @code{submitters} file}. The time is measured in +@dfn{business hours}, which by default are 8:00am to 5:00pm, Monday +through Friday. Business hours can be redefined by changing the +variables @code{BDAY_START}, @code{BDAY_END}, @code{BWEEK_START}, and +@code{BWEEK_END} in the @file{config} file (see below). + +If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} +is @samp{0}, the feature is turned off. The default value for +@samp{NOTIFY} is @samp{1}. + +@cindex @code{ACKNOWLEDGE} +@item ACKNOWLEDGE=@var{boolean} +Determines whether or not to send an automatic acknowledgement to the +originator of a problem report when the @sc{gnats} first receives the PR. + +If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} +is @samp{0}, the feature is turned off. The default for +@samp{ACKNOWLEDGE} is @samp{1}. + +The acknowledgment is of the form: + +@smallexample +@group +To: @var{your-address} +From: gnats +Subject: Re: @var{category}/@var{gnats-id}:@var{Synopsis} +In-Reply-To: Your message of @var{date} + +Thank you very much for your problem report. +It has the internal identification: @var{category}/@var{gnats-id} +The individual assigned to look at your bug is: + @var{responsible} + +Category: @var{category of the PR} +Responsible: @var{responsible} +Synopsis: @var{Synopsis from submitted PR} +Arrival-Date: @var{arrival date} +@end group +@end smallexample + +@cindex @code{DEFAULT_SUBMITTER} +@item DEFAULT_SUBMITTER="submitter-id" +The value @sc{gnats} assigns to PRs which come in with missing or unknown +values for the @samp{>Submitter-Id:} field. This value must also appear +in the @file{submitters} file; see @ref{submitters,,The +@code{submitters} file}. + +@cindex disabling @var{submitter-id} +To disable the feature of @sc{gnats} which tracks the +@samp{>Submitter-Id:}, simply alter the @file{submitters} file to only +contain the @var{submitter-id} value which appears in +@w{@code{DEFAULT_SUBMITTER}}, and and instruct your submitters to ignore +the field. + +The default value for @samp{DEFAULT_SUBMITTER} is @samp{unknown}. + +@cindex @code{KEEP_RECEIVED_HEADERS} +@item KEEP_RECEIVED_HEADERS=@var{boolean} +Determines whether or not @sc{gnats} should retain the +@w{@samp{Received:}} mail headers from incoming mail. These headers +often take up a lot of space, and they are seldom used. + +If @var{boolean} is @samp{1}, this feature is active. If @var{boolean} +is @samp{0}, the feature is turned off. The default value for +@samp{KEEP_RECEIVED_HEADERS} is @samp{1}. + +@item DEBUG_MODE=@var{boolean} +Determines whether or not @sc{gnats} is operating in a mode for +debugging. When @var{boolean} is @samp{1}, @sc{gnats} fowards all mail +to the @sc{gnats} administrator, @w{@code{gnats-admin}}. + +@cindex business hours +@item BDAY_START=@var{integer} +@itemx BDAY_END=@var{integer} +@itemx BWEEK_START=@var{integer} +@itemx BWEEK_END=@var{integer} +The definition of @dfn{business hours}. These values are only used if +@code{NOTIFY} is set to @samp{1} in the @file{config} file (see above). + +By default, business hours are 8:00am to 5:00pm Monday through Friday, +local time. + +@table @code +@item BDAY_START=@var{integer} +Defines the hour of the day when business hours begin. @var{integer} +values must fall between @samp{0} (midnight) and @samp{23} (11:00pm). +The default is @samp{8} (8:00am). + +@item BDAY_END=@var{integer} +Defines the hour of the day when business hours end. @var{integer} +values must fall between @samp{0} (midnight) and @samp{23} (11:00pm). +The default is @samp{17} (5:00pm). + +@item BWEEK_START=@var{integer} +Defines the beginning day of the business week. @var{integer} values +must fall between @samp{0} (Sunday) and @samp{6} (Saturday). The +default is @samp{1} (Monday). + +@item BWEEK_END=@var{integer} +Defines the ending day of the business week. @var{integer} values must +fall between @samp{0} (Sunday) and @samp{6} (Saturday). The default is +@samp{5} (Friday). +@end table + +@end table + +@node categories +@subsection The @code{categories} file +@cindex @code{categories} file + +The @file{categories} file contains a list of problem categories, +specific to your site, which @sc{gnats} tracks. This file also matches +responsible people with these categories. You must edit this file +initially, creating valid categories and then running @code{mkcat} to +create the corresponding subdirectories of @w{@code{@var{GNATS_ROOT}}} +and update the valid categories list for @w{@code{send-pr}}. For +instructions on running @code{mkcat}, see @ref{mkcat,,Adding a problem +category}. + +To create a new category, log in as @sc{gnats}, add a line to this file, +and run @code{mkcat}. Lines beginning with @samp{#} are ignored. + +A line in the @file{categories} file consists of four fields delimited +by colons, as follows: + +@smallexample +@var{category}:@var{description}:@var{responsible}:@var{notify} +@end smallexample + +@noindent +@table @var +@item category +A unique category name, made up of text characters. This name cannot +contain spaces or any of the following characters: + +@smallexample +! $ & * ( ) @{ @} [ ] ` ' " ; : < > ~ +@end smallexample + +@noindent +Ideally, category names should not contain commas or begin with periods. +Each line has a corresponding subdirectory in the main @sc{gnats} +directory (@var{GNATS_ROOT}). + +@ignore +It is possible that if you set up the database with categories +which contain characters that describe subdirectories, such as a slash +(@key{/}) in @sc{Unix}, you could effectively build subdirectories +within each category, and @sc{gnats} would read and write to these +files as it would any other. This is not recommended. It doesn't +break any of the existing tools, and is a fine way to keep category +directories from growing too large. It is, however, quite untested. +@end ignore + +@item description +A terse textual description of the category. + +@item responsible +The name tag of the party responsible for this category of problems, as +listed in the @file{responsible} file (@pxref{responsible,,The +@code{responsible} file}). + +@item notify +One or more other parties which should be notified when a Problem Report +with this category arrives, such as a project manager, other members of +the same project, other interested parties, or even log files. These +should be separated with commas. +@end table + +A good strategy for configuring this file is to have a different +category for each product your organization supports or wishes to track +information for, or perhaps with sub-categories within each category. +For instance, if you wish to track documentation problems in a variety of +areas, you could have entries such as + +@smallexample +doc:General Doc Questions:myboss:me,barney +doc-rock:Doc for ROCK program:me:myboss +doc-stone:Docs for STONE utils:barney:fred +doc-local:in-house documentation:me:doc-local-log +@end smallexample + +In the above example, the nametags @samp{myboss}, @samp{me}, +@samp{fred}, and @samp{barney} must be defined in the @file{responsible} +file (@pxref{responsible,,The @code{responsible} file}). + +Problem Reports with a category of @samp{doc} are sent to the local mail +address (or alias) @samp{myboss}, and also sent to the addresses +@samp{me} and @samp{barney}. PRs with a category of @samp{doc-rock} are +sent to the local addresses @samp{me} and @samp{myboss} only, while PRs +with the category @samp{doc-stone} are sent to @samp{fred} as well as to +@samp{barney}. PRs with a category of @samp{doc-local} are sent only to +@samp{me}, and are also filed in @code{doc-local-log} (in this case, an +alias should be set up in @file{/etc/aliases} to reflect a location for +the log file, such as @w{@samp{doc-local-log: /users/me/local-log}}). + +Whenever you add a new category, be sure to run @code{mkcat} to create a +subdirectory for it and update the local categories list. + +Only one category must be present for @sc{gnats} to function: + +@smallexample +pending:Category for faulty PRs: gnats-admin: +@end smallexample + +@cindex @code{pending} file +The @file{pending} directory is created automatically when you run +@w{@samp{make install}} (@pxref{Configure and make,,Configuring and +compiling the software}). + +@node responsible +@subsection The @code{responsible} file +@cindex @code{responsible} file + +This file contains a list of the responsible parties. Lines beginning +with @samp{#} are ignored. Each entry contains three fields, separated +by colons: + +@smallexample +@var{responsible}:@var{full-name}:@var{mail-address} +@end smallexample + +@noindent +@table @var +@item responsible +A name-tag description of the party in question, such as her or his user +name, or the name of the group. This name is listed in the PR in +the @samp{>Responsible:} field. + +@item full-name +The full name of the party (``Charlotte Bronte''; ``Compiler Group''). + +@item mail-address +The full, valid mail address of the party. This field is only necessary +if the responsible party has no local mail address or alias. +@end table + +@noindent +A sample @file{responsible} listing might be: + +@smallexample +ren:Ren Hoek: +stimpy:Stimpson J. Cat:stimpy@@lederhosen.org +@end smallexample + +Here, @code{ren} is a local user. @code{stimpy} is remote, so his full +address must be specified. + +The following entry must be present for @sc{gnats} to function: + +@smallexample +gnats-admin: GNATS administrator: +@end smallexample + +@noindent +(@code{gnats-admin} is a mail alias, so for this purpose +@code{gnats-admin} is a local address.) + +@node submitters +@subsection The @code{submitters} file +@cindex @code{submitters} file + +This is a database of sites which submit bugs to your support site. It +contains six fields delineated by colons. Lines beginning with @samp{#} +will be ignored. + +Entries are of the format: + +@smallexample +@var{submitter-id}:@var{name}:@var{type}:@var{resp-time}:@var{contact}:@var{notify} +@end smallexample + +@noindent +@table @var +@item submitter-id +A unique identifier for a specific site or other entity who submits +Problem Reports. + +@item name +A textual description of this entity. + +@item type +Optional description for the type of relationship this submitter to your +support site. This could indicate a contract type, a level of +expertise, etc., or it can remain blank. + +@item resp-time +Optional quoted response time, in @dfn{business hours}. @sc{gnats} is +capable of reminding responsible parties when Problem Reports marked +with a @samp{>Severity} value of @samp{critical}, or those with a +@samp{>Severity} of @samp{serious} and a @samp{>Priority} value of +@samp{high}, are neglected for a certain period. This argument defines +that response period for each @var{submitter-id}. Business hours are +defined by default as 8:00am to 5:00pm, Monday through Friday. For +example, three business days would be equal to 24 business hours. + +This function is active if the @code{NOTIFY} field is defined as +@samp{1} in the @file{config} file (@pxref{Local configuration,,Changing +your local configuration}). If @code{NOTIFY} is @samp{0}, this field is +ignored. For information on @code{at-pr}, the program which sends out +this reminder, see @ref{at-pr,,Timely Reminders}. + +@item contact +The name tag of the main @dfn{contact} at the Support Site for this +submitter. This contact should be in the @file{responsible} file +(@pxref{responsible,,The @code{responsible} file}). Incoming bugs from +@var{submitter} are sent to this contact. Optionally, this field can be +left blank. + +@item notify +Any other parties who should receive copies of Problem Reports sent in +by @var{submitter}. +@end table + +A few example entries in the @file{submitters} file: + +@smallexample +univ-hell: University of Hades:eternal:3:beelzebub:lucifer +tta: Telephones and Telegraphs of America:support:720:dave: +@end smallexample + +@noindent +In this example, when a PR comes in from the University of Hades (who +has an eternal contract), it should have @samp{univ-hell} in its +@samp{Submitter-Id} field. This Problem Report goes to @code{beelzebub} +(who should be in the @file{responsible} file), and if it is not +analyzed within three business hours a reminder message is sent. +@code{lucifer} also receives a copy of the bug, and a copy of the +reminder message as well (if it is sent). When Telephones and +Telegraphs of America utilizes their support contract and submits a bug, +a copy is sent only to @code{dave}, who has 720 business hours to return +an analysis before a reminder is sent. + +@cindex disabling @var{submitter-id} +To disable the feature of @sc{gnats} which tracks the +@samp{>Submitter-Id:}, simply alter the @file{submitters} file to only +contain the @var{submitter-id} value which appears as the +@samp{DEFAULT_SUBMITTER} value in the @file{config} file +(@pxref{config,,The @code{config} file}), and instruct your submitters +to ignore the field. + +@node Admin files +@section Administrative data files +@cindex admin files +@cindex files used for @sc{gnats} administration + +The following files are located in @file{@var{GNATS_ROOT}/gnats-adm}, +where @var{GNATS_ROOT} is the resident directory of @sc{gnats}. These +files are maintained by @sc{gnats}; you should never touch them. + +@menu +* index file:: The `index' file +* current file:: The `current' file +@end menu + +@node index file +@subsection The @code{index} file +@cindex @code{index} file + +The index is used to accelerate searches on the database by +@code{query-pr} and @code{edit-pr}. This file is not created until the +first PR comes in. It is then kept up to date by @sc{gnats}; you should +never touch this file. + +Any searches on subjects contained in the index are much faster than +searches which depend on data not in the index. The index contains +single-line entries for the following fields, in order, separated by +colons (@samp{:}) except for @samp{>Category:} and @samp{>Number:}, +which are separated by a slash (@samp{/}) (the @samp{>} and @samp{:} +Problem Report fieldname delimiters have been removed for the sake of +brevity and readability):: + +@smallexample +Category Number Submitter-Id +Responsible State Confidential +Severity Priority +@end smallexample + +To see an example index, run @code{gen-index} without any options +(@pxref{gen-index,,Regenerating the index}). + +@node current file +@subsection The @code{current} file +@cindex @code{current} file + +This file contains the last serial number assigned to an incoming PR. +It is used internally by @sc{gnats}; you need never touch this file. + +@node Admin utils +@section Administrative utilities +@cindex administrative utilities + +These tools are used by the @sc{gnats} administrator as part of the +periodic maintenance and configuration of @sc{gnats}. +@xref{Management,,@sc{gnats} Administration}. + +@menu +* mkcat:: Adding a problem category +* rmcat:: Removing a problem category +* gen-index:: Regenerating the index +* mkdist:: Configuring send-pr for the outside world +@end menu + +@node mkcat +@subsection Adding a problem category +@cindex @code{mkcat} +@cindex adding a problem category +@cindex new problem categories +@cindex @code{categories} file + +To add new categories to the database: + +@enumerate 1 +@item +Add a line to the @file{categories} file under +@w{@file{@var{GNATS_ROOT}/gnats-adm}} for each new category. +@xref{categories,,The @code{categories} file}. + +@item +Run @code{mkcat}. @code{mkcat} creates a directory under +@w{@var{GNATS_ROOT}} for any new categories which appear in the +@file{categories} file. @code{mkcat} also recreates the list of valid +categories for both your locally installed @code{send-pr} and for the +@code{send-pr} distribution template in +@w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats} +lives}. +@end enumerate + +@emph{Note:} @code{mkcat} does not update the categories list for other +machines on your network which have @code{send-pr} installed (unless +the two machines share the directory @var{prefix}). +@xref{Networked management,,Managing @sc{gnats} over a network}. + +It is also important to note that only your local @code{send-pr} has +access to this new information; any copies of @code{send-pr} which you +have distributed to outside submitters now have outdated category lists. +You must either contact your submitters and instruct them to update +their copy of the categories list, which they installed in +@w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the +value for @var{prefix} may be different from yours) from the +distribution you provided, or you must build another distribution of +@code{send-pr} with this new information and redistribute it +(@pxref{mkdist,,Configuring @code{send-pr} for the outside world}). + +@node rmcat +@subsection Removing a problem category +@cindex @code{rmcat} +@cindex removing a problem category +@cindex @code{categories} file + +To remove a category from the database: + +@enumerate 1 +@item +Remove the Problem Reports from the subdirectories corresponding to the +categories you wish to remove, or assign the PRs to new categories. All +PRs for a given category reside in +@w{@file{@var{GNATS_ROOT}/@var{category}}}. Make sure you do this for +each category you wish to remove. + +@item +Run @code{rmcat} using + +@smallexample +rmcat @var{category} [ @var{category@dots{}} ] +@end smallexample + +@noindent +where @var{category} is the category you wish to remove. You can +specify as many categories as you wish as long as each category has no +PRs associated with it. @code{rmcat} removes the directory under +@w{@var{GNATS_ROOT}} where the Problem Reports for that category had been +stored. @code{rmcat} also deletes the category from the list of valid +categories for both your locally installed @code{send-pr} and for the +@code{send-pr} distribution template in +@w{@file{@var{prefix}/lib/gnats/dist}} (@pxref{Locations,,Where @sc{gnats} +lives}). +@end enumerate + +@emph{Note:} @code{rmcat} does not update the categories list for other +machines on your network which have @code{send-pr} installed. +@xref{Networked management,,Managing @sc{gnats} over a network}. + +It is also important to note that only your local @code{send-pr} has +access to this new information; any copies of @code{send-pr} which you +have distributed to outside submitters now have outdated category lists. +You must either contact your submitters and instruct them to update +their copy of the categories list, which they installed in +@w{@file{@var{prefix}/lib/gnats/@var{support-site}}} (@emph{Note:} the +value for @var{prefix} may be different from yours) from the +distribution you provided, or you must build another distribution of +@code{send-pr} with this new information and redistribute it +(@pxref{mkdist,,Configuring @code{send-pr} for the outside world}). + +@c FIXME! Should we suggest this? +@ignore +To reassign a group of categories.... + +(The idea is to call "query-pr --full", run the output through sed, and +then throw it at pr-edit. This approach is untested, and may be unhealthy.) + +@end ignore + +@node gen-index +@subsection Regenerating the index +@cindex @code{gen-index} +@cindex @code{index} file + +If your @file{index} file becomes corrupted, or if you need a copy of +the current index for some reason, use + +@smallexample +gen-index [ -n | --numeric ] + [ -d @var{directory} | --directory=@var{directory} ] + [ -c @var{filename} | --catfile=@var{filename} ] + [ -o @var{filename} | --outfile=@var{filename} ] + [ -h | --help] [ -V | --version ] +@end smallexample + +@noindent +With no options, @code{gen-index} generates an index that is ordered the +same as the order of the categories as they appear in the +@file{categories} file, and prints it to standard output. The options +are: + +@table @code +@item -n +@itemx --numeric +Sorts index entries numerically. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Uses @var{directory} as the directory containing the database, by +default @w{@var{GNATS_ROOT}} (@pxref{Locations,,Where @sc{gnats} lives}). + +@item -o @var{filename} +@itemx --outfile=@var{filename} +Places output in @var{filename} rather than sending it to standard +output. + +@item -c @var{filename} +@itemx --catfile=@var{filename} +Point to @var{filename}, the file listing the valid categories. + +@item -h +@itemx --help +Prints the usage for @code{gen-index}. + +@item -V +@itemx --version +Prints the version number for @code{gen-index}. +@end table + +@node mkdist +@subsection Configuring @code{send-pr} for the outside world +@cindex configuring @code{send-pr} for the outside world +@cindex invoking @code{mkdist} +@cindex using @code{mkdist} + +Now that @sc{gnats} is up and running on your system, you probably want +to distribute @code{send-pr} to all your friends, relatives, enemies, +etc. so they can more easily submit bugs to your organization. To do +this, create a new directory @var{dist-directory} to hold the +distribution. Then run the program + +@smallexample +mkdist --release=@var{release} @var{dist-directory} +@end smallexample + +@noindent +This populates @var{dist-directory} with a full distribution of the +program @code{send-pr}, including a @file{Makefile} and all the +@code{send-pr} documentation. You can then simply package up this +directory and send it to your bug report submitters. For example, +when logged in as @code{gnats} you can do the following: + +@smallexample +mkdir new-dist +mkdist --release=tools-1.2 new-dist +tar cvf send-pr.tar new-dist +@end smallexample + +This creates a file called @file{send-pr.tar} which contains a full +distribution of @code{send-pr} customized for your site, with a default +release number of @samp{tools-1.2}. You can then place this onto a disk +or tape and send it to your submitters, or instruct your submitters to +download it using @code{ftp}. + +If you only have one submitter, you can set the Submitter ID in the +send-pr script by specifying the --submitter option to mkdist. If you +do this, the submitter will not have to run install-sid. + +@node Internal utils +@section Internal utilities +@cindex internal utilities + +These tools are used internally by @sc{gnats}. You should never need to +run these by hand; however, a complete understanding may help you locate +problems with the @sc{gnats} tools or with your local implementation. + +@menu +* queue-pr:: Handling incoming traffic +* file-pr:: Processing incoming traffic +* at-pr:: Timely reminders +* pr-edit:: The edit-pr driver +* pr-addr:: Address retrieval +@end menu + +@node queue-pr +@subsection Handling incoming traffic +@cindex @code{queue-pr} +@cindex handling incoming traffic + +The program @code{queue-pr} handles traffic coming into @sc{gnats}. +@code{queue-pr} queues incoming Problem Reports in the directory +@w{@file{@var{GNATS_ROOT}/gnats-queue}}, and then periodically (via +@code{cron}) passes them on to @code{file-pr} to be filed in the +@sc{gnats} database. @xref{Installation,,Installing @sc{gnats}}. + +The usage for @code{queue-pr} is as follows: + +@smallexample +queue-pr [ -q | --queue ] [ -r | --run ] + [ -f @var{filename} | --file=@var{filename} ] + [ -d @var{directory} | --directory=@var{directory} ] +@end smallexample + +One of @samp{-q} or @samp{-r} (or their longer-named counterparts) must +be present upon each call to @code{queue-pr}. These options provide +different functions, as described below. + +@table @code +@item -q +@itemx --queue +Accepts standard input as an incoming mail message, placing this message +in an incrementally numbered file in the @w{@file{gnats-queue}} directory +under @w{@code{@var{GNATS_ROOT}}} (@pxref{Locations,,Where @sc{gnats} +lives}). + +@item -r +@itemx --run +Redirects files in the @file{gnats-queue} directory into the program +@code{file-pr} one by one. + +@item -f @var{filename} +@itemx --file=@var{filename} +Used with @samp{-q} (or @samp{--queue}), accepts the file denoted by +@var{filename} as input rather than reading from standard input. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Resets the default @var{directory} value, which is by default +@w{@file{@var{GNATS_ROOT}/gnats-queue}}. When @w{@samp{-d +@var{directory}}} is used in conjunction with the @samp{-q} (or +@samp{--queue}) option, @w{@code{queue-pr}} files incoming messages into +@var{directory} rather than the @file{gnats-queue} directory. When +@w{@samp{-d @var{directory}}} is used in conjunction with the @samp{-r} +(or @samp{--run}) option, @code{queue-pr} redirects into +@w{@code{file-pr}} files from @var{directory} rather than from the +@w{@file{gnats-queue}} directory. +@end table + +@node file-pr +@subsection Processing incoming traffic +@cindex @code{file-pr} +@cindex processing incoming traffic + +@code{queue-pr} hands off queued Problem Reports to @code{file-pr} one +at a time. @code{file-pr} checks each Problem Report for correct +information in its fields (particularly a correct @samp{>Category:}), +assigns it an identification number, and files it in the database under +the appropriate category. + +If the @samp{>Category:} field does not contain a valid category value +(i.e., matching a line in the @code{categories} file; +@pxref{categories,,The @code{categories} file}), the PR is given a +@samp{>Category:} value of @samp{pending} and is placed in the +@file{pending} directory. The @sc{gnats} administrator is notified of +the unplaceable PR. + +@code{file-pr} assigns the Problem Report an identification number, +files it in the @sc{gnats} database (under @w{@samp{pending}}, if the +@samp{>Category:} field contains an invalid category), and sends +acknowledgements to appropriate parties. The person responsible for +that category of problem (@pxref{categories,,The @code{categories} +file}) and the person responsible for the submitter site where the PR +originated (@pxref{submitters,,The @code{submitters} file}) receive a +copy of the PR in its entirety. Optionally, the originator of the PR +receives an acknowledgement that the PR arrived and was filed +(@pxref{Local configuration,,Changing your local configuration}). + +The usage for @code{file-pr} is as follows: + +@smallexample +file-pr [ -f @var{filename} | --file=@var{filename} ] + [ -d @var{directory} | --directory=@var{directory}b ] + [ -D | --debug ] [ -h | --help ] [ -V | --version ] +@end smallexample + +@code{file-pr} requires no options in order to operate, and takes input +from standard input (normally, the output of @w{@samp{queue-pr -r}}) +unless otherwise specified. The options include: + +@table @code +@item -f @var{filename} +@itemx --filename=@var{filename} +Uses @var{filename} as input rather than standard input. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Performs refiling operations in @var{directory} rather than in +@w{@code{@var{GNATS_ROOT}}}. + +@item -D +@itemx --debug +Give debugging output while @code{file-pr} is running. + +@item -h +@itemx --help +Prints the usage for @code{file-pr}. + +@item -V +@itemx --version +Prints the version number for @code{file-pr}. +@end table + +@node at-pr +@subsection Timely reminders +@cindex @code{at-pr} +@cindex timely reminders +@cindex automatic notification +@cindex notification of overdue PRs + +@code{at-pr} creates a queued job using @code{at} which, after an +allotted @dfn{response time} is past, checks the PR to see if its state +has changed from @samp{open}. + +The @file{submitters} file contains the response time for each +@w{@code{>Submitter-Id:}} (@pxref{submitters,,The @code{submitters} file}). +The time is determined in @dfn{business hours}, which are defined by +default as 8:00am to 5:00pm Monday through Friday, local time. These +hours are defined in the @file{config} file (@pxref{config,,The +@code{config} file}). + +If the PR is still open after the requisite time period has passed, +@code{at-pr} sends a reminder to the @sc{gnats} administrator, to the +maintainer responsible for that submitter, and to the maintainer +responsible for the PR with the following message: + +@cindex reminder message +@cindex @code{at-pr} +@smallexample +To: @var{submitter-contact} @var{responsible} @var{gnats-admin} +Subject: PR @var{gnats-id} not analyzed in @var{#hours} hours + +PR @var{gnats-id} was not analyzed within the acknowledgment period +of @var{#hours} business hours. The pertinent information is: + + Submitter-Id: @var{submitter} + Originator: @var{full name of the submitter} + Synopsis: @var{synopsis} + Person responsible for the PR: @var{responsible} + +-- +The GNU Problem Report Management System (GNATS) +@end smallexample + +@node pr-edit +@subsection The @code{edit-pr} driver +@cindex @code{pr-edit} +@cindex @code{edit-pr} driver +@cindex driver for @code{edit-pr} + +@code{pr-edit} does the background work for @code{edit-pr}, including +error-checking and refiling newly edited Problem Reports and handling +file locks. It can be called interactively, though it has no useable +editing interface. + +The usage for @code{pr-edit} is: + +@smallexample +pr-edit [ -l @var{maintainer} --lock=@var{maintainer} ] + [ -u | --unlock ] [ -c | --check ] [ -F ] + [ -L | --lockdb ] [ -U | --unlockdb ] + [ -f @var{filename} | --filename=@var{filename} ] + [ -d @var{directory} | --directory=@var{directory} ] + [ -h | --help ] [ -V | --version ] + [ @var{gnats-id} ] +@end smallexample + +@cindex PR locks +@cindex locks +A @dfn{lock} is placed on a Problem Report while the PR is being edited. +The lock is simply a file in the same directory as the PR, with the name +@w{@file{@var{gnats-id}.lock}}, which contains the name of the maintainer +who created the lock. @var{maintainer} then ``owns'' the lock, and must +remove it before the PR can be locked again, even by the same +@var{maintainer}@footnote{This approach may seem heavy-handed, but it +ensures that changes are not overwritten.}. If a PR is already locked +when you attempt to edit it, @code{pr-edit} prints an error message +giving the name of the maintainer who is currently editing the PR. + +If you do not specify @w{@var{gnats-id}}, @code{pr-edit} reads from +standard input. You must specify @w{@var{gnats-id}} for the functions +which affect PR locks, @samp{--lock=@var{maintainer}} and +@samp{--unlock}. + +@table @code +@item -l @var{maintainer} +@itemx --lock=@var{maintainer} +Locks Problem Report @w{@var{gnats-id}}, failing (and returning an error +message) if @w{@var{gnats-id}} is already locked, or if @w{@var{gnats-id}} +does not exist. @code{pr-edit} requires that you specify +@w{@var{gnats-id}} when using this option. + +@item -u +@itemx --unlock +Unlocks Problem Report @w{@var{gnats-id}}. @code{pr-edit} requires that +you specify @w{@var{gnats-id}} when using this option. You must own a +file lock to remove it. + +@item -L +@itemx --lockdb +Locks the GNATS database as a whole. This will prevent any modification +to any part of the system while it's locked. + +@item -U +@itemx --unlockdb +Unlocks the GNATS database as a whole, allowing modification of its +files. + +@item -c +@itemx --check +Checks the Problem Report in @w{@var{gnats-id}} (or standard input, if +@w{@var{gnats-id}} is not present) for correct information in its +@w{@sc{Enumerated}} fields. @code{pr-edit} complains about any bogus +information in the Problem Report. + +@item -F +Forces the PR to be submitted to the database, even if there is no +current index entry for it (i.e., even if the PR did not exist in the +database previously). + +@emph{Warning: using this option may corrupt your index.} If you use +it, be sure you know what you are doing. + +@item -f @var{filename} +@itemx --filename=@var{filename} +Reads @var{filename} rather than standard input. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Resets the operating directory (@w{@code{@var{GNATS_ROOT}}}). + +@item -h +@itemx --help +Prints the usage for @code{pr-edit}. + +@item -V +@itemx --version +Prints the version number for @code{pr-edit}. +@end table +@node pr-addr +@subsection Address retrieval +@cindex address retrieval +@cindex @code{pr-addr} + +Returns an electronic mail address when given a valid @dfn{nametag}, as +it appears in the @file{responsible} file (@pxref{responsible,,The +@code{responsible} file}). If @var{nametag} is not valid, @code{pr-addr} +will tell the user that it could not find the requested address. + +Usage is simply: + +@smallexample +pr-addr @var{name} +@end smallexample
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/p-inst.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,698 @@ +@c remember to put in the autoload stuff!!!! see the .el files + +@c This file is included as an appendix in gnats.texi. + +@cindex installing GNATS +@cindex configuring GNATS +@cindex setting up GNATS +@cindex building GNATS + +@xref{Locations,,Where the tools and utilities reside}. + +There are several steps you need to follow to fully configure and +install @sc{gnats} on your system. You need @code{root} access in order +to create a new account for @code{gnats} and to install the @sc{gnats} +utilities. You may need @code{root} access on some systems in order to +set mail aliases in place and to allow this new account access to +@code{cron} and @code{at}. + +If you are updating an older version of @sc{gnats} rather than installing +from scratch, see @ref{Upgrading,,Upgrading from older versions}. + +To build @sc{gnats}, you must: + +@itemize @bullet +@item +Run @code{configure}, with correct options if the defaults are +unsuitable for your site. @xref{Configure and make,,Configuring and +compiling the software}. Default installation locations are in +@ref{Locations,,Where @sc{gnats} lives}. + +@item +Compile the @sc{gnats} programs on your system. @xref{Configure and +make,,Configuring and compiling the software}. + +@item +Install the @sc{gnats} tools and utilities locally, and install the user +tools on every machine in your local network. @xref{Installing +utils,,Installing the utilities}. + +@item +Set up mail aliases for @sc{gnats}. @xref{Aliases,,Setting up mail +aliases}. + +@item +Install the @sc{gnats} user tools (@code{query-pr}, @code{nquery-pr}, @code{edit-pr}, +@code{send-pr}) around your network. @xref{Installing tools,,Installing +the user tools}. + +@item +Install the @sc{gnats} daemon @file{gnatsd}. + +@item +Update the local configuration files + +@smallexample +config categories submitters responsible gnatsd.conf +@end smallexample + +@noindent +in @w{@file{@var{GNATS_ROOT}/gnats-adm}}. @xref{Local +configuration,,Changing your local configuration}. + +@item +Create a distribution of @code{send-pr} for submitters outside your +organization. @xref{mkdist,,Configuring @code{send-pr} for the outside +world}. +@end itemize + +@menu +* Configure and make:: Configuring and compiling the software +* Installing utils:: Installing the utilities +* Aliases:: Setting up mail aliases +* Installing the daemon:: Installing the daemon +* Installing tools:: Installing the user tools +* Upgrading:: Upgrading from older versions +@end menu + +@node Configure and make +@section Configuring and compiling the software +@cindex unpacking the distribution +@cindex configuring and compiling the software +@cindex compiling the software +@cindex @code{configure} +@cindex @code{make} + +@enumerate 1 +@item +First, unpack your distribution. We provide source code in a @code{tar} +file which was compressed using @code{gzip}. The code can be extracted +into a directory @var{unpackdir} using + +@smallexample +mkdir @var{unpackdir} +cd @var{unpackdir} +tar zxvf gnats-@value{VERSION}.tar.z +@end smallexample + +The sources reside in a directory called @file{gnats-@value{VERSION}} +when unpacked. We call this the @dfn{top level} of the source +directory, or @dfn{srcdir}. The sources for the @sc{gnats} tools are in +the subdirectory @file{gnats-@value{VERSION}/gnats/*}. Lists of files +included in the distribution are in each directory in the file +@file{MANIFEST}. + +@cindex lisp file installation +@cindex Emacs lisp file installation +@item +You may wish to alter the installation directory for the Emacs lisp +files. If your Emacs lisp library is not in +@w{@file{@var{prefix}/lib/emacs/lisp}}, edit the files + +@smallexample +@var{srcdir}/gnats/Makefile.in @emph{and} +@var{srcdir}/send-pr/Makefile.in +@end smallexample + +@noindent +Change the variable @samp{lispdir} from @samp{$(datadir)/emacs/lisp} to +the directory containing your Emacs lisp library. For information on +@var{prefix}, see @ref{prefix,,@var{prefix}}. + +@item +Run @code{configure}. You can nearly always run @code{configure} with +the command + +@example +./configure --with-full-gnats +@end example + +@noindent +and the ``Right Thing'' happens: + +@itemize @bullet +@item +@sc{gnats} is configured in the same directory you unpacked it in; + +@item +when built, @sc{gnats} runs on the machine you're building it on; + +@item +when installed, files are installed under @file{/usr/local} +(@pxref{Locations,,Where @sc{gnats} lives}). + +@item +@sc{gnats} operates by default behavior (@pxref{default behavior,,Default +behavior}). +@end itemize + +@cindex @code{configure} +The full usage for @code{configure} is: + +@smallexample +configure [ --with-full-gnats ] + [ --prefix=@var{prefix} ] + [ --exec-prefix=@var{exec-prefix} ] + [ --with-gnats-root=@w{@var{GNATS_ROOT}} ] + [ --with-gnats-server=@w{@var{hostname}} ] + [ --with-gnats-service=@w{@var{service-name}} ] + [ --with-gnats-user=@w{@var{username}} ] + [ --with-gnats-port=@w{@var{port-number}} ] + [ --verbose ] +@end smallexample + +@table @code +@cindex @code{with-full-gnats} +@item --with-full-gnats +All programs are to be built; this includes the user utilities, the +administrative utilities, and the internal utilities. Use this when +configuring the utilities for the machine where @sc{gnats} is to run. +Omit it when building only the user utilities for other machines on your +network; see @ref{Installing tools,,Installing the user tools}. + +@cindex @var{prefix} +@item --prefix=@var{prefix} +All host-independent programs and files are to be installed under +@var{prefix}. (Host-dependent programs and files are also installed in +@var{prefix} by default.) The default for @var{prefix} is +@w{@file{/usr/local}}. @xref{Locations,,Where @sc{gnats} lives}. + +@cindex @var{exec-prefix} +@item --exec-prefix=@var{exec-prefix} +All host-dependent programs and files are to be installed under +@var{exec-prefix}. The default for @var{exec-prefix} is @var{prefix}. +@xref{Locations,,Where @sc{gnats} lives}. + +@cindex @var{GNATS_ROOT} +@item --with-gnats-root=@w{@var{GNATS_ROOT}} +The database and its data files are to be installed into +@w{@var{GNATS_ROOT}}. The default for @w{@var{GNATS_ROOT}} is +@w{@file{@var{prefix}/lib/gnats/gnats-db}}. @xref{Locations,,Where +@sc{gnats} lives}. + +@cindex --with-gnats-server +@item --with-gnats-root=@w{hostname} +FIXME + +@cindex --with-gnats-service +@item --with-gnats-root=@w{@var{service-name}} +FIXME + +@cindex --with-gnats-user +@item --with-gnats-user=@w{@var{username}} +FIXME + +@cindex --with-gnats-port +@item --with-gnats-port=@w{@var{port-number}} +FIXME + +@item --verbose +Give verbose output while @code{configure} runs. +@end table + +@xref{Using configure,,Using @code{configure},configure,Cygnus +configure}. + +@cindex building in a different directory +@cindex @var{objdir} +You can build @sc{gnats} in a different directory (@var{objdir}) from the +source code by calling the @code{configure} program from the new +directory, as in + +@smallexample +mkdir @var{objdir} +cd @var{objdir} +@var{srcdir}/configure @dots{} +make all +@end smallexample + +By default, @code{configure} compiles the programs in the same directory +as the sources (@var{srcdir}). Emacs lisp files are byte-compiled if +@code{make} can find Emacs on your local system. + +@item +Run + +@smallexample +make all info +@end smallexample + +@noindent +from the directory where @code{configure} created a @file{Makefile}. +(This may not be the same directory as the source directory.) These +targets indicate: + +@table @code +@item all +Compile all programs + +@item info +Create @samp{info} files using @code{makeinfo}. +@end table +@end enumerate + +@node Installing utils +@section Installing the utilities +@cindex installing the utilities + +The following steps are necessary for a complete installation. You may +need @code{root} access for these. + +@enumerate 1 +@item +Install the utilities by +invoking + +@smallexample +make install install-info +@end smallexample + +These targets indicate: + +@table @code +@item install +Installs all programs into their configured locations +(@pxref{Locations,,Where @sc{gnats} lives}). + +@item install-info +Installs @samp{info} files into their configured locations +(@pxref{Locations,,Where @sc{gnats} lives}). +@end table + +After you have installed @sc{gnats}, you can remove the object files with + +@smallexample +make clean +@end smallexample + +@cindex @code{autoload} commands +@cindex loading @code{.el} files +@cindex Emacs functions +@item +Place the following lines in the file @file{default.el} in your Emacs +lisp library, or instruct your local responsible parties to place the +lines in their local editions of @file{.emacs}: + +@smallexample +(autoload 'edit-pr "gnats" + "Command to edit a problem report." t) +(autoload 'view-pr "gnats" + "Command to view a problem report." t) +(autoload 'unlock-pr "gnats" + "Unlock a problem report." t) +(autoload 'query-pr "gnats" + "Command to query information about problem reports." t) +(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 smallexample + +Emacs lisp files are byte-compiled if @code{make} can find Emacs on your +local system. + + +@item +@cindex creating an account for @sc{gnats} +Create an account for a user named @sc{gnats}. This user must have an +entry in the file @file{/etc/passwd}. The home directory for this +account should be the same directory you specified for @var{GNATS_ROOT} +in the file @file{Makefile.in}. Also, the default @code{PATH} for this +user should contain @w{@file{@var{exec-prefix}/bin}} and +@w{@file{@var{exec-prefix}/lib/gnats}}. + +@cindex @code{cron} +@cindex @code{at} +@item +Allow the new user @code{gnats} access to @code{cron} and @code{at}. To +do this, add the name @code{gnats} to the files @w{@file{cron.allow}} and +@w{@file{at.allow}}, which normally reside in the directory +@w{@file{/var/spool/cron}}. If these files do not exist, make sure +@code{gnats} does not appear in either of the files @w{@file{cron.deny}} +and @w{@file{at.deny}} (in the same directory). + +@noindent +For the following steps, log in as @code{gnats}. + +@itemize @bullet +@item +Edit the files @file{categories}, @file{responsible}, and +@file{submitters} in the directory @w{@file{@var{GNATS_ROOT}/gnats-adm}} +(@pxref{Local configuration,,Changing your local configuration}) to +reflect your local needs. Be sure to run @code{mkcat} after you update +the @file{categories} file (@pxref{mkcat,,Adding a new problem +category}). @emph{Note:} these templates are not installed if they +already exist, i.e. if you are upgrading. @xref{Upgrading,,Upgrading +from older versions}. + +@item +If you wish to install the @sc{gnats} user tools on other machines on +your network, see @ref{Installing tools,,Installing the user tools}. +@end itemize + +@cindex @code{crontab} +@item +Create a @code{crontab} entry that periodically runs the program +@code{queue-pr} with the @samp{--run} option. For example, to run +@w{@samp{queue-pr --run}} every ten minutes, create a file called +@file{.mycron} in the home directory of the user @code{gnats} which +contains the line: + +@smallexample +0,10,20,30,40,50 * * * * @var{exec-prefix}/lib/gnats/queue-pr --run +@end smallexample + +@noindent +(Specify the full path name for @code{queue-pr}.) Then run + +@smallexample +crontab .mycron +@end smallexample + +@noindent +See the @code{man} pages for @code{cron} and @code{crontab} for details +on using @code{cron}. +@end enumerate + +@node Aliases +@section Setting up mail aliases +@cindex mail aliases +@cindex aliases + +The following mail aliases must be placed in the file +@w{@file{/etc/aliases}} on the same machine where the @sc{gnats} tools +are installed. You may need @code{root} access to add these aliases. + +@itemize @bullet +@item +@cindex @code{gnats-admin} alias +Create an alias for the @sc{gnats} administrator. This address should +point to the address of the person in charge of administrating +@sc{gnats}: + +@smallexample +gnats-admin: @var{address} +@end smallexample + +@item +@cindex bug alias +@cindex incoming alias for Problem Reports +@cindex alias for incoming Problem Reports +@cindex @code{queue-pr -q} +Create an alias to redirect incoming Problem Reports. This alias should +redirect incoming mail via a @dfn{pipe} to the program @w{@samp{queue-pr +-q}}. For example, if Problem Reports coming to your site are to arrive +at the address @samp{bugs@@your.company.com}, create an alias to the +effect of: + +@smallexample +bugs: "| @var{exec-prefix}/lib/gnats/queue-pr -q" +@end smallexample + +@noindent +This places incoming Problem Reports in +@w{@file{@var{GNATS_ROOT}/gnats-queue}}. + +@item +@cindex @var{site} alias +@cindex mail alias for your @emph{site} +@cindex alias for your @emph{site} +Create an alias for your site. This alias should be the same nametag +indicated by the variable @w{@samp{GNATS_SITE}} in the file +@w{@file{@var{GNATS_ROOT}/gnats-adm/config}} (@pxref{config,,The +@code{config} file}), with an added suffix @samp{-gnats}. This alias, +@w{@samp{@var{GNATS_SITE}-gnats}}, should point toward the local +submission address. For instance, if your site is Tofu Technologies, +the presence of @sc{gnats} on your @var{site} would be aliased as the +following (the previous example is also shown): + +@smallexample +bugs: "| @var{exec-prefix}/lib/gnats/queue-pr -q" +tofu-gnats: bugs +@end smallexample + +@noindent +The report submission utility @code{send-pr} automatically appends the +@samp{-gnats} to any arguments you specify (@pxref{send-pr,,Submitting +Problem Reports}). The @code{send-pr} which was installed when you +typed @w{@kbd{make install}} has a default argument of @var{GNATS_SITE}, +your site, so that when your local users simply type @kbd{send-pr} mail +is sent to your local @sc{gnats}. Part of the installation process a +Submitter Site follows when installing @code{send-pr} is to set up an +alias for the Support Site from whom this submitter received +@code{send-pr}. In other words, anyone you distribute @code{send-pr} to +is instructed to make an alias + +@smallexample +tofu-gnats: bugs@@tofu.com +@end smallexample + +@item +You may also wish to forward a copy of each incoming Problem Report to a +log. This can be accomplished with something like: + +@smallexample +bug-q: "| @var{exec-prefix}/lib/gnats/queue-pr -q" +bug-log: @var{GNATS_ROOT}/gnats-adm/bugs.log +bugs: bug-q, bug-log +@end smallexample + +@noindent +This configuration archives incoming Problem Reports in the file +@w{@file{@var{GNATS_ROOT}/gnats-adm/bug.log}}, and also feeds them to the +program @code{queue-pr}. (Remember, @file{bug.log} needs to be +world-writable, and should be pruned regularly; @pxref{Management,, +@sc{gnats} Administration}.) + +@item +If you want your users to be able to query the database by mail, use the +following alias: + +@smallexample +query-pr: "| @var{exec-prefix}/lib/gnats/mail-query" +@end smallexample + +@noindent +The @code{mail-query} program uses @samp{--restricted} to search on the +database, and by default only searches for PRs that aren't closed +(@pxref{query-pr,,Querying the database}). + +@end itemize + +@c --------------------------------------------------------------- +@node Installing the daemon +@section Installing the daemon +@cindex daemon +@cindex using @sc{gnats} over a network + +By default, the daemon and clients are set to use port 1529. Add the line + +@smallexample +support 1529/tcp # GNATS +@end smallexample + +@noindent +to your @file{/etc/services} file. If you want a different port, +or a different service name or port, configure @sc{gnats} with + +@smallexample +--with-gnats-service=@var{servicename} +--with-gnats-port=@var{portnumber} +@end smallexample + +In your @file{inetd.conf} file, add the line + +@smallexample +support stream tcp nowait gnats /usr/local/lib/gnats/gnatsd gnatsd +@end smallexample + +@noindent +adjusting the path accordingly. To make inetd start spawning the @sc{gnats} daemon +when connected on that port, send it a hangup signal (@code{HUP}). + +By default, the server for the @sc{gnats} daemon is assumed to be one with the +name of @samp{gnats}. If you'd like something else, use + +@smallexample +--with-gnats-server=@var{hostname} +@end smallexample + +In the @file{gnats-adm} directory, you'll want to edit @file{gnatsd.conf}. +It lists the hosts allowed to access your server. Or, if you're using +Kerberos, it shows the sites that don't require Kerberos authentication. +The format is reserved for future revision; only the first field is +actually used: + +@smallexample +site.com:: +@end smallexample + +@noindent +The second field may be used for things like controlling what +categories, submitter-id'd PRs, etc., can be accessed from that site. +In the file that logs syslog messages (@file{/var/adm/messages}, for +example) you'll find the notification of denied access. + + +@c --------------------------------------------------------------- +@node Installing tools +@section Installing the user tools +@cindex networks +@cindex using @sc{gnats} over a network +@cindex configuring @sc{gnats} on a network + +When you install the @sc{gnats} utilities, the user tools are installed +by default on the host machine. If your machine is part of a network, +however, you may wish to install the user tools on each machine in the +network so that responsible parties on those machines can submit new +Problem Reports, query the database, and edit existing PRs. To do this, +follow these steps @emph{on each new host}. You may need root access on +each machine. + +@enumerate 1 +@item +Make sure that the directory where @sc{gnats} resides is mounted to each +system that will need access to it, so @var{GNATS_ROOT} will be the same +for each host. (You can do this with symbolic links as well.) + +@item +Either mount the disk which contains your source directory, or make a +copy of the @sc{gnats} source code tree in a separate directory on each +system you wish to build on. + +@item +Run @code{configure}, @emph{without} specifying +@w{@samp{--with-full-gnats}}, and using the same argument (if any) for +the option + +@smallexample +--with-gnats-root=@var{GNATS_ROOT} +@end smallexample + +that you specified when building the @sc{gnats} utilites +(@pxref{Configure and make,,Configuring and compiling the software}). +You may use different values for the other options to @code{configure}. +Again, @emph{do not} use @w{@samp{--with-full-gnats}} at this point, as +that creates all the @sc{gnats} programs. Without this option, +@code{configure} only instructs the resulting @file{Makefile} to create +the user utilities. + +@exdent +@emph{You may need @code{root} access on each host for the following steps.} + +@item +@cindex creating an account for @sc{gnats} +Create an account for a user named @sc{gnats} on the new host. This user +must have an entry in the file @file{/etc/passwd}. The user ID for +@code{gnats} must be the same as on the main @sc{gnats} host. + +@item +Run + +@smallexample +make all info install install-info +@end smallexample + +@noindent +This builds and installs the @code{gnats} user tools @w{@code{query-pr}}, +@w{@code{edit-pr}}, and @w{@code{send-pr}} on the new host, and installs +them in @w{@file{@var{exec-prefix}/bin}} on the new host (@emph{Note:} +the value for @var{exec-prefix} on the new host may be different from +the value you used when building the @sc{gnats} utilities; +@pxref{exec-prefix,,@var{exec-prefix}}). The programs @code{pr-edit} +and @code{pr-addr} are installed into +@w{@file{@var{exec-prefix}/lib/gnats}}. + +@code{info} files are created as well, and are installed into +@w{@file{@var{prefix}/info}}. The Elisp files @file{gnats.el} and +@file{send-pr.el} (and possibly @file{gnats.elc} +if @code{make} was able to compile them using Emacs) are installed into +@w{@file{@var{prefix}/lib/emacs/lisp}} unless you change the +@samp{lispdir} variable in @file{Makefile.in} (@pxref{Configure and +make,,Configuring and compiling the software}). + +@cindex @code{autoload} commands +@cindex loading @code{.el} files +@cindex Emacs functions +@item +Add the following lines to the file @w{@file{default.el}} in the Emacs +lisp repository on the new host, or instruct your responsible parties +who use these hosts to add them to their @file{.emacs} files: + +@smallexample +(autoload 'edit-pr "gnats" + "Command to edit a problem report." t) +(autoload 'view-pr "gnats" + "Command to view a problem report." t) +(autoload 'unlock-pr "gnats" + "Unlock a problem report." t) +(autoload 'query-pr "gnats" + "Command to query information about problem reports." t) +(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 smallexample + +@item +Copy the file @w{@file{@var{prefix}/lib/gnats/@var{site}}} from the +original host to the new host (which may have a different value for +@var{prefix}). This is the list of valid categories that +@w{@code{send-pr}} uses (@pxref{Locations,,Where @sc{gnats} lives}). +@var{site} is your local site, the value of @w{@samp{GNATS_SITE}} in the +@file{config} file (@pxref{config,,The @code{config} file}). + +@end enumerate + +@c --------------------------------------------------------------- +@node Upgrading +@section Upgrading from older versions +@cindex upgrading from older versions + +If you are upgrading from a previous release of @sc{gnats}, you probably +do not want to delete your current configuration files or your current +database. The new @sc{gnats} can be installed around the older version. + +You need to: + +@itemize @bullet +@item +Specify your current @var{GNATS_ROOT} on the command line to +@code{configure} when you build the new tools, with + +@smallexample +configure --with-full-gnats --with-gnats-root=@var{GNATS_ROOT} +@end smallexample + +@noindent +(@xref{Configure and make,,Configuring and compiling the software}.) + +@item +Remove the directory @w{@file{gnats-bin}} from @w{@var{GNATS_ROOT}}; it is +no longer used. + +@item +Update your current mail aliases to reflect that @w{@code{queue-pr}} now +resides in @w{@file{@var{exec-prefix}/lib/gnats}} rather than +@w{@file{@var{GNATS_ROOT}/gnats-bin}} (@pxref{Locations,,Where @sc{gnats} +lives}). + +@item +Change the default @code{PATH} for the @code{gnats} user to search the +directories @w{@file{@var{exec-prefix}/bin}} and +@w{@file{@var{exec-prefix}/lib/gnats}}. + +@item +Reinstall the @sc{gnats} user tools on all other hosts on your network +(@pxref{Installing tools,,Installing the user tools}). + +@item +Redistribute @code{send-pr} to your Submitter Sites +(@pxref{mkdist,,Configuring @code{send-pr} for the outside world}). +This is not absolutely necessary, as @sc{gnats} can read Problem Reports +generated by older versions of @code{send-pr}. It should be done +eventually, however, as @w{@code{send-pr}} is improved over older +verisons. + +@c FIXME - anything else? +@end itemize
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/p-usage.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,891 @@ +@node Invoking the tools +@chapter Invoking the @sc{gnats} tools +@cindex usage for the @sc{gnats} tools +@cindex invoking the @sc{gnats} tools +@cindex tool usage for software maintainers + +The following programs comprise @sc{gnats}: + +@cindex user utilities +@subheading User Utilities + +These tools are used by the maintainers of a body of work +(@w{@code{send-pr}} is also used by the end users of the product). + +@table @code +@item send-pr +Used by anyone who has a problem with a body of work to submit a report +of the problem to the maintainers of that work +(@pxref{send-pr,,Submitting Problem Reports}). + +@item query-pr +Used by software maintainers to query the @sc{gnats} database +(@pxref{query-pr,,Querying the database}). + +@item edit-pr +Used by software maintainers to edit Problem Reports (to record new +data, to change the responsible party, etc.) (@pxref{edit-pr,,Editing +existing Problem Reports}). + +@item view-pr +Used by software maintainers to view individual Problem Reports using +Emacs (@pxref{view-pr,,Viewing individual Problem Reports}). +@end table + +@cindex administrative utilities +@subheading Administrative Utilities + +These tools are used by the @sc{gnats} administrator; see also +@ref{Management,,@sc{gnats} Administration}. For complete explanations +of these utilities, see @ref{Admin utils,,Administrative utilities}. + +@table @code +@item mkcat +Creates new categories (@pxref{mkcat,,Adding a problem category}). + +@item rmcat +Removes existing categories (@pxref{rmcat,,Removing a problem +category}). + +@item gen-index +Generates an up-to-date copy of the index used by @code{query-pr} and +@code{edit-pr} (@pxref{index file,,The @code{index} file}). Use +@code{gen-index} to rebuild the index if it becomes corrupted, or if you +need a copy of the current index for some reason +(@pxref{gen-index,,Regenerating the index}). + +@item mkdist +Creates a distribution of the program @code{send-pr} for offsite +submitters of PRs (@pxref{mkdist,,Configuring @code{send-pr} for the +outside world}). +@end table + +@cindex internal utilities +@subheading Internal Utilities + +These tools are used internally by @sc{gnats}. You should not need to +run these by hand. For complete explanations of these utilities, see +@ref{Internal utils,,Internal utilities}. + +@table @code +@item queue-pr +Handles incoming bugs, first through a mail alias by queueing incoming +PRs as they arrive, and second as a periodic transfer agent between the +queue and the database. + +@item file-pr +Files Problem Reports as they come in. + +@item at-pr +Sends reminders to maintainers based on quoted response times. + +@item pr-edit +Used by @code{edit-pr} to error-check and submit edited Problem Reports +(also @pxref{edit-pr,,Editing existing Problem Reports}). + +@item pr-addr +Used by the @code{edit-pr} script to retrieve correct addresses from the +@file{responsible} file. +@end table + +@xref{Locations,,Where @sc{gnats} lives}. + +@menu +* send-pr:: Submitting Problem Reports +* edit-pr:: Editing existing Problem Reports +* query-pr:: Querying the database +* view-pr:: Viewing individual Problem Reports +@end menu + +@node send-pr +@section Submitting Problem Reports +@cindex @code{send-pr} +@cindex using @code{send-pr} +@cindex invoking @code{send-pr} +@cindex reporting problems with @code{send-pr} + +Use @code{send-pr} to submit Problem Reports to the database. +@code{send-pr} is both a shell script and a Lisp program for @sc{gnu} +Emacs; both implementations provide a template for submitters to +complete. In most cases, @code{send-pr} can determine intelligent +default values for several fields, partially automating the +bug-reporting process. + +@xref{mkdist,,Configuring @code{send-pr} for the outside world}, for +information on distributing a version of @code{send-pr} customized with +your site's configuration. + +@lowersections +@include s-usage.texi +@raisesections + +@c --------------------------------------------------------------- +@node edit-pr +@section Editing existing Problem Reports +@cindex using @code{edit-pr} +@cindex invoking @code{edit-pr} +@cindex @code{edit-pr} + +Use @code{edit-pr} to make changes to existing PRs in the database. +@code{edit-pr} is both a shell script and a Lisp program for @sc{gnu} +Emacs. Both implementations are essentially identical, though the Emacs +interface provides interactive prompting for some of the fields. + +@code{edit-pr} first examines the PR you wish to edit and locks it if it +is not already locked. This is to prevent you from editing a PR at the +same time as another user. If the PR you wish to edit is already in the +process of being edited, @code{edit-pr} tells you the name of the person +who owns the lock. + +You may edit any field in the database that you wish. We recommend that +you avoid deleting any information in the @sc{Text} and @sc{MultiText} +fields (such as @samp{>Description:} and @samp{>How-To-Repeat:} +(@pxref{Fields,,Problem Report format}). We also recommend that you +record the final solution to the problem in the @samp{>Fix:} field for +future reference. + +If you change the @samp{>Responsible:} field, @code{edit-pr} prompts you +to supply a reason for the change. @code{edit-pr} then mails copies of +the change message to the previous responsible party, and to the new +responsible party. The change is then recorded in the +@samp{>Audit-Trail:} section of the PR as follows: + +@table @asis +@item @code{Responsible-Changed-<From>-<To>}: The value change, supplied +automatically by @code{edit-pr}. + +@item @code{Responsible-Changed-By}: Your name here, supplied +automatically by @code{edit-pr}. + +@item @code{Responsible-Changed-When}: The current date, supplied +automatically by @code{edit-pr}. + +@item @code{Responsible-Changed-Why}: Your reason for the change; you +are prompted for this. +@end table + +If you change the @samp{>State:} field, you are prompted to supply a +reason for the change. Copies of the change message are then mailed to +the responsible party, and to the original submitter of the Problem +Report. The change is then recorded in the @samp{Audit-Trail} section +of the PR as follows: + +@table @asis +@item @code{State-Changed-<From>-<To>}: The value change, supplied +automatically by @code{edit-pr}. + +@item @code{State-Changed-By}: Your name here, supplied +automatically by @code{edit-pr}. + +@item @code{State-Changed-When}: The current date, supplied +automatically by @code{edit-pr}. + +@item @code{State-Changed-Why}: Your reason for the change; you are +prompted for this. +@end table + +The PR is then resubmitted to the database, and the index is updated +(@pxref{index file,,The @code{index} file}). For information on +@code{pr-edit}, the main driver for @code{edit-pr}, see @ref{Internal +utils,,Internal utilities}. + +@menu +* edit-pr in Emacs:: Using @code{edit-pr} from within Emacs +* edit-pr from the shell:: Invoking @code{edit-pr} from the shell +@end menu + +@node edit-pr in Emacs +@subsection Using @code{edit-pr} from within Emacs +@cindex @code{edit-pr} in Emacs + +Call @code{edit-pr} from within Emacs with @w{@code{M-x +edit-pr}}@footnote{If typing @w{@samp{M-x edit-pr}} doesn't work, see +your system administrator for help loading @code{edit-pr} into Emacs.}. +When @code{edit-pr} prompts you for a PR identification number, type the +number of the PR you wish to edit. + +If the PR is locked, Emacs announces the login name of the person who +has locked the file. If not, @w{@code{M-x edit-pr}} locks the PR, loads +it into a buffer named @samp{*edit-pr*}, and places the cursor in the +@samp{>Number:} field. (@emph{Do not change this field}.) + +Edit the PR to reflect correct information. Resubmit the PR to the +database using @w{@samp{C-c C-c}} (see below). + +The easiest way to edit a PR from Emacs is to use the special key +bindings provided. These are: + +@table @code +@item C-c C-c +@itemx M-x gnats-submit-pr +Saves and resubmits the PR currently being edited. Do this when you +finish editing the PR; if you simply kill the buffer, your changes are +lost. + +@item C-x C-s +@itemx M-x save-buffer +Saves the current buffer tp a file. You are prompted for a filename. +This is not a special key binding, but at one point in the history of +@sc{gnats} it was used to resubmit the PR (i.e., it was bound to +@w{@samp{M-x gnats-submit-pr}}). @w{@samp{C-x C-s}} now simply saves a +copy of the PR. This command @emph{does not} resubmit the PR to the +database. Use @w{@samp{C-c C-c}} to resubmit the PR. + +@item C-x k +@itemx M-x gnats:kill-buffer (@emph{use this only with Emacs 18}) +@itemx M-x kill-buffer +Kills the current buffer (destroying all changes) and unlocks the +current PR. Use this to back out of a change without affecting the +database. + +@item C-c C-u +@itemx M-x unlock-pr +Unlocks a PR that you have locked. Use this if you have a locked PR +from a failed editing session. You are prompted for the @var{gnats-id} +of a PR to unlock. + +@item C-c C-q +@item M-x unlock-buffer +Removes the lock on the current PR, allowing others to edit it. The +buffer remains active and non-writeable. To relock a PR, simply type +@samp{e} in the buffer containing the Problem Report. + +@item C-c C-e +@itemx M-x edit-pr +Runs @code{edit-pr} in a new buffer. + +@item C-c C-f +@itemx M-x change-field +Changes the field under the cursor. @code{edit-pr} prompts you for a +new value. If you use + +@smallexample +C-u C-c C-f @emph{or} +C-u M-x change-field +@end smallexample + +@noindent +you are prompted for a field to change. + +@item C-c C-a +@itemx M-x gnats-mail-reply +Sends mail to the originator of this PR, using the address in the +@samp{From:} field of the mail header. The @samp{Subject}, @samp{To:}, +and @samp{Cc:} fields are constructed from the Problem Report currently +being edited. Edit the message, and use @w{@samp{C-c C-c}} to send it. + +@item C-c RET +@itemx C-c C-m +@itemx M-x gnats-mail-other-window +Splits the current window, and starts a mail message. The +@samp{Subject:} field is constructed from the Problem Report currently +being edited. Edit the message, and use @w{@samp{C-c C-c}} to send it. + +@item C-c C-r +@itemx M-x gnats-responsible-change-from-to +Changes the @samp{>Responsible:} field. @code{edit-pr} prompts you for +the new responsible person, and for a message describing the reason for +the change. When you type @w{@samp{C-c C-c}} to resubmit the PR, the +cursor is placed in a mail buffer containing a copy of the change. You +can then edit this buffer and type @w{@samp{C-c C-c}} again to send the +mail. + +@item C-c C-s +@itemx M-x gnats-state-change-from-to +Changes the @samp{>State:} field. @code{edit-pr} prompts you for the +new state, and for a message describing the reason for the change. When +you type @w{@samp{C-c C-c}} to resubmit the PR, the cursor is placed in +a mail buffer containing a copy of the change. You can then edit this +buffer and type @w{@samp{C-c C-c}} again to send the mail. + +@item C-c C-t +@itemx M-x category-change-from-to +Changes the @samp{>Category:} field of the PR. @code{edit-pr} prompts +you for the new category. @code{edit-pr} also prompts you with the +question + +@smallexample +Update the >Responsible field? +@end smallexample + +@noindent +Type @samp{y} to change the value of the @samp{>Responsible:} field to +the name of the party responsible for the new category. Type @samp{n} to +keep the current value of @samp{>Responsible:}. + +@c FIXME: +@c @item C-c C-f +@c @itemx M-x change-field +@c what does this routine do?? I can't figure it out from gnats-el.in... + +@item M-C-b +@itemx M-x gnats-backward-field +Moves the cursor to the beginning of the value of the current field. + +@item M-C-f +@itemx M-x gnats-forward-field +Moves the cursor to the end of the value of the current field. + +@item M-p +@itemx M-x gnats-previous-field +Moves the cursor back one field to the beginning of the value of the +previous field. + +@item M-n +@itemx M-x gnats-next-field +Moves the cursor forward one field to the beginning of the value of the +next field. +@end table + +@node edit-pr from the shell +@subsection Invoking @code{edit-pr} from the shell +@cindex @code{edit-pr} from the shell + +The usage for the @code{edit-pr} shell script is: + +@smallexample +edit-pr @var{gnats-id} [ -V | --version ] [ -h | --help ] +@end smallexample + +@noindent +You must first determine which PR you want to edit. The options are: + +@table @code +@item -V @emph{or} --version +Prints the version number for @code{edit-pr}. + +@item -h @emph{or} --help +Prints the usage for @code{edit-pr}. +@end table + +@code{edit-pr} calls the editor specified in your environment +variable @code{EDITOR} on a temporary copy of that PR. (If you don't +have the variable @code{EDITOR} defined in your environment, the default +editor @code{vi} is used.) + +Edit the PR, changing any relevant fields or adding to existing +information. When you exit the editor, @code{edit-pr} prompts you on +standard input for a reason if you've changed either the +@samp{>Responsible:} field or the @samp{>State:} field. @code{edit-pr} +tracks the information you provide when changing either of these two +fields, along with the change that occurred, your name, and the time of +change in the @samp{>Audit-Trail:} field. + +@c --------------------------------------------------------------- +@node query-pr +@section Querying the database +@cindex using @code{query-pr} +@cindex invoking @code{query-pr} +@cindex @code{query-pr} +@cindex querying invdividual problem reports + +Obtain information from the database by using the program +@w{@code{query-pr}}. @code{query-pr} uses search parameters you provide +to find matching Problem Reports in the database. You can invoke +@code{query-pr} from the shell or from within Emacs. @code{query-pr} +uses the same arguments whether it is invoked from the shell or from +Emacs. + +All arguments and options to @code{query-pr} are optional. If you do +not specify a PR identification number and do not give any search +parameters, @code{query-pr} displays the entire database. All arguments +are considered identification numbers of Problem Reports to display. +Any number of options can be given (though some make no sense when +specified on the same command line); all are connected with a logical +@code{AND}. + +@menu +* Invoking query-pr:: +* Example queries:: +* Reporting:: +@end menu + +@node Invoking query-pr +@subsection Invoking @code{query-pr} + +From the shell, simply type @kbd{query-pr}, followed by any search +parameters you wish to exercise. From Emacs, type @w{@kbd{M-x +query-pr}}. @code{query-pr} prompts you for search parameters in the +minibuffer. + +@cindex @code{query-pr} by mail +@code{query-pr} can also be accessed by electronic mail, if your version +of @sc{gnats} is configured for this. To use this feature, simply send +mail to the address @w{@samp{query-pr@@@var{your-site}}} with command +line arguments or options in the @samp{Subject:} line of the mail +header. @sc{gnats} replies to your mail with the results of your query. +The default settings for the @code{query-pr} mail server are + +@cindex the section on query-by-mail needs to be relocated +@smallexample +--restricted --state="open|analyzed|feedback|suspended" +@end smallexample + +@noindent +To override the @samp{--state} parameter, specify +@w{@samp{--state=@var{state}}} in the @code{Subject:} line of the mail +header. You can not query on confidential Problem Reports by mail. + +The usage for @code{query-pr} is: + +@smallexample +query-pr [ @var{gnats-id} ] + [ -c @var{category} | --category=@var{category} ] + [ -s @var{state} | --state=@var{state} ] + [ -r @var{responsible} | --responsible=@var{responsible} ] + [ -S @var{submitter} | --submitter=@var{submitter} ] + [ -C [ @var{yes} | @var{no} ] | --confidential=[ @var{yes} | @var{no} ] ] + [ -e @var{severity} | --severity=@var{severity} ] + [ -p @var{priority} | --priority=@var{priority} ] + [ -O @var{originator} | --originator=@var{originator} ] + [ -L @var{class} | --class=@var{class} ] +@c [ -k @var{class} | --class=@var{class} ] + [ -t @var{text} | --text=@var{text} ] + [ -m @var{text} | --multitext=@var{text} ] + [ -R | --restricted ] + [ -F | --full ] [ -q | --summary ] [ -i | --sql ] + [ -P | --print-path ] + [ -d @var{directory} | --directory=@var{directory} ] + [ -o @var{outfile} | --output=@var{outfile} ] + [ -V | --version ] [ -h | --help ] +@end smallexample + +If you run @code{query-pr} from within Emacs, you can use + +@smallexample +C-x ` @emph{or} M-x next-error +@end smallexample + +@noindent +to scroll through Problem Reports one by one after the search is +finished. + +@subheading Search criteria + +The following arguments and options specify search criteria. The lack +of a criterion indicates that all values for the corresponding field are +valid for the search. Regular expressions may be used as arguments to +search criteria options; see @ref{Regexps,,Querying using regular +expressions}. + +Using an argument to @code{query-pr} specifies the most stringent search +criteria, that of a single PR. + +@table @code +@item @var{gnats-id} +The identification number of the PR you wish to view, as shown in the +@samp{>Number:} field. Any number of @var{gnats-id} arguments may be +given. + +@item -c @var{category} +@itemx --category=@var{category} +Search only for PRs with a @samp{>Category:} value of @var{category}. +For a list of valid categories, type @w{@samp{send-pr -L}} from the +shell. + +@item -s @var{state} +@itemx --state=@var{state} +Search only for PRs with a @samp{>State:} value of @var{state}. +@var{state} must be one of: @samp{open}, @samp{analyzed}, +@samp{feedback}, @samp{closed}, or @samp{suspended}. + +@noindent +This field may be searched using regular expressions. @xref{Regexps,, +Querying using regular expressions}. Also see @ref{Example +queries,,Example queries}. + +@item -r @var{responsible} +@itemx --responsible=@var{responsible} +Search only for PRs with a @samp{>Responsible:} value of @var{responsible}. + +@item -S @var{submitter} +@itemx --submitter=@var{submitter} +Search only for PRs with a @samp{>Submitter:} value of @var{submitter}. + +@item -C [@var{yes} | @var{no}] +@itemx --confidential=[@var{yes} | @var{no}] +Search only for PRs with a @samp{>Confidential:} value of either +@var{yes} or @var{no}. If this option is not given, all PRs are +eligible for the search regardless of their confidentiality. + +@item -e @var{severity} +@itemx --severity=@var{severity} +Search only for PRs with a @samp{>Severity:} value of @var{severity}. +@var{severity} must be one of: @samp{critical}, @samp{serious}, or +@samp{non-critical}. + +@item -p @var{priority} +@itemx --priority=@var{priority} +Search only for PRs with a @samp{>Priority:} value of @var{priority}. +@var{priority} must be one of: @samp{high}, @samp{medium}, or +@samp{low}. + +@item -O @var{originator} +@itemx --originator=@var{originator} +Search only for PRs with an @samp{>Originator:} value of @var{originator}. + +Since this option does not reference the index, queries using it finish +much faster if you also use another search criterion that @emph{is} part +of the index (@pxref{index file,,The @code{index} file}). + +@item -L @var{class} +@itemx --class=@var{class} +Search only for PRs with a @samp{>Class:} value of @var{class}. +Since this option does not reference the index, queries using it finish +much faster if you also use another search criterion that @emph{is} part +of the index (@pxref{index file,,The @code{index} file}). + +@ignore +@c FIXME - check if these need @w, and make sure this option goes in! +@item -k @var{class} +@itemx --class=@var{class} +Search only for PRs with a @samp{>Class:} value of @var{class}. @var{class} +must be one of: @samp{sw-bug}, @samp{doc-bug}, @samp{change-request}, +@samp{support}, @samp{duplicate}, or @samp{mistaken}. + +Since this option does not reference the index, queries using it finish +much faster if you also use another search criterion that @emph{is} part +of the index (@pxref{index file,,The @code{index} file}). +@end ignore + +@item -t @var{text} +@itemx --text=@var{text} +Search the @sc{Text} fields in the database for the regular expression +@var{text}. @sc{Text} fields include the following (the +@samp{>} and @samp{:} Problem Report fieldname delimiters have been +removed for the sake of brevity and readability): + +@smallexample +@group +Submitter-Id Originator Synopsis +Category Release Responsible +Arrival-Date +@end group +@end smallexample + +@noindent +@xref{Regexps,,Querying using regular expressions}. + +Queries using this option can be slow. Since this option does not +reference the index, queries using it finish much faster if you also use +another search criterion that @emph{is} part of the index (@pxref{index +file,,The @code{index} file}). + +@item -m @var{text} +@item --multitext=@var{text} +Search the @sc{MultiText} fields in the database for the regular +expression @var{text}. @sc{MultiText} fields include the following +(again, the fieldname delimiters @samp{>} and @samp{:} have been +omitted): + +@smallexample +@group +Organization Environment Description +How-To-Repeat Fix Audit-Trail +Unformatted +@end group +@end smallexample + +@noindent +@xref{Regexps,,Querying using regular expressions}. + +Queries using this option can be very slow. Since this option does not +reference the index, queries using it finish much faster if you also use +another search criterion that @emph{is} part of the index (@pxref{index +file,,The @code{index} file}). + +@item -R +@itemx --restricted +Omit from the search path PRs whose @samp{>Confidential:} fields contain +the value @samp{yes}. This is equivalent to + +@smallexample +query-pr --confidential=no +@end smallexample + +@noindent +and also disallows the use of the options +@w{@samp{--outfile=@var{outfile}}} and +@w{@samp{--directory=@var{directory}}}. This option is used with the +@w{@code{mail-query}} tool. + +@item -x +@itemx --skip-closed +Omit closed PRs from the search path. This option is ignored if you +also use @w{@samp{-s @var{state}}} or @samp{--state=@var{state}}. +@end table + +@subheading Output format + +Use the following options to select the format in which the Problem +Report is printed. Use only one of these options for a given search. +If you do not specify one of these options, a header@footnote{A +@dfn{header} includes the mail header fields as well as the following +fields: @samp{>Number:}, @samp{>Category:}, @samp{>Synopsis:}, +@samp{>Confidential:}, @samp{>Severity:}, @samp{>Priority:}, +@samp{>Responsible:}, @samp{>State:}, @samp{>Class:}, +@samp{>Submitter-Id:}, @samp{>Originator:}, @samp{>Release:}, and +@samp{>Arrival-Date:}. For suggestions on using alternate output +formats in database reports, see @ref{Reporting,,Reporting}.} for the +Problem Reports meeting the search criteria is printed. + +@table @code +@item -F +@itemx --full +Prints all fields in the Problem Report rather than just summary +information. + +@item -q +@itemx --summary +Print a short single-line summary of PR information, delimited by +whitespace, including the following fields in order (the @samp{>} and +@samp{:} Problem Report fieldname delimiters have been removed for the +sake of brevity and readability): + +@smallexample +Number Responsible Category +State Severity Priority +Submitter-Id Synopsis +@end smallexample + +@item -i +@itemx --sql +Prints information on a single line with fields delimited by pipes +(@samp{|}), which can be uploaded into a relational database. When you +use this option, @code{query-pr} outputs @sc{Enumerated} fields +numerically rather than textually; see @ref{Reporting,,Reporting on +groups of Problem Reports}. + +@samp{query-pr -i} outputs the following fields, in order (again, the +fieldname delimiters @samp{>} and @samp{:} have been omitted): + +@smallexample +Number Category Synopsis +Confidential Severity Priority +Responsible State Class +Submitter-Id Arrival-Date Originator +Release +@end smallexample + +When you use the @samp{-i} option, @samp{query-pr} outputs the +@sc{Enumerated} fields in the database, namely @samp{>Severity:}, +@samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather +than text. @xref{Reporting,,Reporting on groups of Problem Reports}, +for details. + +@end table + +@subheading Other options + +@code{query-pr} also accepts the following options: + +@table @code +@item -P +@itemx --print-path +Prints the path which @code{query-pr} used to find the current PR. A +line of the form @samp{@var{directory}/@var{number}:@var{number}} is +printed before each PR. This option is automatically used from within +Emacs to facilitate scrolling through groups of PRs with @w{@kbd{C-x `}}. + +@item -d @var{directory} +@itemx --directory=@var{directory} +Changes the search directory to @var{directory} from @var{GNATS_ROOT}. + +@item -o @var{outfile} +@itemx --output=@var{outfile} +Prints all output to @var{outfile} rather than to the standard output. + +@item -V +@itemx --version +Prints the version number for @code{query-pr}. + +@item -h +@itemx --help +Prints the usage for @code{query-pr}. +@end table + + +@node Example queries +@subsection Example queries +@cindex example queries + +The following simple query: + +@smallexample +query-pr --category=rats --responsible=fred --state=analyzed +@end smallexample + +@noindent +yields all PRs in the database which contain the field values: + +@smallexample +>Category: rats @emph{and} +>Responsible: fred @emph{and} +>State: analyzed +@end smallexample + +The following query: + +@smallexample +query-pr --state="o|a" +@end smallexample + +@noindent +yields all PRs in the database whose @samp{>State:} values match either +@samp{open} or @samp{analyzed} (@pxref{Regexps,,Querying using regular +expressions}. This search is useful as a daily report that lists all +Problem Reports which require attention. + +The report can be further altered using an alternate output format for +@code{query-pr}; see @ref{Reporting,,Reporting on groups of Problem +Reports}. A more fine-grained report may be obtained by specifying more +search parameters, e.g. narrowing the search down by +@w{@samp{>Submitter:}} or by @samp{>Responsible:}. + +The following query: + +@smallexample +query-pr --text="The quick.*brown fox" +@end smallexample + +@noindent +yields all PRs whose @sc{Text} fields contain the text @samp{The quick} +followed by @samp{brown fox} within the same field. +@xref{Regexps,,Querying using regular expressions}. + +@node Reporting +@subsection Reporting on groups of Problem Reports +@cindex reporting +@cindex writing reports + +There currently exists no separate reporting mechanism in @sc{gnats} from +@code{query-pr}. However, the @samp{-q} and @samp{-i} options to +@code{query-pr} allow for easy reporting. + +For example, a report on the current open Problem Reports in the +database can be obtained using @code{awk} with + +@smallexample +query-pr -q | awk '@{print $3 "/" $1 ": " $4@}' +@end smallexample + +@noindent +which yields a list of the form + +@smallexample +@var{category}/@var{gnats-id}: @var{state} +@emph{etc@dots{}} +@end smallexample + +@noindent +For example: + +@smallexample +sprockets/123: open +widgets/456: analyzed +@emph{etc@dots{}} +@end smallexample + +@noindent +The @samp{-i} option to @code{query-pr} yields output delimited by pipes +(@samp{|}). This results in the following: + +@smallexample +@var{gnats-id}|@var{category}|@var{synopsis}|@var{confidential}|\ +@var{severity}|@var{priority}|@var{responsible}|@var{state}|@var{class}|\ +@var{submitter-id}|@var{arrival-date}|@var{originator}|@var{release} +@end smallexample + +A report on Problem Reports in the database that are currently +@samp{open} or @samp{analyzed} might resemble the following (the example +is split into two lines in order to fit onto the page; it is intended to +be typed on one command line): + +@smallexample +query-pr -i -s "o|a" | \ + awk -F\| '@{print $1 " " $2 " " $8 " " $3@}' +@end smallexample + +@noindent +which yields + +@smallexample +@var{gnats-id} @var{category} @var{state} @var{responsible} @var{synopsis} +@emph{etc@dots{}} +@end smallexample + +@noindent +For example: + +@smallexample +123 sprockets 1 fred The sprockets program gives bad output +456 widgets 2 barney The foo widget doesn't work with 'bar' +789 widgets 1 wilma The 'baz' widget is broken +@end smallexample + +@noindent +When you use the @samp{-i} option, @samp{query-pr} outputs the +@sc{Enumerated} fields in the database, namely @samp{>Severity:}, +@samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather +than text. In the example above, a @samp{>State:} value of @samp{1} +means @samp{open}, @samp{2} means @samp{analyzed}, and so forth. +@sc{Enumerated} fields are output according to the following paradigm: + +@smallexample + >Severity: >Priority: +critical 1 high 1 +serious 2 medium 2 +non-critical 3 low 3 + + >State: >Class: +open 1 sw-bug 1 +analyzed 2 doc-bug 2 +suspended 3 support 3 +feedback 4 change-request 4 +closed 5 mistaken 5 + duplicate 6 +@end smallexample + +This makes sorting on these values easy, when combined with @code{sort}. +It is left as an exercise for the reader to figure out how to do this. + +@ignore +@c it works something like... +@smallexample +query-pr -i -s "o|a" | \ + awk -F\| '@{print $8 "|" $1 "|" $2 "|" $3@}' | \ + sort -n | \ + awk -F\| '@{if $1 = "1" then \ + print "Open bugs:\n" $2 " " $3 " " $3@}' \ + '@{if $1 = "2" then \ + print "Analyzed bugs:\n" $2 " " $3 " " $3@}' +@end smallexample +@end ignore + +@node view-pr +@section Viewing individual Problem Reports +@cindex @code{view-pr} in Emacs + +Use @code{view-pr} from within Emacs to view individual Problem Reports. +Invoke @code{view-pr} with + +@smallexample +M-x view-pr +@end smallexample + +You are prompted to enter a Problem Report identification number +(@var{gnats-id}). You can also invoke @code{view-pr} with + +@smallexample +C-u @var{gnats-id} M-x view-pr +@end smallexample + +@code{view-pr} allows you to view @var{gnats-id}. This is identical to +using + +@smallexample +C-u @var{gnats-id} M-x query-pr +@end smallexample + +except that you may choose to edit the PR at any time by pressing +@samp{e}.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/s-usage.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,533 @@ +@c This is the usage section for send-pr. It is called as +@c chapter (Invoking send-pr) by send-pr.texi, and also as +@c section (Submitting Problem Reports) by gnats.texi (chapter/section +@c identifiers are adjusted accordingly) + +@c FIXME! This still seems jumbled... + +You can invoke @code{send-pr} from a shell prompt or from within +@sc{gnu} Emacs using @w{@samp{M-x send-pr}}. + +@menu +* using send-pr:: Creating new Problem Reports +* send-pr in Emacs:: Using send-pr from within Emacs +* send-pr from the shell:: Invoking send-pr from the shell +* Helpful hints:: +@end menu + +@node using send-pr +@section Creating new Problem Reports + +@c FIXME - this is a long node +Invoking @code{send-pr} presents a PR @dfn{template} with a number of +fields already filled in. Complete the template as thoroughly as +possible to make a useful bug report. Submit only one bug with each PR. + +@cindex template +A template consists of three sections: + +@table @dfn +@item Comments +The top several lines of a blank template consist of a series of +comments that provide some basic instructions for completing the Problem +Report, as well as a list of valid entries for the @samp{>Category:} +field. These comments are all preceded by the string @samp{SEND-PR:} +and are erased automatically when the PR is submitted. The +instructional comments within @samp{<} and @samp{>} are also removed. +(Only these comments are removed; lines you provide that happen to have +those characters in them, such as examples of shell-level redirection, +are not affected.) + +@item Mail Header +@code{send-pr} creates a standard mail header. @code{send-pr} completes +all fields except the @samp{Subject:} line with default values. +(@xref{Fields,,Problem Report format}.) + +@item @sc{gnats} fields +These are the informational fields that @sc{gnats} uses to route your +Problem Report to the responsible party for further action. They should +be filled out as completely as possible. (@xref{Fields,,Problem Report +format}. Also see @ref{Helpful hints,,Helpful hints}.) +@end table + +@ifset SENDPR +@noindent +For examples of a Problem Report template and complete Problem Report, +see @ref{An Example}. +@end ifset + +The default template contains your preconfigured @samp{>Submitter-Id:}. +@code{send-pr} attempts to determine values for the @samp{>Originator:} +and @samp{>Organization:} fields (@pxref{Fields,,Problem Report +format}). @code{send-pr} will set the @samp{>Originator:} field to +the value of the @code{NAME} environment variable if it has been set; +similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}. +@code{send-pr} also attempts to find out some information +about your system and architecture, and places this information in the +@samp{>Environment:} field if it finds any. + +You may submit problem reports to different Support Sites from the +default site by specifying the alternate site when you invoke +@code{send-pr}. Each @code{site} has its own list of categories for +which it accepts Problem Reports. +@c FIXME! This should go in.. +@c For a list of sites to whom @code{send-pr} is configured to send +@c Problem Reports, type @w{@samp{send-pr -S}}. +@ifset SENDPR +(@xref{default site,,Setting a default @var{site}}.) +@end ifset + +@code{send-pr} also provides the mail header section of the template +with default values in the @samp{To:}, @samp{From:}, and +@samp{Reply-To:} fields. The @samp{Subject:} field is empty. + +The template begins with a comment section: + +@cindex template comment section +@cindex comment section in the PR template +@smallexample +@group +SEND-PR: -*- send-pr -*- +SEND-PR: Lines starting with `SEND-PR' will be removed +SEND-PR: automatically as well as all comments (the text +SEND-PR: below enclosed in `<' and `>'). +SEND-PR: +SEND-PR: Please consult the document `Reporting Problems +SEND-PR: Using send-pr' if you are not sure how to fill out +SEND-PR: a problem report. +SEND-PR: +SEND-PR: Choose from the following categories: +@end group +@end smallexample + +@noindent +and also contains a list of valid @code{>Category:} values for the +Support Site to whom you are submitting this Problem Report. One (and +only one) of these values should be placed in the @code{>Category:} +field. +@ifset SENDPR +A complete sample bug report, from template to completed PR, is shown in +@ref{An Example}. For a complete list of valid categories, type +@w{@samp{send-pr -L}} at your prompt. @xref{Valid Categories,,Valid +Categories}, for a sample list of categories, . +@end ifset + +@c FIXME.. this sounds awkward +The mail header is just below the comment section. Fill out the +@samp{Subject:} field, if it is not already completed using the value of +@samp{>Synopsis:}. The other mail header fields contain default values. + +@cindex mail header section +@smallexample +@group +To: @var{support-site} +Subject: @emph{complete this field} +From: @var{your-login}@@@var{your-site} +Reply-To: @var{your-login}@@@var{your-site} +X-send-pr-version: send-pr @value{VERSION} +@end group +@end smallexample + +@noindent +where @var{support-site} is an alias for the Support Site you wish to +submit this PR to. + +The rest of the template contains @sc{gnats} fields. Each field is +either automatically completed with valid information (such as your +@samp{>Submitter-Id:}) or contains a one-line instruction specifying the +information that field requires in order to be correct. For example, +the @samp{>Confidential:} field expects a value of @samp{yes} or +@samp{no}, and the answer must fit on one line; similarly, the +@samp{>Synopsis:} field expects a short synopsis of the problem, which +must also fit on one line. Fill out the fields as completely as +possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to +what kinds of information to include. + +In this example, words in @emph{italics} are filled in with +pre-configured information: + +@cindex @code{send-pr} fields +@smallexample +@group +>Submitter-Id: @emph{your submitter-id} +>Originator: @emph{your name here} +>Organization: + @emph{your organization} +>Confidential:<[ yes | no ] (one line)> +>Synopsis: <synopsis of the problem (one line)> +>Severity: <[non-critical | serious | critical](one line)> +>Priority: <[ low | medium | high ] (one line)> +>Category: <name of the product (one line)> +>Class: <[sw-bug | doc-bug | change-request | support]> +>Release: <release number (one line)> +>Environment: + <machine, os, target, libraries (multiple lines)> + +>Description: + <precise description of the problem (multiple lines)> +>How-To-Repeat: + <code/input/activities to reproduce (multiple lines)> +>Fix: + <how to correct or work around the problem, if known + (multiple lines)> +@end group +@end smallexample + +@cindex @code{Submitter-Id} field +@cindex @code{>Submitter-Id:} +When you finish editing the Problem Report, @code{send-pr} mails it to +the address named in the @samp{To:} field in the mail header. +@code{send-pr} checks that the complete form contains a valid +@samp{>Category:}. + +@ifset SENDPR +Your copy of @code{send-pr} should have already been customized on +installation to reflect your @samp{>Submitter-Id:}. (@xref{Installing +send-pr, , Installing @code{send-pr} on your system}.) If you don't +know your @samp{>Submitter-Id:}, you can request it using +@w{@samp{send-pr --request-id}}. If your organization is not affiliated +with the site you send Problem Reports to, a good generic +@samp{>Submitter-Id:} to use is @samp{net}. +@end ifset + +@cindex bad Problem Reports +@cindex errors +@cindex invalid Problem Reports +If your PR has an invalid value in one of the @sc{Enumerated} fields +(@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in +a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine. +@var{nnnn} is the process identification number given to your current +@code{send-pr} session. If you are running @code{send-pr} from the +shell, you are prompted as to whether or not you wish to try editing the +same Problem Report again. If you are running @code{send-pr} from +Emacs, the Problem Report is placed in the buffer +@w{@samp{*send-pr-error*}}; you can edit this file and then submit it +with + +@smallexample +M-x gnats-submit-pr +@end smallexample + +@cindex subsequent mail +@cindex other mail +@cindex appending PRs +@cindex saving related mail +@cindex related mail +Any further mail concerning this Problem Report should be carbon-copied +to the @sc{gnats} mailing address as well, with the category and +identification number in the @samp{Subject:} line of the message. + +@smallexample +Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject} +@end smallexample + +@noindent +Messages which arrive with @samp{Subject:} lines of this form are +automatically appended to the Problem Report in the @samp{>Audit-Trail:} +field in the order received. + +@c --------------------------------------------------------------- +@node send-pr in Emacs +@section Using @code{send-pr} from within Emacs +@cindex using @code{send-pr} from within Emacs +@cindex @code{send-pr} within Emacs +@cindex invoking @code{send-pr} from Emacs +@cindex interactive interface + +You can use an interactive @code{send-pr} interface from within @sc{gnu} +Emacs to fill out your Problem Report. We recommend that you +familiarize yourself with Emacs before using this feature +(@pxref{Introduction,,Introduction,emacs,GNU Emacs}). + +Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing +@w{@samp{M-x send-pr}} doesn't work, see your system administrator for +help loading @code{send-pr} into Emacs.} @code{send-pr} responds with a +Problem Report template preconfigured for the Support Site from which +you received @code{send-pr}. (If you use @code{send-pr} locally, the +default Support Site is probably your local site.) + +You may also submit problem reports to different Support Sites from the +default site. To use this feature, invoke @code{send-pr} with + +@smallexample +C-u M-x send-pr +@end smallexample + +@code{send-pr} prompts you for the name of a @var{site}. @var{site} is +an alias on your local machine which points to an alternate Support +Site. + +@cindex Emacs +@code{send-pr} displays the template and prompts you in the minibuffer +with the line: +@smallexample +>Category: other +@end smallexample + +@noindent +Delete the default value @samp{other} @emph{in the minibuffer} and +replace it with the keyword corresponding to your problem (the list of +valid categories is in the topmost section of the PR template). For +example, if the problem you wish to report has to do with the @sc{gnu} C +compiler, and your support organization accepts bugs submitted for this +program under the category @samp{gcc}, delete @samp{other} and then type +@w{@samp{gcc[@key{RET}]}}. @code{send-pr} replaces the line + +@smallexample +>Category: <name of the product (one line)> +@end smallexample + +@noindent +in the template with + +@smallexample +>Category: gcc +@end smallexample + +@noindent +and moves on to another field. + +@cindex completion in Emacs +@cindex name completion in Emacs +@w{@code{send-pr}} provides name completion in the minibuffer. For +instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr} +attempts to complete the entry for you. Typing @w{@samp{g[@key{TAB}]}} +may not have the same effect if several possible entries begin with +@samp{g}. In that case @code{send-pr} cannot complete the entry because +it cannot determine whether you mean @samp{gcc} or, for example, +@samp{gdb}, if both of those are possible categories. +@w{@code{send-pr}} continues to prompt you for a valid entry until you +enter one. + +@w{@code{send-pr}} prompts you interactively to enter each field for +which there is a range of specific choices. If you attempt to enter a +value which is not in the range of acceptable entries, @code{send-pr} +responds with @w{@samp{[No match]}} and allows you to change the entry +until it contains an acceptable value. This avoids unusable information +(at least in these fields) and also avoids typographical errors which +could cause problems later. + +@code{send-pr} prompts you for the following fields: + +@c FIXME - should these go before the discussion on completion? +@example +@group +>Category: +>Confidential: (@emph{default}: no) +>Severity: (@emph{default}: serious) +>Priority: (@emph{default}: medium) +>Class: (@emph{default}: sw-bug) +>Release: +>Synopsis: (@emph{this value is copied to @code{Subject:}}) +@end group +@end example + +@noindent +After you complete these fields, @w{@code{send-pr}} places the cursor in +the @samp{>Description:} field and displays the message + +@smallexample +To send the problem report use: C-c C-c +@end smallexample + +@noindent +in the minibuffer. At this point, edit the file in the main buffer to +reflect your specific problem, putting relevant information in the +proper fields. +@ifset SENDPR +@xref{An Example}, for a sample Problem Report. +@end ifset + +@w{@samp{send-pr}} provides a few key bindings to make moving +around in a template buffer more simple: + +@table @code +@item C-c C-f +@itemx M-x change-field +Changes the field under the cursor. @code{edit-pr} prompts you for a +new value. + +@item M-C-b +@itemx M-x gnats-backward-field +Moves the cursor to the beginning of the value of the current field. + +@item M-C-f +@itemx M-x gnats-forward-field +Moves the cursor to the end of the value of the current field. + +@item M-p +@itemx M-x gnats-previous-field +Moves the cursor back one field to the beginning of the value of the +previous field. + +@item M-n +@itemx M-x gnats-next-field +Moves the cursor forward one field to the beginning of the value of the +next field. +@end table + +@code{send-pr} takes over again when you type @samp{C-c C-c} to send the +message. @code{send-pr} reports any errors in a separate buffer, which +remains in existence until you send the PR properly (or, of course, +until you explicitly kill the buffer). + +For detailed instructions on using Emacs, see +@ref{Introduction,,,emacs,GNU Emacs}. + +@node send-pr from the shell +@section Invoking @code{send-pr} from the shell +@cindex command line options +@cindex invoking @code{send-pr} from the shell +@cindex shell invocation + +@c FIXME! Add [ -S ] right after [ -L ]... +@smallexample +send-pr [ @var{site} ] + [ -f @var{problem-report} | --file @var{problem-report} ] + [ -t @var{mail-address} | --to @var{mail-address} ] + [ --request-id ] + [ -L | --list ] [ -P | --print ] + [ -V | --version] [ -h | --help ] +@end smallexample + +@var{site} is an alias on your local machine which points to an address +used by a Support Site. If this argument is not present, the default +@var{site} is usually the site which you received @code{send-pr} from, +or your local site if you use @sc{gnats} locally. +@ifset SENDPR +(@xref{default site,,Setting a default @var{site}}.) +@end ifset + +Invoking @code{send-pr} with no options calls the editor named in your +environment variable @code{EDITOR} on a default PR template. If the +environment variable @code{PR_FORM} is set, its value is used as a file +name which contains a valid template. If @code{PR_FORM} points to a +missing or unreadable file, or if the file is empty, @code{send-pr} +generates an error message and opens the editor on a default template. + +@table @code +@item -f @var{problem-report} +@itemx --file @var{problem-report} +Specifies a file, @var{problem-report}, where a completed Problem Report +already exists. @code{send-pr} sends the contents of the file without +invoking an editor. If @var{problem-report} is @samp{-}, +@w{@code{send-pr}} reads from standard input. + +@item -t @var{mail-address} +@itemx --to @var{mail-address} +Sends the PR to @var{mail-address}. The default is preset when +@code{send-pr} is configured. @emph{This option is not recommended}; +instead, use the argument @var{site} on the command line. + +@item -c @var{mail-address} +@itemx --cc @var{mail-address} +Places @var{mail-address} in the @code{Cc:} header field of the message +to be sent. + +@item --request-id +Sends a request for a @code{>Submitter-Id:} to the Support Site. + +@cindex listing valid categories +@item -L +@itemx --list +Prints the list of valid @code{>Category:} values on standard output. +No mail is sent. + +@item -s @var{severity} +@itemx --severity @var{severity} +@cindex @code{send-pr} fields +Sets the initial value of the @code{>Severity:} field to @var{severity}. + +@ignore +@item -S +@itemx --sites +Displays a list of valid @var{site} values on standard output. No mail +is sent. +@end ignore + +@item -P +@itemx --print +Displays the PR template. If the variable @code{PR_FORM} is set in your +environment, the file it specifies is printed. If @code{PR_FORM} is not +set, @code{send-pr} prints the standard blank form. If the file +specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an +error message. No mail is sent. + +@item -V +@itemx --version +Displays the @code{send-pr} version number and a usage summary. No mail +is sent. + +@item -h +@itemx --help +Displays a usage summary for @code{send-pr}. No mail is sent. +@end table + +@node Helpful hints +@section Helpful hints +@cindex helpful hints +@cindex Using and Porting @sc{gnu} CC +@cindex effective problem reporting +@cindex kinds of helpful information +@cindex information to submit +@cindex Report all the facts! + +There is no orthodox standard for submitting effective bug reports, +though you might do well to consult the section on submitting bugs for + +@sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and +Porting GNU CC}, by Richard Stallman. This section contains +instructions on what kinds of information to include and what kinds of +mistakes to avoid. + +In general, common sense (assuming such an animal exists) dictates the +kind of information that would be most helpful in tracking down and +resolving problems in software. +@itemize @bullet +@item +Include anything @emph{you} would want to know if you were looking at +the report from the other end. There's no need to include every minute +detail about your environment, although anything that might be different +from someone else's environment should be included (your path, for +instance). + +@item +Narratives are often useful, given a certain degree of restraint. If a +person responsible for a bug can see that A was executed, and then B and +then C, knowing that sequence of events might trigger the realization of +an intermediate step that was missing, or an extra step that might have +changed the environment enough to cause a visible problem. Again, +restraint is always in order (``I set the build running, went to get a +cup of coffee (Columbian, cream but no sugar), talked to Sheila on the +phone, and then THIS happened@dots{}'') but be sure to include anything +relevant. + +@item +Richard Stallman writes, ``The fundamental principle of reporting bugs +usefully is this: @strong{report all the facts}. If you are not sure +whether to state a fact or leave it out, state it!'' This holds true +across all problem reporting systems, for computer software or social +injustice or motorcycle maintenance. It is especially important in the +software field due to the major differences seemingly insignificant +changes can make (a changed variable, a missing semicolon, etc.). + +@item +Submit only @emph{one} problem with each Problem Report. If you have +multiple problems, use multiple PRs. This aids in tracking each problem +and also in analyzing the problems associated with a given program. + +@item +It never hurts to do a little research to find out if the bug you've +found has already been reported. Most software releases contain lists +of known bugs in the Release Notes which come with the software; see +your system administrator if you don't have a copy of these. + +@item +The more closely a PR adheres to the standard format, the less +interaction is required by a database administrator to route the +information to the proper place. Keep in mind that anything that +requires human interaction also requires time that might be better spent +in actually fixing the problem. It is therefore in everyone's best +interest that the information contained in a PR be as correct as +possible (in both format and content) at the time of submission. +@end itemize
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/send-pr.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,656 @@ +\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: (send-pr). Reporting problems--using send-pr +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1993, 1994, 1995 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, 1994, 1995 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 @sc{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
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/states.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,53 @@ +@node States +@section States of Problem Reports + +@cindex life-cycle of a Problem Report +@cindex states of Problem Reports +@cindex Problem Report states +@cindex automatic notification + +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. + +@table @dfn +@cindex @emph{open} state +@cindex initial state (@dfn{open}) +@cindex state---@dfn{open} +@item open +The initial state of a Problem Report. This means the PR has been filed +and the responsible person(s) notified. + +@cindex @emph{analyzed} state +@cindex state---@dfn{analyzed} +@item 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. + +@cindex @emph{feedback} state +@cindex state---@dfn{feedback} +@item 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. + +@cindex @emph{closed} state +@cindex state---@dfn{closed} +@cindex final state (@dfn{closed}) +@item 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. + +@cindex @emph{suspended} state +@cindex state---@dfn{suspended} +@item 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. +@end table +
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/man/gnats/version.texi Mon Aug 13 09:20:48 2007 +0200 @@ -0,0 +1,1 @@ +@set VERSION 3.101
--- a/man/gnus.texi Mon Aug 13 09:19:47 2007 +0200 +++ b/man/gnus.texi Mon Aug 13 09:20:48 2007 +0200 @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @setfilename gnus -@settitle Gnus 5.4 Manual +@settitle Gnus 5.4.28 Manual @synindex fn cp @synindex vr cp @synindex pg cp @@ -287,13 +287,13 @@ @tex @titlepage -@title Gnus 5.4 Manual +@title Gnus 5.4.28 Manual @author by Lars Magne Ingebrigtsen @page @vskip 0pt plus 1filll -Copyright @copyright{} 1995,96 Free Software Foundation, Inc. +Copyright @copyright{} 1995,96,97 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -323,7 +323,7 @@ spool or your mbox file. All at the same time, if you want to push your luck. -This manual corresponds to Gnus 5.4. +This manual corresponds to Gnus 5.4.28 @end ifinfo @@ -1816,8 +1816,9 @@ command, you will be prompted for a file name and a file type. Currently supported types are @code{babyl}, @code{mbox}, @code{digest}, @code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, -@code{rfc934} and @code{forward}. If you run this command without a -prefix, Gnus will guess at the file type. @xref{Document Groups}. +@code{rfc934}, @code{rfc822-forward}, and @code{forward}. If you run +this command without a prefix, Gnus will guess at the file type. +@xref{Document Groups}. @item G w @kindex G w (Group) @@ -1898,6 +1899,10 @@ followup---except that if it is present in a news group, you'll get mail group semantics when doing @kbd{f}. +If you do an @kbd{a} command in a mail group and you don't have a +@code{to-list} group parameter, one will be added automatically upon +sending the message. + @item broken-reply-to @cindex broken-reply-to Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} @@ -9131,7 +9136,9 @@ @vindex nnmail-expiry-wait The @code{nnmail-expiry-wait} variable supplies the default time an -expirable article has to live. The default is seven days. +expirable article has to live. Gnus starts counting days from when the +message @emph{arrived}, not from when it was sent. The default is seven +days. Gnus also supplies a function that lets you fine-tune how long articles are to live, based on what group they are in. Let's say you want to @@ -9755,8 +9762,9 @@ @item nndoc-article-type @vindex nndoc-article-type This should be one of @code{mbox}, @code{babyl}, @code{digest}, -@code{mmdf}, @code{forward}, @code{rfc934}, @code{news}, @code{rnews}, -@code{mime-digest}, @code{clari-briefs}, or @code{guess}. +@code{mmdf}, @code{forward}, @code{rfc934}, @code{rfc822-forward}, +@code{news}, @code{rnews}, @code{mime-digest}, @code{clari-briefs}, or +@code{guess}. @item nndoc-post-type @vindex nndoc-post-type @@ -13843,6 +13851,7 @@ Adrian Aichner, Peter Arius, +Matt Armstrong, Marc Auslander, Chris Bone, Mark Borges, @@ -13894,6 +13903,7 @@ Shlomo Mahlab, Nat Makarevitch, David Martin, +Gordon Matzigkeit, Timo Metzemakers, Richard Mlynarik, Lantz Moore, @@ -13916,6 +13926,7 @@ Loren Schall, Dan Schmidt, Ralph Schleicher, +Philippe Schnoebelen, Randal L. Schwartz, Danny Siu, Paul D. Smith,
--- a/man/internals/internals.texi Mon Aug 13 09:19:47 2007 +0200 +++ b/man/internals/internals.texi Mon Aug 13 09:20:48 2007 +0200 @@ -486,6 +486,10 @@ version 19.12 released June 23, 1995. @item version 19.13 released September 1, 1995. +@item +version 19.14 released June 23, 1996. +@item +version 20.0 released February 9, 1997. @end itemize @node GNU Emacs 19 @@ -544,6 +548,18 @@ version 19.28 (first ``official'' release) released November 1, 1994. @item version 19.29 released June 21, 1995. +@item +version 19.30 released November 24, 1995. +@item +version 19.31 released May 25, 1996. +@item +version 19.32 released July 31, 1996. +@item +version 19.33 released August 11, 1996. +@item +version 19.34 released August 21, 1996. +@item +version 19.34b released September 6, 1996. @end itemize @cindex Mlynarik, Richard
--- a/man/widget.texi Mon Aug 13 09:19:47 2007 +0200 +++ b/man/widget.texi Mon Aug 13 09:20:48 2007 +0200 @@ -1,6 +1,6 @@ \input texinfo.tex -@c $Id: widget.texi,v 1.7 1997/03/16 03:06:11 steve Exp $ +@c $Id: widget.texi,v 1.8 1997/03/18 03:27:04 steve Exp $ @c %**start of header @setfilename widget @@ -15,7 +15,7 @@ @comment node-name, next, previous, up @top The Emacs Widget Library -Version: 1.63 +Version: 1.64 @menu * Introduction::
--- a/src/ChangeLog Mon Aug 13 09:19:47 2007 +0200 +++ b/src/ChangeLog Mon Aug 13 09:20:48 2007 +0200 @@ -1,3 +1,13 @@ +Mon Mar 17 15:40:12 1997 David Moore <dmoore@ucsd.edu> + + * glyphs-x.c (our_own_dgif_slurp_from_gif2x11_c): Only get the + first image out of a multi-image or animated gif. + +Mon Mar 17 15:27:26 1997 Steven L Baur <steve@altair.xemacs.org> + + * Makefile.in.in (xemacs): Invert sense of test for successful + completion of XEmacs dump. + Sat Mar 15 14:21:39 1997 David Moore <dmoore@ucsd.edu> * fileio.c (Fdo_auto_save): Protect against file handlers which
--- a/src/Makefile.in.in Mon Aug 13 09:19:47 2007 +0200 +++ b/src/Makefile.in.in Mon Aug 13 09:20:48 2007 +0200 @@ -1335,18 +1335,20 @@ else true; fi @touch SATISFIED -$(DUMPENV) ./temacs -nl -batch -l loadup.el dump - @if [ -f SATISFIED ]; then \ + @if [ ! -f SATISFIED ]; then \ $(MAKE) release; \ fi + @/bin/rm -f SATISFIED #else /* ! defined (HAVE_SHM) */ -if [ -w ${srcdir}/../lisp ]; then \ w=`pwd`; cd ${srcdir} && $${w}/temacs -batch -l inc-vers; \ else true; fi @touch SATISFIED -$(DUMPENV) ./temacs -batch -l loadup.el dump - @if [ -f SATISFIED ]; then \ + @if [ ! -f SATISFIED ]; then \ $(MAKE) release; \ fi + @/bin/rm -f SATISFIED #endif /* ! defined (HAVE_SHM) */ touch release #endif /* ! defined (CANNOT_DUMP) */ @@ -1354,16 +1356,18 @@ xemacs: temacs ${libsrc}DOC ${lisp} MOFILE OTHER_FILES @touch SATISFIED -$(DUMPENV) ./temacs -batch -l loadup.el dump - @if [ -f SATISFIED ]; then \ + @if [ ! -f SATISFIED ]; then \ $(MAKE) xemacs; \ fi + @/bin/rm -f SATISFIED xemacs-no-site-file: temacs ${libsrc}DOC ${lisp} MOFILE OTHER_FILES @touch SATISFIED -$(DUMPENV) ./temacs -batch -l loadup.el dump no-site-file - @if [ -f SATISFIED ]; then \ + @if [ ! -f SATISFIED ]; then \ $(MAKE) xemacs-no-site-file; \ fi + @/bin/rm -f SATISFIED obj_src = $(objs:.o=.c) @@ -1378,7 +1382,7 @@ ${libsrc}DOC: ${libsrc}make-docfile ${obj_src} ${mule_obj_src} ${lisp} #endif rm -f ${libsrc}DOC - ${libsrc}make-docfile -d ${srcdir} -i ${lispdir}../site-packages \ + ${libsrc}make-docfile -d ${srcdir} -i ../site-packages \ ${obj_src} ${mule_obj_src} \ ${mallocdocsrc} ${rallocdocsrc} ${lispdir}version.el \ ${lisp} > ${libsrc}DOC @@ -1386,7 +1390,12 @@ dump_elcs: dump-elcs dump-elcs: temacs - $(LOADPATH) ./temacs -batch -l ../prim/update-elc.el $(lisp) $(otherlisp) + @touch SATISFIED + -$(LOADPATH) ./temacs -batch -l ../prim/update-elc.el $(lisp) $(otherlisp) + @if [ ! -f SATISFIED ]; then \ + $(MAKE) dump-elcs; \ + fi + @/bin/rm -f SATISFIED all-elc all-elcs: cd .. && $(MAKE) all-elc $(MFLAGS)
--- a/src/alloc.c Mon Aug 13 09:19:47 2007 +0200 +++ b/src/alloc.c Mon Aug 13 09:20:48 2007 +0200 @@ -2738,11 +2738,11 @@ clear_message (); if (rc < 0) { + (void)unlink("SATISFIED"); fatal ("Pure size adjusted, will restart `make'"); } else if (pure_lossage && die_if_pure_storage_exceeded) { fatal ("Pure storage exhausted"); } - (void)sys_unlink("SATISFIED"); }
--- a/src/glyphs-x.c Mon Aug 13 09:19:47 2007 +0200 +++ b/src/glyphs-x.c Mon Aug 13 09:20:48 2007 +0200 @@ -1678,6 +1678,12 @@ return GIF_ERROR; } } + + /* Only get 1 image from animated gifs. */ + /* #### if the rest of the file was bad, we still return + GIF_OK, since we don't even bother looking at it. Should + probably check for ImageCount == 1 above too, hmm. */ + goto done; break; case EXTENSION_RECORD_TYPE: @@ -1701,6 +1707,8 @@ } while (RecordType != TERMINATE_RECORD_TYPE); + done: + return GIF_OK; }
--- a/src/redisplay-x.c Mon Aug 13 09:19:47 2007 +0200 +++ b/src/redisplay-x.c Mon Aug 13 09:20:48 2007 +0200 @@ -1150,6 +1150,7 @@ GC gc; XGCValues gcv; unsigned long pixmap_mask; + int need_clipping = (clip_x || clip_y); if (!override_gc) { @@ -1167,14 +1168,27 @@ gcv.clip_y_origin = y - pixmap_offset; pixmap_mask |= (GCFunction | GCClipMask | GCClipXOrigin | GCClipYOrigin); + /* Can't set a clip rectangle below because we already have a mask. + We could conceivably create a new clipmask by zeroing out + everything outside the clip region. Is it worth it? + Is it possible to get an equivalent effect by changing the + args to XCopyArea below rather than messing with a clip box? + - dkindred@cs.cmu.edu */ + need_clipping = 0; } gc = gc_cache_lookup (DEVICE_X_GC_CACHE (d), &gcv, pixmap_mask); } else - gc = override_gc; + { + gc = override_gc; + /* override_gc might have a mask already--we don't want to nuke it. + Maybe we can insist that override_gc have no mask, or use + one of the suggestions above. */ + need_clipping = 0; + } - if (clip_x || clip_y) + if (need_clipping) { XRectangle clip_box[1]; @@ -1209,7 +1223,7 @@ 1L); } - if (clip_x || clip_y) + if (need_clipping) { XSetClipMask (dpy, gc, None); XSetClipOrigin (dpy, gc, 0, 0);