svn commit: r39282 - head/en_US.ISO8859-1/books/porters-handbook

[Carlo Strub]

Author: cs (ports committer)
Date: Sun Jul 29 19:12:09 2012
New Revision: 39282
URL: http://svn.freebsd.org/changeset/doc/39282

Log:
  Add in more details about how to write a good COMMENT
  
  Approved by:	portmgr@ (implicit)

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/book.sgml

Modified: head/en_US.ISO8859-1/books/porters-handbook/book.sgml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/book.sgml	Sun Jul 29 17:35:46 2012	(r39281)
+++ head/en_US.ISO8859-1/books/porters-handbook/book.sgml	Sun Jul 29 19:12:09 2012	(r39282)
@@ -133,7 +133,7 @@ CATEGORIES=	games
 MASTER_SITES=	ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/
 
 MAINTAINER=	asami at FreeBSD.org
-COMMENT=	A cat chasing a mouse all over the screen
+COMMENT=	Cat chasing a mouse all over the screen
 
 MAN1=		oneko.1
 MANCOMPRESSED=	yes
@@ -3411,20 +3411,42 @@ ALWAYS_KEEP_DISTFILES=	yes
       <title><makevar>COMMENT</makevar></title>
 
       <para>This is a one-line description of the port.
-	<emphasis>Please</emphasis> do not include the package name
-	(or version number of the software) in the comment.  The
-	comment should begin with a capital and end without a period.
-	Here is an example:</para>
+        Please respect the following rules:</para>
+	  <orderedlist>
+	    <listitem>
+	      <para>Try to keep the COMMENT value at no longer than 70
+		characters, as this line will be used by the &man.pkg.info.1;
+		utility to display a one-line summary of the port;</para>
+	    </listitem>
+	    <listitem>
+	      <para>Do <emphasis>not</emphasis> include the package name
+	      (or version number of the software);</para>
+	    </listitem>
+	    <listitem>
+	      <para>The comment should begin with a capital and end without a
+	      period;</para>
+	    </listitem>
+	    <listitem>
+	      <para>Do not start with an indefinite article (i.e. A or An);</para>
+	    </listitem>
+	    <listitem>
+	      <para>Names are capitalized (e.g. Apache, JavaScript, Perl);</para>
+	    </listitem>
+	    <listitem>
+	      <para>For lists of words use the Oxford comma (e.g. green,
+	      red<emphasis>,</emphasis> and blue);</para>
+	    </listitem>
+	    <listitem>
+	      <para>Spell check the text.</para>
+	    </listitem>
+	  </orderedlist>
+	<para>Here is an example:</para>
 
-      <programlisting>COMMENT=	A cat chasing a mouse all over the screen</programlisting>
+      <programlisting>COMMENT=	Cat chasing a mouse all over the screen</programlisting>
 
       <para>The COMMENT variable should immediately follow the
 	MAINTAINER variable in the
 	<filename>Makefile</filename>.</para>
-
-      <para>Please try to keep the COMMENT value at no longer than 70
-	characters, as this line will be used by the &man.pkg.info.1;
-	utility to display a one-line summary of the port.</para>
     </sect1>
 
     <sect1 id="makefile-depend">