[PATCH] doc: Clarify --completes-needed and --marginals-needed.

[Daniel Kahn Gillmor]

Hi Damien--

On Wed 2015-10-28 11:09:22 -0400, Damien Goutte-Gattat <dgouttegattat at incenp.org> wrote:
> * doc/gpg.texi: Explain better how --completes-needed and
>   --marginals-needed affect a user ID's validity.
> * doc/DETAILS: Ditto.

thanks for this fix! I think these are both improvements to the existing
documentation.  Now that you've got me looking at it, i'll propose even
more improvements below.  what do you think?

I think the more we can be consistent about calling a
signature-over-identity-plus-key-material a "certification", the better
we'll be able to explain the difference between the C and S usage flags.

Also, we use the term "full" ownertrust elsewhere, but "complete"
ownertrust isn't defined as far as i can tell.  I assume it means
"either full or ultimate ownertrust", but that's not stated anywhere.
Does that need to be improved?

So how about we use "Number of certifications from..." in the DETAILS
lines below?

> diff --git a/doc/DETAILS b/doc/DETAILS
> index 97079b0..06ffd49 100644
> --- a/doc/DETAILS
> +++ b/doc/DETAILS
> @@ -250,10 +250,10 @@ pkd:0:1024:B665B1435F4C2 .... FF26ABB:
>  
>      - Field 4 :: Date trustdb was created in seconds since Epoch.
>      - Field 5 :: Date trustdb will expire in seconds since Epoch.
> -    - Field 6 :: Number of marginally trusted users to introduce a new
> -                 key signer (gpg's option --marginals-needed).
> -    - Field 7 :: Number of completely trusted users to introduce a new
> -                 key signer.  (gpg's option --completes-needed)
> +    - Field 6 :: Number of signatures from marginally trusted keys to
> +                 fully validate a UID.  (gpg's option --marginals-needed)
> +    - FIeld 7 :: Number of signatures from completely trusted keys to
> +                 fully validate a UID.  (gpg's option --completes-needed)
>  
>      - Field 8 :: Maximum depth of a certification chain. (gpg's option
>                   --max-cert-depth)


and more terminology cleanup in the .texi:

> diff --git a/doc/gpg.texi b/doc/gpg.texi
> index 6e62917..cfa2622 100644
> --- a/doc/gpg.texi
> +++ b/doc/gpg.texi
> @@ -1682,13 +1682,13 @@ are available for all keyserver types, some common options are:
>  
>  @item --completes-needed @code{n}
>  @opindex compliant-needed
> -Number of completely trusted users to introduce a new
> -key signer (defaults to 1).
> +Number of signatures emitted by completely trusted keys
> +to hold a user ID as fully valid (defaults to 1).
>  
>  @item --marginals-needed @code{n}
>  @opindex marginals-needed
> -Number of marginally trusted users to introduce a new
> -key signer (defaults to 3)
> +Number of signatures emitted by marginally trusted keys
> +to hold a user ID as fully valid (defaults to 3).
>  
>  @item --tofu-default-policy @code{auto|good|unknown|bad|ask}
>  @opindex tofu-default-policy

I think "emitted" and "hold" are odd words here.  

Also, what if we invert the sentence so that the goal of the sentence
comes first?

That is, what about:

--completes-needed:

Consider a User ID (and its associated key) to be fully valid if we see
certifications by at least this number of keys that have full or
ultimate ownertrust.

--marginals needed:

Consider a User ID (and its associated key) to be fully valid if we see
certifications by at least this number of keys that have marginal
ownertrust.


it's still an awkward way to express the situation.  I wonder if we
could do better if we switched out of text mode and into graphics.  but
that's another project, probably, and we should try to be clear in text
where possible.

      --dkg