From nobody@FreeBSD.org  Fri Mar  7 15:41:13 2014
Return-Path: <nobody@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1])
	(using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by hub.freebsd.org (Postfix) with ESMTPS id 8AAE76F6
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  7 Mar 2014 15:41:13 +0000 (UTC)
Received: from cgiserv.freebsd.org (cgiserv.freebsd.org [IPv6:2001:1900:2254:206a::50:4])
	(using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
	(No client certificate requested)
	by mx1.freebsd.org (Postfix) with ESMTPS id 770B2D6C
	for <freebsd-gnats-submit@FreeBSD.org>; Fri,  7 Mar 2014 15:41:13 +0000 (UTC)
Received: from cgiserv.freebsd.org ([127.0.1.6])
	by cgiserv.freebsd.org (8.14.8/8.14.8) with ESMTP id s27FfD9n076055
	for <freebsd-gnats-submit@FreeBSD.org>; Fri, 7 Mar 2014 15:41:13 GMT
	(envelope-from nobody@cgiserv.freebsd.org)
Received: (from nobody@localhost)
	by cgiserv.freebsd.org (8.14.8/8.14.8/Submit) id s27FfD6D076048;
	Fri, 7 Mar 2014 15:41:13 GMT
	(envelope-from nobody)
Message-Id: <201403071541.s27FfD6D076048@cgiserv.freebsd.org>
Date: Fri, 7 Mar 2014 15:41:13 GMT
From: Allan Jude <freebsd@allanjude.com>
To: freebsd-gnats-submit@FreeBSD.org
Subject: handbook section on ports does not mention pkg search
X-Send-Pr-Version: www-3.1
X-GNATS-Notify:

>Number:         187351
>Category:       docs
>Synopsis:       handbook section on ports does not mention pkg search
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bcr
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Mar 07 15:50:00 UTC 2014
>Closed-Date:    Sun May 04 20:01:27 UTC 2014
>Last-Modified:  Sun May 04 20:01:27 UTC 2014
>Originator:     Allan Jude
>Release:        9.2-RELEASE
>Organization:
ScaleEngine Inc.
>Environment:
FreeBSD Trooper.HML3.ScaleEngine.net 9.2-RELEASE FreeBSD 9.2-RELEASE #0 r255898: Thu Sep 26 22:50:31 UTC 2013     root@bake.isc.freebsd.org:/usr/obj/usr/src/sys/GENERIC  amd64

>Description:
The handbook section "5.3. Finding Software" does not mention 'pkg search' as a way to find software. Even for searching the ports tree, this can be useful, but it is especially useful when searching for a package
>How-To-Repeat:

>Fix:
Patch attached

Patch attached with submission follows:

Index: ports/chapter.xml
===================================================================
--- ports/chapter.xml	(revision 44112)
+++ ports/chapter.xml	(working copy)
@@ -197,9 +197,11 @@
       <para>Before installing any application, check <uri
 	  xlink:href="http://vuxml.freebsd.org/">http://vuxml.freebsd.org/</uri>
 	for security issues related to the application or install
-	<package>ports-mgmt/portaudit</package>. Once installed, type
+	<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
@@ -246,6 +248,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-1.8.5.2
+java-subversion-1.8.5
+p5-subversion-1.8.5
+py27-hgsubversion-1.5.1
+py27-subversion-1.8.5
+ruby-subversion-1.8.5
+subversion-1.6.23_2
+subversion-1.7.14
+subversion-1.8.5
+subversion-book-4515
+subversion-static-1.8.5</screen>
+
+	<para>Package names include the version number and in the
+	  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 the 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, 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><command>pkg search</command> also supports searching
+	  using shell globs, regular expressions, exact match,
+	  search by description, or any other field in the
+	  repository database.  See &man.pkg-search.8;</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


>Release-Note:
>Audit-Trail:
Responsible-Changed-From-To: freebsd-doc->	 bcr  
Responsible-Changed-By: bcr 
Responsible-Changed-When: Sun May 4 19:35:14 UTC 2014 
Responsible-Changed-Why:  
I intent to tackle this PR... 

http://www.freebsd.org/cgi/query-pr.cgi?pr=187351 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/187351: commit references a PR
Date: Sun,  4 May 2014 19:59:42 +0000 (UTC)

 Author: bcr
 Date: Sun May  4 19:59:38 2014
 New Revision: 44756
 URL: http://svnweb.freebsd.org/changeset/doc/44756
 
 Log:
   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
 
 Modified:
   head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
 
 Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
 ==============================================================================
 --- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Sun May  4 19:29:54 2014	(r44755)
 +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Sun May  4 19:59:38 2014	(r44756)
 @@ -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
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: bcr 
State-Changed-When: Sun May 4 20:00:21 UTC 2014 
State-Changed-Why:  
A modified version of the patch was just committed. Good work, Allan! 
Thanks for filing the PR, which is hereby closed. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=187351 
>Unformatted:
