From ed12a1dabaf928e8620fc26ca426c935e1a8a880 Mon Sep 17 00:00:00 2001
From: Ineiev <ineiev@gnu.org>
Date: Sun, 6 May 2018 05:58:23 +0000
Subject: [PATCH] doc: Update description of displayed trust values.

* doc/trust-values.texi: New file.
* doc/Makefile.am (EXTRA_DIST): Add trust-values.texi.
* doc/gnupg.texi (Trust Values): New chapter.
* doc/gpg.texi (OpenPGP Key Management): Update the description
of how trust values are displayed, replace table with a reference
to Trust Values.
* doc/gpg.texi (GPG Examples): Add @mansect trust values.

--

Signed-off-by: Ineiev <ineiev@gnu.org>
---
 doc/Makefile.am       |  3 ++-
 doc/gnupg.texi        |  6 ++++++
 doc/gpg.texi          | 41 +++++++++----------------------------
 doc/trust-values.texi | 47 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 65 insertions(+), 32 deletions(-)
 create mode 100644 doc/trust-values.texi

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a857c8e6e..d47d83ede 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -49,7 +49,8 @@ EXTRA_DIST = samplekeys.asc mksamplekeys com-certs.pem qualified.txt \
              gnupg-card-architecture.png gnupg-card-architecture.pdf \
              FAQ gnupg7.texi mkdefsinc.c defsincdate \
              opt-homedir.texi see-also-note.texi specify-user-id.texi \
-	     gpgv.texi yat2m.c ChangeLog-2011 whats-new-in-2.1.txt
+	     gpgv.texi yat2m.c ChangeLog-2011 whats-new-in-2.1.txt \
+             trust-values.texi
 
 BUILT_SOURCES = gnupg-module-overview.png gnupg-module-overview.pdf \
                 gnupg-card-architecture.png gnupg-card-architecture.pdf \
diff --git a/doc/gnupg.texi b/doc/gnupg.texi
index 7154fc841..336414870 100644
--- a/doc/gnupg.texi
+++ b/doc/gnupg.texi
@@ -140,6 +140,7 @@ the administration and the architecture.
 * Invoking GPGSM::      Using the S/MIME protocol.
 * Invoking SCDAEMON::   How to handle Smartcards.
 * Specify a User ID::   How to Specify a User Id.
+* Trust Values::        How GnuPG displays trust values.
 
 * Helper Tools::        Description of small helper tools
 * Web Key Service::     Tools for the Web Key Service
@@ -179,6 +180,11 @@ the administration and the architecture.
 @anchor{how-to-specify-a-user-id}
 @include specify-user-id.texi
 
+@node Trust Values
+@chapter Trust Values
+@anchor{trust-values}
+@cindex trust values
+@include trust-values.texi
 
 @include tools.texi
 @include wks.texi
diff --git a/doc/gpg.texi b/doc/gpg.texi
index 2888050a7..805a01fc3 100644
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@@ -1040,38 +1040,13 @@ signing.
 
 @c man:.RS
 The listing shows you the key with its secondary keys and all user
-ids.  The primary user id is indicated by a dot, and selected keys or
-user ids are indicated by an asterisk.  The trust
-value is displayed with the primary key: the first is the assigned owner
-trust and the second is the calculated trust value. Letters are used for
-the values:
+IDs.  The primary user ID is indicated by a dot, and selected keys or
+user IDs are indicated by an asterisk.  The trust
+value is displayed with the primary key: "trust" is the assigned owner
+trust and "validity" is the calculated validity of the key.  Validity
+values are also displayed for all user IDs.
+For possible values of trust, @pxref{trust-values}.
 @c man:.RE
-
-@table @asis
-
-  @item -
-  No ownertrust assigned / not yet calculated.
-
-  @item e
-  Trust
-  calculation has failed; probably due to an expired key.
-
-  @item q
-  Not enough information for calculation.
-
-  @item n
-  Never trust this key.
-
-  @item m
-  Marginally trusted.
-
-  @item f
-  Fully trusted.
-
-  @item u
-  Ultimately trusted.
-
-@end table
 @c ******** End Edit-key Options **********
 
 @item --sign-key @var{name}
@@ -3798,6 +3773,10 @@ which is equivalent to
 imports only the user ids of a key containing the strings "Alfa"
 or "Alpha" but not the string "test".
 
+@mansect trust values
+@ifset isman
+@include trust-values.texi
+@end ifset
 
 @mansect return value
 @chapheading RETURN VALUE
diff --git a/doc/trust-values.texi b/doc/trust-values.texi
new file mode 100644
index 000000000..634a784fc
--- /dev/null
+++ b/doc/trust-values.texi
@@ -0,0 +1,47 @@
+@c Copyright (C) 2018 Free Software Foundation, Inc.
+@c This is part of the GnuPG manual.
+@c For copying conditions, see the file gnupg.texi.
+
+Trust values are used to indicate ownertrust and validity of keys and
+user IDs.  They are displayed with letters or strings:
+
+@table @asis
+
+  @item -
+  @itemx unknown
+  No ownertrust assigned / not yet calculated.
+
+  @item e
+  @itemx expired
+
+  Trust calculation has failed; probably due to an expired key.
+
+  @item q
+  @itemx undefined, undef
+  Not enough information for calculation.
+
+  @item n
+  @itemx never
+  Never trust this key.
+
+  @item m
+  @itemx marginal
+  Marginally trusted.
+
+  @item f
+  @itemx full
+  Fully trusted.
+
+  @item u
+  @itemx ultimate
+  Ultimately trusted.
+
+  @item r
+  @itemx revoked
+  For validity only: the key or the user ID has been revoked.
+
+  @item ?
+  @itemx err
+  The program encountered an unknown trust value.
+
+@end table