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. jmc > Index: md5.1 > =================================================================== > RCS file: /cvs/src/bin/md5/md5.1,v > retrieving revision 1.36 > diff -u -p -r1.36 md5.1 > --- md5.1 8 Jan 2014 16:12:44 -0000 1.36 > +++ md5.1 10 Jan 2014 05:08:51 -0000 > @@ -26,11 +26,13 @@ > .Nd calculate a message digest (checksum) for a file > .Sh SYNOPSIS > .Nm md5 > -.Op Fl bpqrtx > -.Op Fl c Op Ar checklist ... > +.Op Fl bprtx > .Op Fl h Ar hashfile > .Op Fl s Ar string > .Op Ar > +.Nm md5 > +.Op Fl q > +.Fl c Op Ar checklist ... > .Sh DESCRIPTION > .Nm > takes as input a message of arbitrary length and produces > Index: md5.c > =================================================================== > RCS file: /cvs/src/bin/md5/md5.c,v > retrieving revision 1.64 > diff -u -p -r1.64 md5.c > --- md5.c 8 Jan 2014 16:23:21 -0000 1.64 > +++ md5.c 10 Jan 2014 05:12:01 -0000 > @@ -820,8 +820,10 @@ usage(void) > __progname, (int)strlen(__progname), ""); > else > #endif /* !defined(SMALL) */ > - fprintf(stderr, "usage: %s [-bpqrtx] [-c [checklist ...]] " > - "[-h hashfile] [-s string] [file ...]\n", __progname); > + fprintf(stderr, "usage:" > + "\t%s [-bprtx] [-h hashfile] [-s string] [file ...]\n" > + "\t%s [-q] -c [checklist ...]\n", > + __progname, __progname); > > exit(EXIT_FAILURE); > } > Index: sha1.1 > =================================================================== > RCS file: /cvs/src/bin/md5/sha1.1,v > retrieving revision 1.34 > diff -u -p -r1.34 sha1.1 > --- sha1.1 8 Jan 2014 16:12:44 -0000 1.34 > +++ sha1.1 10 Jan 2014 05:09:06 -0000 > @@ -26,11 +26,13 @@ > .Nd calculate a message digest (checksum) for a file > .Sh SYNOPSIS > .Nm sha1 > -.Op Fl bpqrtx > -.Op Fl c Op Ar checklist ... > +.Op Fl bprtx > .Op Fl h Ar hashfile > .Op Fl s Ar string > .Op Ar > +.Nm sha1 > +.Op Fl q > +.Fl c Op Ar checklist ... > .Sh DESCRIPTION > .Nm > takes as input a message of arbitrary length and produces > Index: sha256.1 > =================================================================== > RCS file: /cvs/src/bin/md5/sha256.1,v > retrieving revision 1.9 > diff -u -p -r1.9 sha256.1 > --- sha256.1 8 Jan 2014 16:12:44 -0000 1.9 > +++ sha256.1 10 Jan 2014 05:09:47 -0000 > @@ -27,17 +27,21 @@ > .Nd calculate a message digest (checksum) for a file > .Sh SYNOPSIS > .Nm sha256 > -.Op Fl bpqrtx > -.Op Fl c Op Ar checklist ... > +.Op Fl bprtx > .Op Fl h Ar hashfile > .Op Fl s Ar string > .Op Ar > +.Nm sha256 > +.Op Fl q > +.Fl c Op Ar checklist ... > .Nm sha512 > -.Op Fl bpqrtx > -.Op Fl c Op Ar checklist ... > +.Op Fl bprtx > .Op Fl h Ar hashfile > .Op Fl s Ar string > .Op Ar > +.Nm sha512 > +.Op Fl q > +.Fl c Op Ar checklist ... > .Sh DESCRIPTION > .Nm > takes as input a message of arbitrary length and produces > >
