Update the repo.conf section -- the ``MULTIPLE REPOSITORIES'' concept

is now the standard and only way to configure repositories, so don't
describe it as a special case.

Move chunks of the description of repo.conf items out of the (doubly
indented) definition list, as the text doesn't fit well in the narrow
column available.

Add discussion of how the order of conf files on REPOS_DIR affects
operation and add examples to match.  Add description of how to
bootstrap pkg(8) from a private repository.

Fixes #842

docs/pkg.conf.5

@@ -15,7 +15,7 @@
 .\"     @(#)pkg.1
 .\" $FreeBSD$
 .\"
-.Dd May 27, 2014
+.Dd June 29, 2014
 .Dt PKG.CONF 5
 .Os
 .Sh NAME
@@ -267,11 +267,15 @@ vulnerability database from.
 Default:
 .Pa http://www.vuxml.org/freebsd/vuln.xml.bz2 .
 .El
-.Sh MULTIPLE REPOSITORIES
-To use multiple repositories, specify the primary repository as shown above.
-Further repositores can be configured using repository files.
+.Sh REPOSITORY CONFIGURATION
+To use a repository you will need at least one repository
+configuration file.
 .Pp
-Repository files reside in
+Repository configuration files are searched for in order of the
+directories listed in the
+.Cm REPOS_DIR
+array,
+which defaults to
 .Pa /etc/pkg/
 and
 .Pa /usr/local/etc/pkg/repos/ .
@@ -281,8 +285,7 @@ Filenames are arbitrary, but should end in
 For example
 .Pa /usr/local/etc/pkg/repos/myrepo.conf .
 .Pp
-A repository file is in UCL format and has the following form (see
-above for the description of most options):
+A repository file is in UCL format and has the following form:
 .Bl -tag -width ".Cm myrepo:"
 .It Cm myrepo:
 .Bl -tag -width ".Cm MIRROR_TYPE: string"
@@ -292,13 +295,27 @@ URL for this repository only.
 The repository will be used only if this option is enabled. (default: YES)
 .It Cm MIRROR_TYPE: string
 MIRROR_TYPE for this repository only. (default: NONE).
-Either
+Any of
 .Dv HTTP
 or
 .Dv SRV
 or
-.Dv NONE
-can be used.
+.Dv NONE .
+.It Cm SIGNATURE_TYPE: string
+Specifies what type of signature this repository uses.
+Can be one of
+.Dv NONE ,
+.Dv PUBKEY or
+.Dv FINGERPRINTS .
+(default: NONE)
+.It Cm PUBKEY: string
+This should be set to a path containing public key for this repository
+only. (default: NONE)
+.It Cm FINGERPRINTS: string
+This should be set to a path containing known signatures for the repository.
+.El
+.El
+.Pp
 For a
 .Cm MIRROR_TYPE
 of
@@ -310,9 +327,10 @@ can be used, including:
 .Dv https:// ,
 .Dv ftp:// ,
 or
-.Dv file://
-plus
-.Dv ssh:// .
+.Dv file:// .
+In addition a
+.Dv ssh://
+URL scheme is also supported.
 Where
 .Sy MIRROR_TYPE
 is
@@ -324,14 +342,9 @@ or
 (etc.) URL scheme.
 Using
 .Dv http://
-URLS implies that the hostname part is a simple hostname according to RFC 2616,
-and is deprecated.
-.It Cm SIGNATURE_TYPE: string
-Specifies what type of signature this repository uses.
-Can be either
-.Dv NONE ,
-.Dv PUBKEY or
-.Dv FINGERPRINTS .
+URLS implies that the hostname part is a simple hostname according to
+RFC 2616, and is no longer accepted.
+.Pp
 When
 .Sy SIGNATURE_TYPE
 is
@@ -356,12 +369,8 @@ This option is for use with an external signing command.
 See
 .Xr pkg-repo 8
 for more discussion on signature types.
-(default: NONE)
-.It Cm PUBKEY: string
-This should be set to a path containing public key for this repository only. (default: NONE)
-.It Cm FINGERPRINTS: string
-This should be set to a path containing known signatures for the repository.
-I.e., if
+.Pp
+If
 .Sy FINGERPRINTS
 is set to
 .Pa /usr/local/etc/pkg/fingerprints/myrepo ,
@@ -375,13 +384,40 @@ Files in those directories should be in the format:
 function: sha256
 fingerprint: sha256_representation_of_the_public_key
 .Ed
-.El
-.El
 .Pp
-Note that
+The repository tag
 .Fa myrepo
-could be any string.
-However no two repositories may share the same name.
+is an arbitrary string.
+Reusing the repository tag will cause those items defined in
+configuration files later on the
+.Sy REPOS_DIR
+search path to overwrite the equivalent settings for the same tag
+earlier on the search path.
+Hence the very common idiom, used to turn off the default
+.Cm FreeBSD
+configuration shipped in
+.Pa /etc/pkg/FreeBSD.conf .
+Rather than editing that file directly, create
+.Pa /usr/local/etc/pkg/repos/FreeBSD.conf
+with this content:
+.Bd -literal -offset indent
+FreeBSD: { enabled: no }
+.Ed
+.Pp
+Repositories are prioritised in the order they are found on the
+.Sy REPOS_DIR
+search path, with individual repository configuration files in the
+same directory processed in alphabetical order.
+Earlier files take precedence, meaning that packages will be downloaded
+from them preferentially where the same package is available from several
+repositories.
+This behaviour may be overridden per-package by adding a 
+.Sy repository
+annotation to the installed package.
+See
+.Xr pkg-repository 8
+for details. 
+.Pp
 It is possible to specify more than one repository per file.
 .Sh ENVIRONMENT
 An environment variable with the same name as the option in the
@@ -420,6 +456,38 @@ alias: {
     nonauto: "query -e '%a == 0' '%n-%v'"
 }
 .Ed
+To bootstrap
+.Xr pkg 8
+using a private repository (Assuming 
+.Os 10.0 or later where
+.Xr pkg 7
+supports the
+.Cm bootstrap
+command.)
+.Bd -literal -offset indent
+# cat > /usr/local/etc/pkg/repos/example.conf <<EOF
+example: {
+    url: http://pkgrepo.example.com/${ABI}
+}
+EOF
+# cat > /usr/local/etc/pkg/repos/FreeBSD.conf <<EOF
+FreeBSD: {
+    enabled: no
+}
+EOF
+# env PACKAGESITE='http://pkgrepo.example.com/${ABI}' \
+    /usr/sbin/pkg bootstrap
+.Ed
+Note that
+.Xr pkg 7
+uses
+.Ev PACKAGESITE
+for the URL to download
+.Xr pkg 8
+from, and subsequently passes it in the environment to
+.Xr pkg-static 8 ,
+which ignores it (possibly with a deprecation warning that should be
+ignored), and reads the configuration files instead.
 .Sh SEE ALSO
 .Xr fetch 3 ,
 .Xr pkg_printf 3 ,