initial documentation for pkg.conf, after nits from jmc@, and straightening

up by Theo about what should be in there...

2 files changed, 98 insertions, 2 deletions

diff --git a/usr.sbin/pkg_add/Makefile b/usr.sbin/pkg_add/Makefile
index 4577ae74c56..59c2cf6afa7 100644
--- a/usr.sbin/pkg_add/Makefile
+++ b/usr.sbin/pkg_add/Makefile
@@ -1,10 +1,10 @@
-# $OpenBSD: Makefile,v 1.67 2010/06/25 12:03:54 espie Exp $
+# $OpenBSD: Makefile,v 1.68 2010/07/04 18:30:28 espie Exp $
 
 .include <bsd.own.mk>
 
 MAN1=pkg_add.1 pkg_info.1 pkg_create.1 pkg_delete.1 pkg_merge.1 \
 	pkg.1 pkg_mklocatedb.1
-MAN5=package.5
+MAN5=package.5 pkg.conf.5
 MAN8=pkg_check.8
 MAN=${MAN1} ${MAN5} ${MAN8}
 NOPROG=
diff --git a/usr.sbin/pkg_add/pkg.conf.5 b/usr.sbin/pkg_add/pkg.conf.5
new file mode 100644
index 00000000000..efebaf6822a
--- /dev/null
+++ b/usr.sbin/pkg_add/pkg.conf.5
@@ -0,0 +1,96 @@
+.\"	$OpenBSD: pkg.conf.5,v 1.1 2010/07/04 18:30:28 espie Exp $
+.\"
+.\" Copyright (c) 2010 Marc Espie
+.\"
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
+.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: July 4 2010 $
+.Dt PKG.CONF 5
+.Os
+.Sh NAME
+.Nm pkg.conf
+.Nd system-wide package system configuration
+.Sh DESCRIPTION
+The file 
+.Pa /etc/pkg.conf
+contains system-wide options related to package handling, as a list of
+.Sq keyword=value 
+lines.
+.Pp
+In particular, the base system
+.Dq installation-and-update
+shell scripts record the URL used for the installation as
+.Ar installpath .
+.Xr pkg_add 1
+can then add or replace packages from the same location straight after 
+the install.
+.Pp
+Currently defined options are as follows:
+.Pp
+.Bl -tag -width fullkeyword -compact
+.It Ar installpath
+URL to package repository updated during installation.
+Used for accessing packages if the environment variable
+.Ev PKG_PATH
+is not defined and no further options are defined.
+.It Ar nochecksum
+Set to 
+.Ar yes
+to waive MD5 checksums during package deletions.
+.It Ar ntogo
+Set to 
+.Ar yes
+to display (done/total) number of package messages.
+.El
+.Pp
+Each option uses a separate line, and follows the following template:
+.Bd -literal -offset indent
+keyword = value
+.Ed
+.Pp
+A list of values can also be specified over several lines using the variation:
+.Bd -literal -offset indent
+keyword += value
+keyword += value
+\&...
+.Ed
+.Pp
+Keywords are case-insensitive.
+.Pp
+Blank lines and comment lines (introduced by a #) are ignored.
+.Pp
+Unknown keywords are ignored.
+.Pp
+.Sh FILES
+.Pa /etc/pkg.conf
+.Sh SEE ALSO
+.Xr pkg_add 1 ,
+.Xr pkg_create 1 ,
+.Xr pkg_delete 1 ,
+.Xr pkg_info 1 ,
+.Xr pkg_check 8
+.Sh HISTORY
+The
+.Nm
+mechanism and format first appeared in
+.Ox 4.8 .