Add a section on how to search for ports using pkg search.

I've updated the submitted patch slightly by wrapping the version numbers
of the resulting ports in the example in <replaceable>s so that people
know that they might have a different output as time goes by.
I also rephrased a paragraph so that it does not start with a <command> tag.

PR:		187351
Submitted by:	Allan Jude

1 files changed, 58 insertions, 1 deletions

diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
index 389ed18694..79ef897354 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
@@ -202,7 +202,9 @@
 	for security issues related to the application or install
 	<package>ports-mgmt/portaudit</package>.  Once installed, type
 	<command>portaudit -F -a</command> to check all installed
-	applications for known vulnerabilities.</para>
+	applications for known vulnerabilities.  If you are using
+	<application>pkg</application>, the audit functionality is
+	built in.  Simply run: <command>pkg audit -F</command>.</para>
     </warning>
 
     <para>The remainder of this chapter explains how to use packages
@@ -249,6 +251,61 @@
       </listitem>
 
       <listitem>
+	<indexterm>
+	  <primary>pkg</primary>
+	  <secondary>search</secondary>
+	</indexterm>
+
+	<para xml:id="pkg-search">To search the binary package
+	  repository for an application:</para>
+
+	<screen>&prompt.root; <userinput>pkg search <replaceable>subversion</replaceable></userinput>
+git-subversion-<replaceable>1.9.2</replaceable>
+java-subversion-<replaceable>1.8.8_2</replaceable>
+p5-subversion-<replaceable>1.8.8_2</replaceable>
+py27-hgsubversion-<replaceable>1.6</replaceable>
+py27-subversion-<replaceable>1.8.8_2</replaceable>
+ruby-subversion-<replaceable>1.8.8_2</replaceable>
+subversion-<replaceable>1.8.8_2</replaceable>
+subversion-book-<replaceable>4515</replaceable>
+subversion-static-<replaceable>1.8.8_2</replaceable>
+subversion16-<replaceable>1.6.23_4</replaceable>
+subversion17-<replaceable>1.7.16_2</replaceable></screen>
+
+	<para>Package names include the version number and in case of
+	  ports based on python, the version number of the version of
+	  python the package was built with.  Some ports also have
+	  multiple versions available.  In case of
+	  <application>subversion</application> there are different
+	  versions available, as well as different compile options.
+	  In this case, the staticly linked version of
+	  <application>subversion</application>.  When indicating
+	  which package to install, it is best to specify the
+	  application by the port origin, which is the path in the
+	  ports tree.  Repeat the <command>pkg search</command> with
+	  <option>-o</option> to list the origin of each
+	  package:</para>
+
+	<screen>&prompt.root; <userinput>pkg search -o <replaceable>subversion</replaceable></userinput>
+devel/git-subversion
+java/java-subversion
+devel/p5-subversion
+devel/py-hgsubversion
+devel/py-subversion
+devel/ruby-subversion
+devel/subversion16
+devel/subversion17
+devel/subversion
+devel/subversion-book
+devel/subversion-static</screen>
+
+	<para>Searching by shell globs, regular expressions, exact
+	  match, by description, or any other field in the repository
+	  database is also supported by <command>pkg search</command>.
+	  See &man.pkg-search.8; for more details.</para>
+      </listitem>
+
+      <listitem>
 	<para>If the Ports Collection is already installed, there are
 	  several methods to query the local version of the ports
 	  tree.  To find out which category a port is in, type