Document USES=cpe.

Reviewed by:	wblock, des, antoine
Sponsored by:	Absolight

1 files changed, 90 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
index 2d60849f70..3e87756cc3 100644
--- a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -166,6 +166,96 @@
 	    <filename>pkg-plist</filename>.</entry>
 	</row>
 
+	<row xml:id="uses-cpe">
+	  <entry><literal>cpe</literal></entry>
+
+	  <entry>(none)</entry>
+
+	  <entry>
+	    Include Common Platform Enumeration
+	    (<acronym>CPE</acronym>) information in package manifest
+	    as a <acronym>CPE</acronym> 2.3 formatted string.  See the
+	    <link
+	      xlink:href="http://scap.nist.gov/specifications/cpe/"><acronym>CPE</acronym>
+	      specification</link> for details.  To add
+	    <acronym>CPE</acronym> information to a port, follow these
+	    steps:
+
+	    <procedure>
+	      <step>
+		<para>Search for the official CPE entry for the
+		  software product either by using the NVD's <link
+		    xlink:href="http://web.nvd.nist.gov/view/cpe/search"><acronym>CPE</acronym>
+		    search engine</link> or in the <link
+		    xlink:href="http://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml">official
+		    <acronym>CPE</acronym> dictionary</link> (warning,
+		  very large <acronym>XML</acronym> file).
+		  <emphasis>Do not ever make up <acronym>CPE</acronym>
+		    data.</emphasis></para>
+	      </step>
+
+	      <step>
+		<para>Add <literal>cpe</literal> to
+		  <varname>USES</varname> and compare the result of
+		  <command>make -V CPE_STR</command> to the
+		  <acronym>CPE</acronym> dictionary entry.  Continue
+		  one step at a time until <command>make -V
+		    CPE_STR</command> is correct.</para>
+	      </step>
+
+	      <step>
+		<para>If the product name (second field, defaults to
+		  <varname>PORTNAME</varname>) is incorrect, define
+		  <varname>CPE_PRODUCT</varname>.</para>
+	      </step>
+
+	      <step>
+		<para>If the vendor name (first field, defaults to
+		  <varname>CPE_PRODUCT</varname>) is incorrect, define
+		  <varname>CPE_VENDOR</varname>.</para>
+	      </step>
+
+	      <step>
+		<para>If the version field (third field, defaults to
+		  <varname>PORTVERSION</varname>) is incorrect, define
+		  <varname>CPE_VERSION</varname>.</para>
+	      </step>
+
+	      <step>
+		<para>If the update field (fourth field, defaults to
+		  empty) is incorrect, define
+		  <varname>CPE_UPDATE</varname>.</para>
+	      </step>
+
+	      <step>
+		<para>If it is still not correct, check
+		  <filename>Mk/Uses/cpe.mk</filename> for additional
+		  details, or contact the &a.ports-secteam;.</para>
+	      </step>
+
+	      <step>
+		<para>Derive as much as possible of the
+		  <acronym>CPE</acronym> name from existing variables
+		  such as <varname>PORTNAME</varname> and
+		  <varname>PORTVERSION</varname>.  Use variable
+		  modifiers to extract the relevant portions from
+		  these variables rather than hardcoding the
+		  name.</para>
+	      </step>
+
+	      <step>
+		<para><emphasis>Always</emphasis> run <command>make -V
+		    CPE_STR</command> and check the output before
+		  committing anything that changes
+		  <varname>PORTNAME</varname> or
+		  <varname>PORTVERSION</varname> or any other variable
+		  which is used to derive
+		  <varname>CPE_STR</varname>.</para>
+	      </step>
+	    </procedure>
+	  </entry>
+	</row>
+
 	<row xml:id="uses-desktop-file-utils">
 	  <entry><literal>desktop-file-utils</literal></entry>