On Fri, Jan 10, 2014 at 12:54:20AM -0700, Theo de Raadt wrote: > > On Fri, Jan 10, 2014 at 12:13:45AM -0500, Ted Unangst wrote: > > > The synopsis for -c is dreadfully confusing. it's a mode, not an > > > option. as such, all the other stuff isn't available. > > > > > > > i see it's already done, so i'm late to the party. but i'll add my > > thoughts anyway. > > > > i dislike this. i dislike splitting SYNOPSIS up. it is not SYNOPSIS' job > > to tell you how to to use a utility. it is the text in the man page that > > is meant to do that. > > > > what's the problem? why, take a gander over to ssh-keygen(1) and see the > > way our pages are headed. see? yuck. and it's not just that - the syntax > > is simply not good enough to allow us to describe every permutation. > > you're just rewriting a lie. SYNOPSIS always lies. i don;t see why folks > > have such a hard time accepting this. > > > > so the problem is your method does appear, on the surface, clearer for > > simple usage cases. but when the utility gets more complex, it gets very > > ugly. so then we're left with some pages do it one way, others do it > > another way. and extra verbosity. > > > > i hate it. > > Well, three of us got fooled by it in one day. > > try this: > > sha -c SHA256 * > > What does it do? It does something very unexpected. > > Another option we can go to is: > > md5 [-bprtxc] [-h hashfile] [-s string] [file ...] > > Because -c DOES NOT TAKE A LIST OF FILES! > > 'c' is just a mode change, and then the file list at the end > means something entirely different. > > From the code: > > optstr = "bch:pqrs:tx"; > > See? It is c, not c:
well then this means the description of -c is very poor. i would look for a fix there, not in SYNOPSIS. jmc
