On Fri, Jan 10, 2014 at 01:55:23PM +0100, Marc Espie wrote: > 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. >
well you disagree with what i've said. does that make you pig-headed? i don;t really find this comment helpful. > (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.) > i have no trouble parsing SYNOPSIS, believe me. i've edited enough of them. > 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. > that's right > When I type wrong options, the first thing I see is the SYNOPSIS, not > the manpage. > that's right again > 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. > and the text is *way* more useful still. it doesn;t prove your point though. we do what we can with SYNOPSIS, and that's handy. it's why i go to such lengths to try and make sure ours are correct, and that they match the manual page. but that doesn;t mean we should ask it to dance: SYNOPSIS does not have the ability to express all the permutations of a utility and its options, sanely. > In case options are completely separated by some kind of mode, it's > much much clearer to put things as separate SYNOPSIS. > we disagree. jmc
