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

[Jason Helfman]

Author: jgh
Date: Tue Apr 12 18:42:10 2016
New Revision: 48574
URL: https://svnweb.freebsd.org/changeset/doc/48574

Log:
  - convert ordered list to unordered list
  - address rules verbiage and grammar
  
  Reviewed with: wblock@

Modified:
  head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml

Modified: head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Apr 12 18:19:29 2016	(r48573)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Tue Apr 12 18:42:10 2016	(r48574)
@@ -3124,46 +3124,43 @@ ALWAYS_KEEP_DISTFILES=	yes
   <sect1 xml:id="makefile-comment">
     <title><varname>COMMENT</varname></title>
 
-    <para>This is a one-line description of the port.  Please respect
-      these rules:</para>
+    <para>The comment is a one-line description of a port shown by
+      <command>pkg info</command>.  Please follow these rules when
+      composing it:</para>
 
-    <orderedlist>
+    <itemizedlist>
       <listitem>
-	<para>Try to keep the COMMENT value at no longer than 70
-	  characters, as this line will be used by
-	  <command>pkg info</command> (see &man.pkg-info.8;) to
-	  display a one-line summary of the port;</para>
+	<para>The COMMENT string should be 70 characters or less.</para>
       </listitem>
 
       <listitem>
-	<para>Do <emphasis>not</emphasis> include the package name (or
-	  version number of the software);</para>
+	<para>Do <emphasis>not</emphasis> include the package name or
+	  version number of software.</para>
       </listitem>
 
       <listitem>
 	<para>The comment must begin with a capital and end without
-	  a period;</para>
+	  a period.</para>
       </listitem>
 
       <listitem>
 	<para>Do not start with an indefinite article (that is, A or
-	  An);</para>
+	  An).</para>
       </listitem>
 
       <listitem>
-	<para>Names are capitalized (for example, Apache, JavaScript,
-	  Perl);</para>
+	<para>Capitalize names such as Apache, JavaScript, or Perl.</para>
       </listitem>
 
       <listitem>
-	<para>For lists of words, use the Oxford comma (for example,
-	  green, red<emphasis>,</emphasis> and blue);</para>
+	<para>Use a serial comma for lists of words: "green,
+	  red<emphasis>,</emphasis> and blue."</para>
       </listitem>
 
       <listitem>
-	<para>Spell check the text.</para>
+	<para>Check for spelling errors.</para>
       </listitem>
-    </orderedlist>
+    </itemizedlist>
 
     <para>Here is an example:</para>