[issue123] gpgconf needs new field with longer help string

[Marcus Brinkmann]

At Thu, 25 Mar 2004 19:06:26 +0000,
David Faure wrote:
> Let's take an example: 
> one of the gpgsm options is 
>  include-certs:16:2:number of certificates to include:2:2:N:1:: 
>  
> It's relatively easy to guess what this option does.... 
> But how will users guess that -1 means 
> "send all certificates in the chain along with a signature or the number of 
> certificates up the chain"? (found by reading gpgsm.h), and -2 apparently means 
> "without the root cert" (not even mentionned in gpgsm.h!). 

For example by reading the documentation?  How to access the
documentation is an interesting issue by itself, I admit that.

> I think this calls for a new field in gpgconf, which would hold a much longer 
> "description" for each option; we could call this field "help" for instance. 

Well, you can add a couple of fields.  name, description, short help,
long help, tooltip help.  But you'd still have to write the content
for all those fields, and that's an issue all by itself.

Furthermore, I don't really see this as a documentation issue, at
least not solely.  The question you are asking (for the user) is
basically: What semantic meaning do certain values have for this
option?  The documentation should explain how the value of the option
is used, but not necessarily the meaning of each specific value, at
least not in case the value is reasonable generic.

To illustrate this, compare this with the ldap keyserver list.  The
list is actually a list of LDAP server strings.  But documenting the
format of a LDAP server string is not going to explain what it is used
for (to lookup which information, for example?).  Both issues are
separate.

Here, it is similar.  Of course you could have a help text that says:
"enter -2 to send all certificates except the root cert", but in my
opinion, that just sucks.  Why should we require the user to enter a
totally unmotivated number like -2 into a GUI?

So, in my opinion, this calls for a new complex type
INCLUDE-CERTS-NUMBER or whatever, with the basic type integer.  GUIs
that want to help their users with the input can then present a way to
enter either a number, or choose "all", or choose "all except root":

 ( )  Send all certificates in the chain.
 ( )  Send all certificates in the chain, except the root cert.
 (X)  Send at most that many certificates:  ______10_

Which ( ) being radio buttons, and the __10_ being a number entry
field (spin button?) which is disabled if another radio field is
selected.

This is exactly what complex types are useful for.  We should not be
shy to use them, even if they only apply to one option for now.  That
could always change.  Clearly, the above radio style selection group
is superior in every aspect to entering -2 in a number field that
supposedly says how many certs should be sent.[2]

> In the GUI the current "description" is used as the visible label
> for checkboxes etc., the "help" would be used as "what's this help",
> used by the user to find out more about the meaning of a particular
> option.

I see how a longer help text can be useful, too.  I don't think it is
a solution to the above problem, as I said above, but it can be
considered in addition.  I think it is a separate issue, though.

Thanks,
Marcus


[2] btw, the corresponding regular expression would be (-2|-1|[0-9]+),
    which is clearly a selection between three alternatives, where two
    are static and one is a non-negative number.  One could embed
    further information into such a regular expression like this:
    (-2{"all except root cert"}|-1{"all certs"}|[0-9]+{"that many certs"})
    but clearly, I am getting fancy here!  Just ignore this annotation ;)