Conversation
levitte
added
branch: master
|
@richsalz, feel free to give me hell 😉 |
levitte
force-pushed
the
fix-man1-20191001
branch
from
bf79867 to
f9ff097
Compare
richsalz
left a comment
richsalz
left a comment
There was a problem hiding this comment.
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.
levitte
force-pushed
the
fix-man1-20191001
branch
from
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) |
levitte
force-pushed
the
fix-man1-20191001
branch
from
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. |
t8m
left a comment
t8m
left a comment
There was a problem hiding this comment.
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.
t8m
added
the
approval: done
Reviewed-by: Tomas Mraz <[email protected]> (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 <[email protected]>
(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 <[email protected]> (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 <[email protected]>
(Merged from #10065)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10065)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10065)
Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10065)
"gost" was called "ccgost". "rsax" was treated like literal input rather than an engine name. Reviewed-by: Tomas Mraz <[email protected]> (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 <[email protected]>
(Merged from #10065)
Make replacables italic, change '-rand' to '-r', fix links. Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10065)
Normalise on L<openssl-cmd(1)> over L<cmd(1)> Reviewed-by: Tomas Mraz <[email protected]> (Merged from #10065)
It's a separate script, not an openssl sub-command Reviewed-by: Tomas Mraz <[email protected]> (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. |
levitte
removed
the
issue: documentation
4 participants
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
-randargument) 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)