os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add in more details about how to write a good COMMENT

Browse source 
Approved by:	portmgr@ (implicit)
This commit is contained in:
Carlo Strub 2012-07-29 19:12:09 +00:00
parent 519e063152
commit afc0f25e5d
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=39282
1 changed files with 32 additions and 10 deletions

42
en_US.ISO8859-1/books/porters-handbook/book.sgml
View file

@ -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">