From nobody@FreeBSD.org  Wed Jan 23 07:29:26 2002
Return-Path: <nobody@FreeBSD.org>
Received: from freefall.freebsd.org (freefall.FreeBSD.org [216.136.204.21])
	by hub.freebsd.org (Postfix) with ESMTP id 7ABD737B448
	for <freebsd-gnats-submit@FreeBSD.org>; Wed, 23 Jan 2002 07:29:17 -0800 (PST)
Received: (from nobody@localhost)
	by freefall.freebsd.org (8.11.6/8.11.6) id g0NFTHn48988;
	Wed, 23 Jan 2002 07:29:17 -0800 (PST)
	(envelope-from nobody)
Message-Id: <200201231529.g0NFTHn48988@freefall.freebsd.org>
Date: Wed, 23 Jan 2002 07:29:17 -0800 (PST)
From: Marian Cerny <cerny@spnv.sk>
To: freebsd-gnats-submit@FreeBSD.org
Subject: more difficult way of searching for a port's path in handbook section 4.5.2
X-Send-Pr-Version: www-1.0

>Number:         34209
>Category:       docs
>Synopsis:       more difficult way of searching for a port's path in handbook section 4.5.2
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jan 23 07:30:00 PST 2002
>Closed-Date:    Mon Jan 28 11:12:13 PST 2002
>Last-Modified:  Mon Jan 28 11:12:54 PST 2002
>Originator:     Marian Cerny
>Release:        FreeBSD 4.4-RELEASE
>Organization:
private
>Environment:
FreeBSD ivetka 4.4-RELEASE FreeBSD 4.4-RELEASE #0: Tue Sep 18 11:57:08 PDT 2001
    murray@builder.FreeBSD.org:/usr/src/sys/compile/GENERIC  i386
>Description:
In handbook, section 4.5.2 - 4.5.2 Installing Ports:

>   Yet another way of finding a particular port is by using the ports
>   collection's built-in search mechanism. To use the search feature, you
>   will need to be in the /usr/ports directory. Once in that directory,
>   run make search key=program-name where ``program-name'' is the name of
                    ^^^
>   the program you want to find. For example, if you were looking for
>   lsof:
>    # cd /usr/ports
>    # make search key=lsof
                   ^^^
>    Port:   lsof-4.56.4
>    Path:   /usr/ports/sysutils/lsof
>    Info:   Lists information about open files (similar to fstat(1))
>    Maint:  obrien@FreeBSD.org
>    Index:  sysutils
>    B-deps:
>    R-deps:
>   The part of the output you want to pay particular attention to is the
>   ``Path:'' line, since that tells you where to find it. The other
>   information provided is not needed in order to install the port
>   directly, so it will not be covered here.

This works fine, but "make search key=lsof" finds 7 matching
ports on my machine and some of them do not even include the
string "lsof" in the information shown (because it also looks
into port description, etc.).
For example "Port:   xwpe-1.5.22a" is listed, because of the line
"WWW: http://www.identicalsoftware.com/xwpe/" in pkg-descr.
                         ^^^^

Better way (IMHO) is to do "make search name=lsof". This gives
                                        ^^^^
only one match.
>How-To-Repeat:
Have a look at the handbook, section 4.5.2.
>Fix:
I know "search key=" is important as well, so I think both should
have been noticed in the text explaining the difference between
"search name=" and "search key=".
>Release-Note:
>Audit-Trail:

From: Andrew McKay <andy@openirc.co.uk>
To: Marian Cerny <cerny@spnv.sk>
Cc: freebsd-gnats-submit@freebsd.org
Subject: Re: docs/34209: more difficult way of searching for a port's path
 in handbook section 4.5.2
Date: Wed, 23 Jan 2002 22:12:36 +0000 (GMT)

 The following patch attempts to address this issue.  This patch is also
 available from http://www.openirc.co.uk/freebsd/
 
 --- chapter.sgml	Thu Dec 13 13:59:27 2001
 +++ chapter.sgml.new	Wed Jan 23 21:40:57 2002
 @@ -652,13 +652,13 @@
          ports collection's built-in search mechanism.  To use the search
          feature, you will need to be in the
  	<filename>/usr/ports</filename> directory.  Once in that
 -	directory, run <command>make search key=program-name</command>
 +	directory, run <command>make search name=program-name</command>
  	where <quote>program-name</quote> is the name of the program you
  	want to find.  For example, if you were looking for
  	<command>lsof</command>:</para>
 
        <screen>&prompt.root; <userinput>cd /usr/ports</userinput>
 -&prompt.root; <userinput>make search key=lsof</userinput>
 +&prompt.root; <userinput>make search name=lsof</userinput>
  Port:   lsof-4.56.4
  Path:   /usr/ports/sysutils/lsof
  Info:   Lists information about open files (similar to fstat(1))
 @@ -672,6 +672,17 @@
  	find it.  The other information provided is not needed in order
  	to install the port directly, so it will not be covered
  	here.</para>
 +
 +      <para>For more in-depth searching you can also use
 +       <command>make search key=string</command> where
 +       <quote>string</quote> is some text to search for.  This searches
 +       port names, comments, descriptions and dependencies and can be used
 +       to find ports which relate to a particular subject if you don't
 +       know the name of the program you are looking for.</para>
 +
 +      <para>In both of these cases, the search string is case-insensitive.
 +       Searching for <quote>LSOF</quote> will yield the same results as
 +       searching for <quote>lsof</quote>.</para>
 
        <note>
          <para>You must be the <username>root</username> user to install
 
 -- 
 Andrew McKay <andy@openirc.co.uk>
 
State-Changed-From-To: open->closed 
State-Changed-By: chern 
State-Changed-When: Mon Jan 28 11:12:13 PST 2002 
State-Changed-Why:  
Andrew's patch has been applied, fixing this issue.  It will be on 
the website the next time it rebuilds, thanks! 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=34209 
>Unformatted:
