Re: md5/sha256 -c option
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.
Re: md5/sha256 -c option
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. jmc
Re: md5/sha256 -c option
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.
Re: md5/sha256 -c option
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
Re: md5/sha256 -c option
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. let us give this a little bit a break. This is a new command and not all the permutations are figured out yet. For instance, it is rather unrefined if you pass it extra optind's and on some of the options you can pass incorrect flags which will be ignored. Let's not strange the process before it is finished.
md5/sha256 -c option
The synopsis for -c is dreadfully confusing. it's a mode, not an option. as such, all the other stuff isn't available. 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 - 1.36 +++ md5.1 10 Jan 2014 05:08:51 - @@ -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 - 1.64 +++ md5.c 10 Jan 2014 05:12:01 - @@ -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 - 1.34 +++ sha1.1 10 Jan 2014 05:09:06 - @@ -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.18 Jan 2014 16:12:44 - 1.9 +++ sha256.110 Jan 2014 05:09:47 - @@ -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
Re: md5/sha256 -c option
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 - 1.36 +++ md5.1 10 Jan 2014 05:08:51 - @@ -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 - 1.64 +++ md5.c 10 Jan 2014 05:12:01 - @@ -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.18 Jan 2014 16:12:44 - 1.34 +++ sha1.110 Jan 2014 05:09:06 - @@ -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 - 1.9 +++ sha256.1 10 Jan 2014 05:09:47 - @@ -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
Re: md5/sha256 -c option
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:
