pacman-key: Improve documentation for --populate

Signed-off-by: Allan McRae <allan@archlinux.org>

1 files changed, 15 insertions, 4 deletions

diff --git a/doc/pacman-key.8.txt b/doc/pacman-key.8.txt
index f61c2eca..ff8d38df 100644
--- a/doc/pacman-key.8.txt
+++ b/doc/pacman-key.8.txt
@@ -82,10 +82,8 @@ Options
 
 *\--populate* [<keyring(s)>]::
 	Reload the default keys from the (optionally provided) keyrings in
-	+{pkgdatadir}/keyrings+. Each keyring is provided in a file foo.gpg that
-	contains the keys for the foo keyring. Optionally the file foo-revoked
-	contains a list of revoked key IDs for that keyring. These files are
-	required to be signed (detached) by a trusted PGP key.
+	+{pkgdatadir}/keyrings+. For more information, see
+	<<SC,Providing a Keyring for Import>> below.
 
 *-u, \--updatedb*::
 	Equivalent to \--check-trustdb in GnuPG.
@@ -97,6 +95,19 @@ Options
 	Displays the program version.
 
 
+Providing a Keyring for Import
+------------------------------
+A distribution or other repository provided may want to provide a set of valid
+PGP keys used in the signing of its packages and repository databases that can
+be readily imported into the pacman keyring.  This is achieved by providing a
+PGP keyring file `foo.gpg` that contains the keys for the foo keyring in the
+directory +{pkgdatadir}/keyrings+.  Optionally the file `foo-revoked` can be
+provided containing a list of revoked key IDs for that keyring. These files are
+required to be signed (detached) by a trusted PGP key that the user must
+manually import to the pacman keyring.  This prevents a potentially malicious
+repository adding keys to the pacman keyring without the users knowledge.
+
+
 See Also
 --------
 linkman:pacman[8], linkman:pacman.conf[5]