Date: Sun, 29 Jul 2012 19:12:10 +0000 (UTC) From: Carlo Strub <cs@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39282 - head/en_US.ISO8859-1/books/porters-handbook Message-ID: <201207291912.q6TJCAPB089082@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201207291912.q6TJCAPB089082>