On Fri, Jan 10, 2014 at 08:05:44AM +0001, Jason McIntyre wrote:
> On Fri, Jan 10, 2014 at 01:01:46AM -0700, Theo de Raadt wrote:
> > > well then this means the description of -c is very poor. i would look
> > > for a fix there, not in SYNOPSIS.
> >
> > But look closer, the synopsis is wrong:
> >
> > sha256 [-bpqrtx] [-c [checklist ...]] [-s string] [file ...]
> >
> > It is not regular. When does checklist ... stop and file ... start?
> >
> > No matter what, that line needs a change. At minimum,
> >
> > sha256 [-bcpqrtx] [-s string] [file ...]
> >
> > With wording changes below.
>
> right, so i support the idea of making a single synopsis as clear as
> possible, and improving the text.
Sorry, that's not always possible.
I think you're completely wrong and pig-headed about that one.
(You probably have a natural bias towards full fledged text, whereas
coder-type people will tend to trust the quick summary that looks like
code, and won't have a problem parsing more information from there.)
The main reason we have several synopsis is that those are actually
related *commands* that happen to share the same *filename*.
When I'm in a hurry, I check the SYNOPSIS.
When I type wrong options, the first thing I see is the SYNOPSIS, not
the manpage.
Oh, hey, let's read the full manpage... hum, lots of text. Oh, hey, let's
check what option goes with what.
One-line synopsis for signify(1):
signify [-neGVI] [-o sigfile] [-p pubkey] [-s seckey] [message]
What's currently in there:
signify -G [-n] -p pubkey -s seckey
signify -I [-o sigfile] [-p pubkey] [-s seckey]
signify -S [-e] [-o sigfile] -s seckey message
signify -V [-e] [-o sigfile] -p pubkey message
Sorry, the current version is *ways* more useful.
In case options are completely separated by some kind of mode, it's
much much clearer to put things as separate SYNOPSIS.
