Find undoc nits#4144
Find undoc nits#4144richsalz wants to merge 7 commits intoopenssl:masterfrom richsalz:find-undoc-nits
Conversation
richsalz
added
branch: master
doc/man1/dgst.pod
Outdated
There was a problem hiding this comment.
I always thought that convention is that square brackets denote something you don't have to provide. So with this in mind doesn't suggested modification mean "you have an option to pass dash alone"? Comment applies in multiple cases.
There was a problem hiding this comment.
On side note, this page is misleading in sense that it lists sha and blake2[bs] as standalone commands. These don't work. It might be appropriate to add a note that those that are provided for backward compatibility and should not be used in new scripts. BTW, it refers to list --digest-commands, which seems to be misleading at least on gost count. I mean if you issue apps/openssl gost apps/openssl it will emit SHA256 hash value...
There was a problem hiding this comment.
As for the side note. One can wonder if it's sustainable approach to "synthesize" commands. Maybe it would be more appropriate to "freeze" to options that are documented and are working, and force users to adhere to dgst -algorithm for all other cases...
There was a problem hiding this comment.
The problem is that the digests/encryption that are available depends on the build options. So I tried to say "any available" most of the time. But I know it's a side note :)
There was a problem hiding this comment.
Synopsis in enc.pod starts with
B<openssl enc -ciphername>
and is silent about that you can simply use ciphers' names to invoke on enc command. Wouldn't it be appropriate to do same even in dgst.pod, start the synopsis with dgst -digestname? I'd say it would...
|
I also wrote manpages for the two commands that were missing. |
Always use -[cipher] and -[digest] for ciphers/digests. Split up multiple flags into a single entry in the synopsis.
doc/man1/s_time.pod
Outdated
There was a problem hiding this comment.
Why not lowercase the CApath and CAfile uses around here too?
There was a problem hiding this comment.
Because, sadly and stupidly, that is what the flags are and now we have to live with it.
apps/openssl.c
Outdated
There was a problem hiding this comment.
I was about to make a change to suppress the initial \n in a new PR. Fortunately, I remember seeing this.
paulidale
left a comment
paulidale
left a comment
There was a problem hiding this comment.
My comment was more a question if something was missed than a suggestion for a change.
doc/man1/dgst.pod
Outdated
There was a problem hiding this comment.
I find "or verify" misleading. dgst does verification, but signatures. As far as plain digests go, it only generates digest.
There was a problem hiding this comment.
Yes, but see the -verify and -prverify flags.
There was a problem hiding this comment.
Yes, but "generate or verify message digests" makes you believe that that you can 'dgst -sha256 file > file.sig' and then verify file.sig. Description paragraph gets it right. Maybe "perform digest operations" would be appropriate?
There was a problem hiding this comment.
that's better; additional commit pushed
doc/man1/dgst.pod
Outdated
There was a problem hiding this comment.
Originally question also was what does [-[digest]] mean? That passing dash alone is meaningful? I mean shouldn't it be at least [-digest]. And by "at least" I mean that I see nothing wrong with original [B<-I<digest>>]...
There was a problem hiding this comment.
Ok. New commit pushed that uses B<-I<cipher>> or digest, for all places that I could find.
doc/man1/enc.pod
Outdated
There was a problem hiding this comment.
Same here, what's -[cipher]?
There was a problem hiding this comment.
Already fixed in the latest commit.
There was a problem hiding this comment.
forgot to push, just did
dot-asm
left a comment
dot-asm
left a comment
There was a problem hiding this comment.
Previous red cross from appveyor is auto-cancel thing.
dot-asm
added
approval: done
Write missing prime.pod and srp.pod Implement -c in find-doc-nits (for command options) Other fixes to some manpages Use B<-I<digest|cipher>> notation Split up multiple flags into a single entry in the synopsis. Add -1 and missing-help to list command. Reviewed-by: Andy Polyakov <[email protected]> (Merged from #4144)
|
Squashed and merged. Thanks for the feedback, Andy, it improved the PR |
3 participants
This is a replacement for #4136.