[129061] trunk/base/doc

Thu Dec 4 12:20:50 PST 2014

Revision: 129061
          https://trac.macports.org/changeset/129061
Author:   cal at macports.org
Date:     2014-12-04 12:20:50 -0800 (Thu, 04 Dec 2014)
Log Message:
-----------
base: generate roff from asciidoc source, enable port-search.1

Modified Paths:
--------------
    trunk/base/doc/Makefile.in

Added Paths:
-----------
    trunk/base/doc/port-search.1

Modified: trunk/base/doc/Makefile.in
===================================================================

--- trunk/base/doc/Makefile.in	2014-12-04 20:20:09 UTC (rev 129060)
+++ trunk/base/doc/Makefile.in	2014-12-04 20:20:50 UTC (rev 129061)
@@ -69,6 +69,7 @@
 		port-reclaim.1 \
 		port-reload.1 \
 		port-rev-upgrade.1 \
+		port-search.1 \
 		port-selfupdate.1 \
 		port-uninstall.1 \
 		port-unload.1 \

Added: trunk/base/doc/port-search.1
===================================================================
--- trunk/base/doc/port-search.1	                        (rev 0)
+++ trunk/base/doc/port-search.1	2014-12-04 20:20:50 UTC (rev 129061)
@@ -0,0 +1,226 @@
+'\" t
+.TH "PORT\-SEARCH" "1" "2014\-12\-04" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+port-search \- Search for a port using keywords
+.SH "SYNOPSIS"
+.sp
+.nf
+\fBport\fR [\fB\-dq\fR] \fBsearch\fR
+     [\-\-case\-sensitive] [\-\-line] [\-\-exact|\-\-glob|\-\-regex] [\-\-\fIfield\fR \&...]
+     \fIkeyword\fR \&...
+.fi
+.SH "DESCRIPTION"
+.sp
+\fBport search\fR helps you find ports by partial matches of the name or description (or other fields, depending on the given options)\&. It is the tool of choice if you are looking for software in MacPorts\&.
+.sp
+\fBsearch\fR works by searching for your given keyword(s) in a set of fields of all available ports\&. By default, a port\(cqs name and short description are searched, as if you had specified both \fB\-\-name\fR and \fB\-\-description\fR\&. See \fBOPTIONS\fR for possible values for \fIfield\fR\&.
+.sp
+Note that you can specify multiple fields to be searched\&. A port will be printed when any of the fields matches your keyword(s)\&. If you specify multiple keywords, \fBsearch\fR will run multiple separate searches, one for each given keyword\&.
+.SH "OPTIONS"
+.SS "Search behavior"
+.PP
+\fB\-\-case\-sensitive\fR
+.RS 4
+Do not ignore case when searching for the given keyword\&.
+.RE
+.PP
+\fB\-\-exact\fR
+.RS 4
+Search for the given string exactly\&. Disables
+\fB\-\-glob\fR
+(the default) and
+\fB\-\-regex\fR\&.
+.RE
+.PP
+\fB\-\-glob\fR
+.RS 4
+Treat the keyword(s) as wildcard (i\&.e\&., expand
+\fI*\fR,
+\fI?\fR
+and
+\fI[sets]\fR)\&. This is the default\&. See the
+\fBstring match\fR
+section of
+\fBstring\fR(n)
+for a detailed syntax description\&.
+.RE
+.PP
+\fB\-\-regex\fR
+.RS 4
+Treat the given string as a Tcl regular expression\&. See
+\fBre_syntax\fR(n)
+for a description of Tcl regular expressions\&.
+.RE
+.SS "Output behavior"
+.PP
+\fB\-\-line\fR
+.RS 4
+Print one match per line, where a line consists of name, version, categories and short description\&.
+.RE
+.sp
+See also \fB\-q\fR in the \fBGLOBAL OPTIONS\fR section below\&.
+.SS "Field selection"
+.PP
+\fB\-\-category\fR, \fB\-\-categories\fR
+.RS 4
+Search the category\&. You can use this to list all ports in a given category\&. For example,
+\fBport search \-\-category haskell\fR
+will print all Haskell ports in MacPorts\&. If you don\(cqt need the description it\(cqs usually faster to use the pseudo\-portname selector
+\fBcategory:haskell\fR
+with
+\fBport-echo\fR(1)
+(i\&.e\&.,
+\fBport echo category:haskell\fR) instead\&. See
+\fBport\fR(1)
+for more information on pseudo\-port selectors\&.
+.RE
+.PP
+\fB\-\-depends\fR, \fB\-\-depends_build\fR, \fB\-\-depends_extract\fR, \fB\-\-depends_fetch\fR, \fB\-\-depends_lib\fR, \fB\-\-depends_run\fR
+.RS 4
+Search for ports that depend on the port given as keyword\&.
+\fB\-\-depends\fR
+is an alias for all other
+\fB\-\-depends_\fR
+options combined\&. Note that only dependencies present in default variants will be found by this search\&. As with
+\fB\-\-category\fR, there also are pseudo\-portname selectors available for dependencies\&.
+.RE
+.PP
+\fB\-\-description\fR, \fB\-\-long_description\fR
+.RS 4
+Test the search string against ports\*(Aq descriptions\&.
+.RE
+.PP
+\fB\-\-homepage\fR
+.RS 4
+Search for the keyword(s) in the homepage property\&.
+.RE
+.PP
+\fB\-\-maintainer\fR
+.RS 4
+Search for ports maintained by a specific maintainer\&. Note that there also is a pseudo\-portname selector available for maintainer addresses\&. See
+\fBport\fR(1)
+for more information\&.
+.RE
+.PP
+\fB\-\-name\fR
+.RS 4
+Search in ports\*(Aq names\&. Since this is the default (together with
+\fB\-\-description\fR), this flag is only useful when you to search
+\fIonly\fR
+in the name, but not the description\&.
+.RE
+.PP
+\fB\-\-portdir\fR
+.RS 4
+Test the search string against the path of the directory that contains the port\&.
+.RE
+.PP
+\fB\-\-variant\fR, \fB\-\-variants\fR
+.RS 4
+Search for variant names\&.
+.RE
+.SH "GLOBAL OPTIONS"
+.sp
+Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
+.PP
+\fB\-q\fR
+.RS 4
+Only print the name of the port that matched your query\&. Print one match per line\&.
+.RE
+.SH "EFFICIENT SEARCHING"
+.sp
+The output of \fBsearch\fR can be overwhelming and confusing, especially with a large number of results\&. Here are a few tips to improve your search efficiency with MacPorts\&.
+.sp
+Suppose you are looking for PHP in MacPorts\&. You might start with
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port search php
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+and notice your query produces a lot of output\&. In fact, at the time of writing this, this search produces 763 matches\&. By default, \fBsearch\fR searches both name and description of a port\&. While we\(cqre looking for PHP, we can reduce the number of hits by using the \fB\-\-name\fR flag\&. Furthermore, we only want ports whose name starts with \(lqphp\(rq, so we add the \fB\-\-glob\fR flag (actually, we could leave it out because it is the default) and modify the search term to \fBphp\fR*\&. Note that the asterisk needs to be escaped or quoted to prevent the shell from interpreting it:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port search \-\-name \-\-glob \*(Aqphp*\*(Aq
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Since that still produces 689 results, we can activate compressed output using the \fB\-\-line\fR flag
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port search \-\-line \-\-name \-\-glob \*(Aqphp*\*(Aq
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Scrolling over the output, we see a large number of PHP modules starting with php<version>\-<modulename>\&. That tells us the main PHP ports might be named php<version>\&. Using regex we can further narrow down the results:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port search \-\-line \-\-name \-\-regex \*(Aq^php\ed+$\*(Aq
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+Note it is not always necessary to drill down to reduce the amount of output\&. For example, if you\(cqre looking for \fBrrdtool\fR, a popular system to store and graph time\-series data, the simple approach works well, with only 12 ports being returned:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$> port search rrd
+.fi
+.if n \{\
+.RE
+.\}
+.SH "SEE ALSO"
+.sp
+\fBport\fR(1), \fBstring\fR(n), \fBre_syntax\fR(n), \fBport-install\fR(1)
+.SH "AUTHORS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+(C) 2014 The MacPorts Project
+Clemens Lang <cal at macports\&.org>
+.fi
+.if n \{\
+.RE
+.\}
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/macports-changes/attachments/20141204/1ab0cf5d/attachment-0001.html>
