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

[Damien Goutte-Gattat]

On 10/28/2015 06:20 PM, Daniel Kahn Gillmor wrote:
> 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.

I agree.


> 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?

Well, at least in the context of the --completes-needed option, 
"complete" means the same thing as "full", as this option has nothing to 
do with ultimately trusted keys. Only one certification from such a key 
is *always* enough to fully validate a UID, independently of the 
--completes-needed value (this is hardcoded).


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

Fine for me.


> 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.

Full ownertrust only (see my remark above).

I do not really like that "if we see certifications"... How about "if it 
is certified" instead?

--completes-needed:

Consider a user ID (and its associated key) to be fully valid if it is 
certified by at least this number of keys that have full ownertrust.

(or: "this number of fully trusted keys")


Damien

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: OpenPGP digital signature
URL: </pipermail/attachments/20151028/a9701dec/attachment.sig>