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

[Eitan Adler]

Author: eadler
Date: Sun Jun 22 07:51:24 2014
New Revision: 45097
URL: http://svnweb.freebsd.org/changeset/doc/45097

Log:
  porter's handbook: better handle OPTION_DESC
  
  - Make some of the porter's handbook examples better.
  - move a tip to a general paragraph.
  - clarify a tip

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	Sat Jun 21 23:37:15 2014	(r45096)
+++ head/en_US.ISO8859-1/books/porters-handbook/makefiles/chapter.xml	Sun Jun 22 07:51:24 2014	(r45097)
@@ -3288,7 +3288,7 @@ LIB_DEPENDS=	libbar.so:${PORTSDIR}/foo/b
 	<title>Correct Declaration of an Optional Dependency</title>
 
 	<programlisting>OPTIONS_DEFINE=	BAR
-BAR_DESC=	Bar support
+BAR_DESC=	Calling cellphones via bar
 
 BAR_LIB_DEPENDS=	libbar.so:${PORTSDIR}/foo/bar</programlisting>
       </example>
@@ -3499,16 +3499,16 @@ OPT4_DESC=	Describe OPT4
 OPT5_DESC=	Describe OPT5
 OPT6_DESC=	Describe OPT6</programlisting>
 
-	<tip>
-	  <para><filename>ports/Mk/bsd.options.desc.mk</filename>
+	<para><filename>ports/Mk/bsd.options.desc.mk</filename>
 	    has descriptions for many common
-	    <varname>OPTIONS</varname>; there is usually no need to
-	    override these.</para>
-	</tip>
+	    <varname>OPTIONS</varname>.  While often useful, they
+	    should be overriden if the description is insufficient
+	    for the port.</para>
 
 	<tip>
 	  <para>When describing options, view it from the
-	    perspective of the user: <quote>What does it do?</quote>
+	    perspective of the user: <quote>What functionality does it
+	    change?</quote>
 	    and <quote>Why would I want to enable this?</quote>
 	    Do not just repeat the name.  For example, describing the
 	    <literal>NLS</literal> option as
@@ -3576,8 +3576,8 @@ OPTIONS_GROUP_GG1=	OPT9 OPT10</programli
 	  <title>Simple Use of <varname>OPTIONS</varname></title>
 
 	  <programlisting>OPTIONS_DEFINE=	FOO BAR
-FOO_DESC=	Enable option foo
-BAR_DESC=	Support feature bar
+FOO_DESC=	Option foo support
+BAR_DESC=	Feature bar support
 
 OPTIONS_DEFAULT=FOO