# HG changeset patch
# User stephent
# Date 1060596432 0
# Node ID 138c42c84aec8d2245d899d2711f8d52799613ab
# Parent  28ffd53a1d42f565645471d2729f634b8825ec4b
[xemacs-hg @ 2003-08-11 10:07:09 by stephent]
package style guide <874r0oh5lo.fsf@tleepslib.sk.tsukuba.ac.jp>

diff -r 28ffd53a1d42 -r 138c42c84aec man/ChangeLog
--- a/man/ChangeLog	Mon Aug 11 10:03:36 2003 +0000
+++ b/man/ChangeLog	Mon Aug 11 10:07:12 2003 +0000
@@ -1,3 +1,9 @@
+2003-08-05  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* lispref/packaging.texi (Creating Packages):
+	* xemacs/packages.texi (Creating Packages):
+	Style guideline for package-info.in description.
+
 2003-06-30  Vin Shelton  <acs@xemacs.org>
 
 	* lispref/lists.texi (List-related Predicates): Add @end defun.
diff -r 28ffd53a1d42 -r 138c42c84aec man/lispref/packaging.texi
--- a/man/lispref/packaging.texi	Mon Aug 11 10:03:36 2003 +0000
+++ b/man/lispref/packaging.texi	Mon Aug 11 10:07:12 2003 +0000
@@ -748,7 +748,7 @@
    priority high
    category CATEGORY                ; Makefile
    dump nil
-   description "description"        ; a one-line description string
+   description "DESCRIPTION"        ; a one-line period-terminated string
    filename FILENAME                ; obsolete
    md5sum MD5SUM                    ; generated
    size SIZE                        ; generated
@@ -762,11 +762,13 @@
 @end example
 
 You should replace NAME, DISTRIBUTION, DESCRIPTION, and FEATURE ... with
-appropriate values, according to the comments.  Fields marked as
-@samp{obsolete} can be ignored.  Fields marked as @samp{generated} are
-generated by the package construction process, and will be filled in
-automatically.  Fields marked as @samp{Makefile} should be set as
-variables in the @file{Makefile}.
+appropriate values, according to the comments.  As a matter of style,
+the first letter of the description should be capitalized, and the
+string should end with a period.  It need not be a complete sentence
+grammatically.  Fields marked as @samp{obsolete} can be ignored.  Fields
+marked as @samp{generated} are generated by the package construction
+process, and will be filled in automatically.  Fields marked as
+@samp{Makefile} should be set as variables in the @file{Makefile}.
 
 The @samp{provides} can be done automatically, but currently aren't.  It
 would probably be a good idea to set them in the @file{Makefile} (they
diff -r 28ffd53a1d42 -r 138c42c84aec man/xemacs/packages.texi
--- a/man/xemacs/packages.texi	Mon Aug 11 10:03:36 2003 +0000
+++ b/man/xemacs/packages.texi	Mon Aug 11 10:07:12 2003 +0000
@@ -575,7 +575,7 @@
    priority high
    category CATEGORY
    dump nil
-   description "description"        ; a one-line description string
+   description "DESCRIPTION"        ; one-line period-terminated string
    filename FILENAME
    md5sum MD5SUM
    size SIZE
@@ -590,11 +590,13 @@
 of the main Lisp file or principal feature provided.  The allowed values
 for distribution are @code{xemacs} and @code{mule}.  Write them as
 unquoted symbols.  The @code{description} is a quoted Lisp string; use
-the usual conventions.  The value for @code{provides} is a list of
-feature symbols (written unquoted).  All of the features provided by
-libraries in your package should be elements of this list.  Implementing
-an automatic method for generating the @file{provides} line is
-desirable, but as yet undone.
+the usual conventions.  The first letter should be capitalized, and the
+string should end in a period.  It need not be a complete sentence
+grammatically.  The value for @code{provides} is a list of feature
+symbols (written unquoted).  All of the features provided by libraries
+in your package should be elements of this list.  Implementing an
+automatic method for generating the @file{provides} line is desirable,
+but as yet undone.
 
 The variables in upper-case are references to variables set in the
 @file{Makefile} or automatically generated.  Do not change them; they