reorg examples to better use actual options.

emphasize -U straight away because people often don't even realize it's
there.

Make more use of default stem so that we don't have to update examples too
often.

Ditch the interactive ftp stuff, there's nobody that actually uses that,
especially since there are almost no ftp mirrors left.

1 files changed, 35 insertions, 41 deletions

diff --git a/usr.sbin/pkg_add/pkg_add.1 b/usr.sbin/pkg_add/pkg_add.1
index c9af794c1a3..d32f8002b28 100644
--- a/usr.sbin/pkg_add/pkg_add.1
+++ b/usr.sbin/pkg_add/pkg_add.1
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: pkg_add.1,v 1.135 2016/05/14 03:41:48 tj Exp $
+.\"	$OpenBSD: pkg_add.1,v 1.136 2016/06/14 13:02:35 espie Exp $
 .\"
 .\" Documentation and design originally from FreeBSD. All the code has
 .\" been rewritten since. We keep the documentation's notice:
@@ -15,12 +15,12 @@
 .\" Jordan K. Hubbard
 .\"
 .\"
-.Dd $Mdocdate: May 14 2016 $
+.Dd $Mdocdate: June 14 2016 $
 .Dt PKG_ADD 1
 .Os
 .Sh NAME
 .Nm pkg_add
-.Nd install software package distributions
+.Nd install or update software packages
 .Sh SYNOPSIS
 .Nm pkg_add
 .Bk -words
@@ -40,7 +40,7 @@ command is used to install packages created
 with the
 .Xr pkg_create 1
 command.
-Selected packages containing pre-compiled applications from the
+Packages containing pre-compiled applications from the
 .Pa /usr/ports
 tree can be found on the
 .Ox
@@ -68,6 +68,11 @@ option
 .Fl u
 .Pc .
 .Pp
+In a hurry, a new package can be installed using
+.Sq Nm Fl U Ar package ,
+which updates dependencies and then installs the new 
+.Ar package .
+.Pp
 Details of packing-list internals are documented in
 .Xr pkg_create 1 .
 .Pp
@@ -130,11 +135,6 @@ Each package name may be specified as a filename (which normally consists of the
 package name itself plus the
 .Dq .tgz
 suffix) or a URL referring to FTP, HTTP, HTTPS, or SCP locations.
-The following examples are valid:
-.Pp
-.Li pkg_add -v http://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/m4-1.4.tgz
-.Li pkg_add -v scp://login@host/usr/ports/packages/sparc/all/tcl-8.4.7.tgz
-.Pp
 If the given package names are not found in the current working directory,
 .Nm
 will search for them in each directory (local or remote) named by the
@@ -170,8 +170,11 @@ options
 .Fl I/i .
 .Pp
 For instance
-.Li pkg_add screen
-is ambiguous as it matches screen-4.02  and screen-4.02-static.
+.Sq Nm Ar screen
+is ambiguous as it matches 
+.Ar screen-4.03p6
+and 
+.Ar screen-4.03p6-shm .
 .Pp
 To avoid ambiguities,
 .Nm
@@ -179,11 +182,28 @@ supports
 .Sq stems with flavors ,
 that is, a stem separated from flavors with a double dash.
 For instance, the previous ambiguity could be resolved by using
-.Li pkg_add screen--
-(matches only the normal flavor)
+.Sq Nm Ar screen--
+(matches only the empty flavor)
 or
-.Li pkg_add screen--static
-(matches only the static flavor).
+.Sq Nm Ar screen--shm
+(matches only the shm flavor).
+.Pp
+All paths recognize special sequences
+.Sq %a ,
+.Sq %c ,
+.Sq %m ,
+.Sq %v
+.Po
+from
+.Xr pkg.conf 5
+.Pc .
+.Pp
+The following examples are valid:
+.Bd -literal -offset indent
+pkg_add -v http://ftp.openbsd.org/%m/rsync--
+pkg_add -v http://ftp.openbsd.org/%m/m4
+pkg_add -v scp://login@host/usr/ports/packages/%a/all/tcl-8.5.18.tgz
+.Ed
 .Pp
 If the environment variable
 .Ev PKG_CACHE
@@ -198,32 +218,6 @@ dependencies with the list of packages left to install, then ask the
 user's opinion in interactive mode,
 then install default packages that satisfy the dependencies.
 .Pp
-Alternatively, it is possible to add packages interactively from within the
-.Xr ftp 1
-client,
-in which case setting
-.Ev PKG_PATH
-correctly will be necessary for any dependency to be found out and retrieved
-the same way.
-For example, the following works:
-.Bd -literal -offset indent
-$ ftp ftp://ftp.openbsd.org/pub/OpenBSD/2.7/packages/i386/
-250 CWD command successful
-ftp> ls m*
-227 Entering Passive Mode (129,128,5,191,164,73)
-150 Opening ASCII mode data connection for m*.
-m4-1.4.tgz
-metamail-2.7.tgz
-mh-6.8.4.tgz
-mm-1.0.12.tgz
-mpeg_lib-1.2.1.tgz
-mpeg_play-2.4.tgz
-mpg123-0.59q.tgz
-mutt-0.95.7i.tgz
-226 Transfer complete.
-ftp> get m4-1.4.tgz "|pkg_add -v -"
-.Ed
-.Pp
 .Sy Warning:
 Since the
 .Nm