New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
More doc/man1 fixes #10065
More doc/man1 fixes #10065
Conversation
@richsalz, feel free to give me hell 😉 |
bf79867
to
f9ff097
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Whew.
Many of the comments are repeated. We should think about factoring out the engine and rand writerand options to openssl.pod common manpage. probably other flags, too.
2083ac2
to
788001f
Compare
With the find-doc-nits fixes that were recently merged, this should run fine on Travis |
Please also see my comment (wrong link before) #10065 (comment) |
fe857ea
to
8583e7c
Compare
Okie, all comments answered, I hope. As for |
I'll assume good faith and due diligence :) Not planning to re-read this unless you ask me. This is nice, tedious, work. Good job! |
I won't ask anyone to read this PR again, but I do hope that a few of us will take the time to read through the man-pages and fix what needs fixing. It can be done one page at a time, or several, as it pleases each of us. |
(I've worked as proofreader... and quite frankly, I don't like me in that mode, I can be very unkind... so I've avoided doing that with the man-pages) |
I want to start working on missing content and refactoring common flags to a common manpage, and I'd rather start from this base than have either Richard or I go through a gnarly rebase. Can this get approved and merged soon? |
I should rebase it first... |
Ellipses were used to express that the '-rand' value can specify multiple files, like this: B<-rand> I<file...> Because there are conventions around ellipses, this becomes confusing, because '-rand file...' is normally intepreted to mean that '-rand file1 file2 file3' would be processed as three randomness files, which makes no sense. Rather than making things complicated with more elaborate syntax, we change it to: B<-rand> I<files>
… dash Quite a lot of replacables were still bold, and some options were mentioned without a beginning dash.
Almost all OpenSSL commands are in reality 'openssl cmd', so make sure they are refered to like that and not just as the sub-command. Self-references are avoided as much as is possible, and replaced with "this command". In some cases, we even avoid that with a slight rewrite of the sentence or paragrah they were in. However, in the few cases where a self-reference is still admissible, they are done in bold, i.e. openssl-speed.pod references itself like this: B<openssl speed> References to other commands are done as manual links, i.e. CA.pl.pod references 'openssl req' like this: L<openssl-req(1)> Some commands are examples rather than references; we enclose those in C<>. While we are it, we abolish "utility", replacing it with "command", or remove it entirely in some cases.
"gost" was called "ccgost". "rsax" was treated like literal input rather than an engine name.
Better synopsis for 'openssl dgst' and 'openssl enc', correct names for 'openssl rehash' ('c_rehash' is mentioned there too), correct option end marker for 'openssl verify', and finally, refer to sub-commands as sub-commands.
Make replacables italic, change '-rand' to '-r', fix links.
Done |
Unfortunately the find-doc-nits fails after the rebase. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've gone through all the changes and except the few comments I did not find anything that would be a regression. There of course might be other formatting issues.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good work!
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Ellipses were used to express that the '-rand' value can specify multiple files, like this: B<-rand> I<file...> Because there are conventions around ellipses, this becomes confusing, because '-rand file...' is normally intepreted to mean that '-rand file1 file2 file3' would be processed as three randomness files, which makes no sense. Rather than making things complicated with more elaborate syntax, we change it to: B<-rand> I<files> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
… dash Quite a lot of replacables were still bold, and some options were mentioned without a beginning dash. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Merged. b1c0cc2 Command docs: fix ellipses, the easy cases |
Almost all OpenSSL commands are in reality 'openssl cmd', so make sure they are refered to like that and not just as the sub-command. Self-references are avoided as much as is possible, and replaced with "this command". In some cases, we even avoid that with a slight rewrite of the sentence or paragrah they were in. However, in the few cases where a self-reference is still admissible, they are done in bold, i.e. openssl-speed.pod references itself like this: B<openssl speed> References to other commands are done as manual links, i.e. CA.pl.pod references 'openssl req' like this: L<openssl-req(1)> Some commands are examples rather than references; we enclose those in C<>. While we are it, we abolish "utility", replacing it with "command", or remove it entirely in some cases. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
"gost" was called "ccgost". "rsax" was treated like literal input rather than an engine name. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Better synopsis for 'openssl dgst' and 'openssl enc', correct names for 'openssl rehash' ('c_rehash' is mentioned there too), correct option end marker for 'openssl verify', and finally, refer to sub-commands as sub-commands. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Make replacables italic, change '-rand' to '-r', fix links. Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
Normalise on L<openssl-cmd(1)> over L<cmd(1)> Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
It's a separate script, not an openssl sub-command Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from #10065)
@richsalz, I believe you have some rebasing to do... |
yes. :) Or is that :( working on it, will push updated PR's soon. |
A number of replacables were still bold.
A few literals were not bold(!)
Some options were given without the initial dash
Some ellipses (especially for the
-rand
argument) were confusingThere was a mix of
L<cmd(1)>
andL<openssl-cmd(1)>
referencesSome references to other sections weren't in link form
All file names or parts of file names are now all wrapped with
F<>
More literal input / output is now wrapped with
C<>
A few engine names fixed
Corrected
tsget.pod
(including its file name, which was misrepresenting the command)