>Number:         23063
>Category:       pkg
>Synopsis:       tracking freebsd/openbsd pkg_* documentation
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    pkg-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Sun Oct 05 07:47:00 UTC 2003
>Closed-Date:
>Last-Modified:
>Originator:     william allen simpson
>Release:        1.6ZC
>Organization:
daydreamer
>Environment:
NetBSD dreamer.citi.umich.edu 1.6ZC NetBSD 1.6ZC (GENERIC) #0: Sat Sep 27 02:24:48 EDT 2003  current@dreamer.citi.umich.edu:/usr/obj/sys/arch/i386/compile/GENERIC i386

>Description:
Pending the pkg freeze, I've integrated the fixes for typos, grammer, and added explanations that have been added to openbsd & freebsd.  Since each has changed the macro set somewhat over the years, I kept the netbsd format (it appears to be an older version of freebsd.)

There are no changes in function (that I'm aware of) -- just text.  

Here's today's pkg_add.1 (similar to what I posted to the list recently), I'll try to get the others done soon.
>How-To-Repeat:

>Fix:
--- ../src/usr.sbin/pkg_install/add/pkg_add.1	2003-10-03 11:42:22.000000000 -0400
+++ pkg_add.1	2003-10-05 03:25:27.000000000 -0400
@@ -53,17 +53,45 @@
 .Xr pkg_create 1
 command.
 Packages are prepared collections of pre-built binaries, documentation,
-configurations, installation instructions and/or other files.
+configurations, installation instructions, and/or other files.
+These packages are provided as a convenience for quickly installing software
+that would otherwise need to be built manually.
+.Bd -filled -offset indent
+.Em Note :
+System distribution files, e.g. base.tgz, comp.tgz, etc., are
+.Em not
+packages.
+.Ed
+.Pp
+One or more
+.Ar pkg-name
+arguments may be specified, each being either a file containing the
+package (these usually end with a
+.Dq .tbz ,
+.Dq .tgz ,
+.Dq .tar.gz ,
+or
+.Dq .tar
+suffix) or a
+URL pointing at a file available on an FTP or WWW site.
+Thus, you may extract files directly from their anonymous FTP or WWW
+locations (for example,
+.Nm
+.Li ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.6/i386/shells/bash-2.05nb1.tgz
+or
 .Nm
-can recursively install other packages that the current package
-depends on or requires from both local disk and via FTP or HTTP.
+.Li http://www.example.org/packages/screen-4.0.tbz).
+.Nm
+can recursively install other packages that the current package needs.
 .Sh WARNING
 .Bf -emphasis
 Since the
 .Nm
 command may execute scripts or programs contained within a package file,
-your system may be susceptible to ``Trojan horses'' or other subtle
-attacks from miscreants who create dangerous package files.
+your system may be susceptible to
+.Dq trojan horses
+or other subtle attacks from miscreants who create dangerous packages.
+Be sure the specified package(s) are from trusted sources.
 .Pp
 You are advised to verify the competence and identity of those who
 provide installable package files.
@@ -92,19 +120,24 @@
 .Bl -tag -width indent
 .It Ar pkg-name [ ... ]
 The named packages are installed.
-.Ar pkg-name
-may be either a URL or a local pathname,
-a package name of "-" will cause
+Specifying
+.Ql -
+as a package name causes
 .Nm
 to read from stdin.
-If the packages are not found in the current
-working directory,
+Each
+.Ar pkg-name
+may be a base package name,
+a complete package name with version,
+a local pathname,
+or a fully qualified URL.
+If the given package names are not found in the current working directory,
 .Nm
-will search them in each directory named by the
+will search for them in each location indicated by the
 .Ev PKG_PATH
 environment variable.
 Any dependencies required by the installed package will be searched
-in the same location that the original package was installed from.
+for throughout the same locations where the original package was found.
 .It Fl f
 Force installation to proceed even if prerequisite packages are not
 installed or the requirements script fails.
@@ -113,7 +146,8 @@
 will still try to find and auto-install missing prerequisite packages,
 a failure to find one will not be fatal.
 .It Fl I
-If an installation script exists for a given package, do not execute it.
+When installation scripts exist for a given package,
+do not execute them.
 .It Fl K Ar pkg_dbdir
 Set
 .Ar pkg_dbdir
@@ -148,8 +182,8 @@
 mode, it allows you to make radical changes to the package structure
 before acting on its contents.
 .It Fl n
-Don't actually install a package, just report the steps that
-would be taken if it was.
+Don't actually install a package,
+just report the steps that would be taken.
 .It Fl p Ar prefix
 Set
 .Ar prefix
@@ -163,8 +197,9 @@
 has no way of knowing which directory settings are relative and
 which are absolute.
 It is rare in any case to see more than one directory transition made,
-but when such does happen and you wish to have control over *all* directory
-transitions, then you may then wish to look into the use of
+but when such does happen and you wish to have control over
+.Em all
+directory transitions, then you may wish to look into the use of
 .Cm MASTER
 and
 .Cm SLAVE
@@ -175,7 +210,7 @@
 options).
 .It Fl R
 Do not record the installation of a package.
-This means that you cannot deinstall it later, so only use this option if
+This means that you cannot deinstall it later, so only use this option when
 you know what you are doing!
 .It Fl S
 Run in
@@ -218,16 +253,17 @@
 Use
 .Ar template
 as the input to
-.Xr mktemp 3
-when creating a ``staging area.''
+.Xr mkdtemp 3
+when creating a
+.Dq staging area .
 By default, this is the string
 .Pa /var/tmp/instmp.XXXXXX ,
-but it may be necessary to override it in the situation where
-space in your
-.Pa /var/tmp
-directory is limited.
-Be sure to leave some number of `X' characters for
-.Xr mktemp 3
+but it may be necessary to override this
+(see CAVEATS section).
+Be sure to leave some number of
+.Dq X
+characters for
+.Xr mkdtemp 3
 to fill in with a unique ID.
 .Pp
 You can get a performance boost by setting the staging area
@@ -267,23 +303,12 @@
 environment variable.
 .El
 .Pp
-One or more
-.Ar pkg-name
-arguments may be specified, each being either a file containing the
-package (these usually ending with the ``.tgz'' suffix) or a
-URL pointing at a file available on an ftp or web site.
-Thus you may extract files directly from their anonymous ftp or WWW
-locations (e.g.,
-.Nm
-ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.5/i386/shells/bash-2.04.tgz
-or
-.Nm
-http://www.example.org/packages/screen-4.0.tbz).
-Note:  For ftp transfers, if you wish to use
+Note:  If you wish to use
 .Bf -emphasis
 passive mode
 .Ef
-ftp in such transfers, set the variable
+.Xr ftp 1
+in such transfers, set the variable
 .Bf -emphasis
 FTP_PASSIVE_MODE
 .Ef
@@ -299,40 +324,44 @@
 ftp.
 .Sh TECHNICAL DETAILS
 .Nm
-extracts each package's "packing list"
-into a special staging directory in /var/tmp (or $PKG_TMPDIR if set)
+extracts each package's
+.Dq packing list
+into a special staging directory in
+.Pa /var/tmp
+(or
+.Ev PKG_TMPDIR ,
+see ENVIRONMENT and CAVEATS sections)
 and then runs through the following sequence to fully extract the contents
 of the package:
-.Bl -enum -offset indent
+.Bl -enum
 .It
-A check is made to determine if the package or another version of it
+A check is made to determine whether the package or another version of it
 is already recorded as installed.
 If it is,
-installation is terminated if the
+installation is terminated when the
 .Fl u
-option is not given.
+option is not present.
 .Pp
 If the
 .Fl u
-option is given, it's assumed the package should be replaced by the
-new version instead.  Before doing so, all packages that depend on the
-pkg being upgraded are checked if they also work with the new version.
-If that test is successful, replacing is prepared by moving an existing
+option is specified,
+all other packages that depend upon the package being upgraded are checked
+to determine that they also work with the updated version.
+If that test is successful, any existing
 .Pa +REQUIRED_BY
-file aside (if it exists), and running
+file is saved, and
 .Xr pkg_delete 1
-on the installed package.
-Installation then proceeds as if the package
-was not installed, and restores the
+is run to remove the existing package.
+Installation then proceeds, and the
 .Pa +REQUIRED_BY
-file afterwards.
+file is restored afterwards.
 .It
-A check is made to determine if the package conflicts (from
+If this package conflicts (from
 .Cm @pkgcfl
 directives, see
 .Xr pkg_create 1 )
-with an already recorded as installed package.
-If it is, installation is terminated.
+with a package already recorded as installed,
+installation is terminated.
 .It
 All package dependencies (from
 .Cm @pkgdep
@@ -350,8 +379,7 @@
 The only currently implemented option is
 .Cm @option extract-in-place ,
 which causes the package to be extracted directly into its
-prefix directory rather than moving it through a staging area in
-.Pa /var/tmp .
+prefix directory without moving it through a staging area.
 .It
 If
 .Cm @option extract-in-place
@@ -393,15 +421,16 @@
 .It
 If
 .Cm @option extract-in-place
-is not present in the packing list,
-then it is used as a guide for moving (or copying, as necessary) files from
-the staging area into their final locations.
+is not used, then the packing list
+is used as a guide for moving (or copying, as necessary)
+files from the staging area into their final locations.
 .It
 If the package contains an
 .Ar mtreefile
 file (see
 .Xr pkg_create 1 ) ,
 then mtree is invoked as:
+.Pp
 .Bd -filled -offset indent -compact
 .Cm mtree
 .Fl u
@@ -412,6 +441,7 @@
 .Fl p
 .Pa prefix
 .Ed
+.Pp
 where
 .Pa prefix
 is either the prefix specified with the
@@ -475,7 +505,7 @@
 .Sh ENVIRONMENT
 .Bl -tag -width PKG_TMPDIR
 .It Ev LOCALBASE
-This is the location of the
+The location of the
 .Ar viewbase
 directory in which all the views are managed.
 The default
@@ -491,20 +521,30 @@
 The default package database directory is
 .Pa /var/db/pkg .
 .It Ev PKG_PATH
-The value of the
+If a given package name cannot be found,
+the directories named by
 .Ev PKG_PATH
-is used if a given package can't be found, it's usually set to
-.Pa /usr/pkgsrc/packages/All .
-The environment variable
-should be a series of entries separated by semicolons.
+are searched.
+It should contain a series of entries separated by semicolons.
 Each entry consists of a directory name or URL.
-The current directory may be indicated implicitly by an empty directory
-name, or explicitly by a single period.
+(Note:  other distributions use colon,
+which conflicts with the URL usage.)
+The current directory may be indicated
+implicitly by an empty directory name,
+or explicitly by a single period
+.Pq Ql \&. .
 FTP URLs may not end with a slash.
+It's usually set to
+.Pa /usr/pkgsrc/packages/All .
 .It Ev PKG_TMPDIR
-Staging directory for installing packages, defaults to /var/tmp.
-Set to directory with lots of free disk if you run out of
-space when installing a binary package.
+Temporary area where packages will be extracted, instead of
+.Ev TMPDIR ,
+.Pa /var/tmp ,
+.Pa /tmp ,
+or
+.Pa /usr/tmp ,
+in that order.
+(See CAVEATS section.)
 .It Ev PKG_VIEW
 The default view can be specified in the
 .Ev PKG_VIEW
@@ -536,9 +576,7 @@
 The URL can be put into an environment variable,
 .Ev PKG_PATH .
 .Bd -literal
-# pkg_add -v ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.5/i386/All/mozilla-0.8.1.tgz
-
-# export PKG_PATH=ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.5/i386/All
+# export PKG_PATH=ftp://ftp.NetBSD.org/pub/NetBSD/packages/1.6/i386/All
 # pkg_add -v mozilla
 .Ed
 .Sh SEE ALSO
@@ -546,7 +584,7 @@
 .Xr pkg_create 1 ,
 .Xr pkg_delete 1 ,
 .Xr pkg_info 1 ,
-.Xr mktemp 3 ,
+.Xr mkdtemp 3 ,
 .Xr sysconf 3 ,
 .Xr packages 7 ,
 .Xr mtree 8
@@ -563,6 +601,25 @@
 .It Thomas Klausner
 HTTP support.
 .El
+.Sh CAVEATS
+Package extraction does need a temporary area that
+.Bl -bullet -compact
+.It
+is big enough to hold the complete extracted package,
+.It
+can hold executable scripts.
+.El
+.Pp
+.Nm
+looks through ${PKG_TMPDIR}, ${TMPDIR}, /var/tmp, /tmp, /usr/tmp
+for such an area, in sequence.
+.Pp
+If ${TMPDIR} and /var/tmp are mounted noexec,
+.Ev PKG_TMPDIR
+must be set to a suitable area, as
+.Nm
+has no way to check for noexec status,
+except by failure to run installation scripts.
 .Sh BUGS
 Hard links between files in a distribution are only preserved if either
 (1) the staging area is on the same file system as the target directory of
@@ -570,10 +627,10 @@
 .Cm @cwd
 directives in the contents file,
 .Em and
-and the link names are extracted with a single
-.Cm tar
+the link names are extracted with a single
+.Xr tar 1
 command (not split between
-invocations due to exec argument-space limitations--this depends on the
+invocations due to exec argument-space limitations; this depends on the
 value returned by
 .Fn sysconf _SC_ARG_MAX ) .
 .Pp

>Release-Note:
>Audit-Trail:
>Unformatted: