Bug 26690

petef@databits.net writes:
> >Fix:
> 
> Index: ports.7
> ===================================================================
> RCS file: /home/ncvs/src/share/man/man7/ports.7,v
> retrieving revision 1.21
> diff -u -r1.21 ports.7
> [...]
> @@ -186,6 +188,20 @@
>  This can be used from
>  .Pa /usr/ports
>  to create a browsable web of all ports on your system!
> +.It Ar search
> +Search the INDEX file for the keyword specified by the 

This should be:

Search the
.Pa INDEX
file for the....

> +.Ev KEY

``KEY'' is not an environment variable.  Perhaps you could explain
that the syntax is `make search name=query' and `make search
key=query'.  Ideally it wouldn't be too long.

> +value.  Results include the path to the port, a short comment, and the

Please put a newline instead of two spaces at the end of sentences, e.g.:

value.
Results include the path...

> +build and run depends required.
> +.It Ar index
> +Create /usr/ports/INDEX, used by the
> +.Pa pretty-print-*
> +and
> +.Pa search

This should be:

Create
.Pa /usr/ports/INDEX ,
which is used by the
.Ar pretty-print-*
and
.Ar search
targets.

Other than that (and a few other places you made the same errors) it
looks pretty good.  If you could fix that up I'd appreciate it.

Thanks,

					Dima Dorfman
					dima@unixfreak.org

++ 18/04/01 19:20 -0700 - Dima Dorfman:
| The following reply was made to PR docs/26690; it has been noted by GNATS.
| 

Thanks for your constructive comments, here's another go at it.  The one
thing I was unsure of is when I was giving an example of make search, I
used:

+.Bd -literal -offset indent
+cd /usr/ports && make search name=query
+.Ed
+.Pp

Is that the best way to give an example command?  

Thanks!

--
Pete Fritchman <petef@databits.net>
Databits Network Services, Inc. <http://databits.net>
finger petef@databits.net for PGP key


[ also available http://hex.databits.net/~petef/freebsd/ports.7.diff ]

Index: ports.7
===================================================================
RCS file: /home/ncvs/src/share/man/man7/ports.7,v
retrieving revision 1.21
diff -u -r1.21 ports.7
--- ports.7	2000/12/29 09:18:42	1.21
+++ ports.7	2001/04/21 00:00:46
@@ -92,8 +92,9 @@
 .Ar install ,
 and so on all the way to
 .Ar fetch .
-You will usually only target
-.Ar install .
+Usually, you will only use the
+.Ar install
+target.
 .Bl -tag -width configure
 .It Ar fetch
 Fetch all of the files needed to build this port from the site(s)
@@ -102,7 +103,8 @@
 and
 .Ev MASTER_SITE_OVERRIDE .
 .It Ar checksum
-Verify that the fetched distfile matches the one the port was tested against.
+Verify that the fetched distfile's checksum matches the one the port was
+tested against.
 Defining
 .Ev NO_CHECKSUM
 will skip this step.
@@ -152,7 +154,8 @@
 .It Ar distclean
 Remove the port's distfile(s) and perform the
 .Ar clean
-operation.  The
+target.
+The
 .Sq clean
 portion recurses to dependencies unless
 .Ev NOCLEANDEPENDS
@@ -186,6 +189,36 @@
 This can be used from
 .Pa /usr/ports
 to create a browsable web of all ports on your system!
+.It Ar search
+Search the
+.Pa INDEX
+file for the pattern specified by either the
+.Pa key
+(searches the port name, comment, and depends) or
+.Pa name
+(just searches the port name) make argument.
+For example, one would type 
+.Bd -literal -offset indent
+cd /usr/ports && make search name=query
+.Ed
+.Pp
+to find all ports whose
+name matches
+.Pa query .
+Results include the matching ports' path, comment, maintainer, build depends,
+and run depends.
+.It Ar index
+Create
+.Pa /usr/ports/INDEX ,
+which is used by the
+.Ar pretty-print-*
+and
+.Ar search
+targets.
+While the master INDEX file in the CVS repository is periodically
+updated, running the
+.Pa index
+target will ensure your INDEX file is up to date with your ports tree.
 .El
 .Sh ENVIRONMENT
 You can change all of these.

Pete Fritchman <petef@databits.net> writes:
> +.Bd -literal -offset indent
> +cd /usr/ports && make search name=query
> +.Ed
> +.Pp
> 
> Is that the best way to give an example command?  

This is fine.  For one-line examples like the above, you can also do:

.Pp
.Dl cd /usr/ports && make search name=query
.Pp

to achieve the same thing.

> +.Pa key
> +(searches the port name, comment, and depends) or
> +.Pa name

".Pa" is used to markup pathnames.  `key' and `name' aren't paths.

> +While the master INDEX file in the CVS repository is periodically
> +updated, running the
> +.Pa index

In this context, `index' is a make target (marked up with .Ar), not a path.

Since the problems are very minor, I've went ahead and fixed them and
committed the change to HEAD.  Thanks!

					Dima Dorfman
					dima@unixfreak.org

Comment 4 dd 2001-04-22 01:28:53 UTC

State Changed
From-To: open->analyzed

Committed to -current, thanks!  I'll MFC this in a few days. 

Comment 5 dd 2001-04-22 01:28:53 UTC

Responsible Changed
From-To: freebsd-doc->dd

My MFC reminder.

Comment 6 dd 2001-05-02 03:22:16 UTC

State Changed
From-To: analyzed->closed

MFC'd