Revise some NOTES and README files#14042
Conversation
paulidale
left a comment
There was a problem hiding this comment.
One wording suggestion. It was preexisting, so not critical.
Some of the notes and readme files have been converted to markdown
format recently and renamed during this process. While adding the
.md extension was a natural step, switching to mixed cases was not
a change to the better, it gives them a ragged appearance:
NOTES.ANDROID => NOTES-Android.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-Perl.md
NOTES.UNIX => NOTES-Unix.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-Valgrind.md
NOTES.WIN => NOTES-Windows.txt
README.ENGINE => README-Engine.md
README.FIPS => README-FIPS.md
Moreover, the NOTES-Windows.txt file is the only file which has been
converted to markdown but has received a .txt file extension.
This doesn't make sense, because the OpenSSL users on Windows will
need to read the other markdown documents as well. Since they are
developers, we can trust them to be able to associate their favorite
editor with the .md extension.
In fact, having a comment at the beginning of the file saying that it
is in markdown format but we didn't dare to add the correct extension
in order not to overwhelm our Windows users can be interpreted either
as unintentionally funny or disrespectful ;-)
This commit suggests the following more consistent renaming:
NOTES.ANDROID => NOTES-ANDROID.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-PERL.md
NOTES.UNIX => NOTES-UNIX.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-VALGRIND.md
NOTES.WIN => NOTES-WINDOWS.md
README.ENGINE => README-ENGINES.md
README.FIPS => README-FIPS.md
(note the plural in README-ENGINES, anticipating a README-PROVIDERS)
Formatting is still very mixed in the NOTES and README files. This commit tries to make formatting more consistent with the one introduced in pull request openssl#10545.
In many locations, the files have been converted to markdown syntactically, but don't utilize the power of markdown yet. Here, instead of just repeating the file name, the markdown link now shows the title of the document. Additionally, the notes are now reference in the same order in both the README and the INSTALL file.
The current content of this README file are just meant to be a starting point and an incentive to add more. Most of the text was borrowed from the [OpenSSL 3.0 Wiki], which is the reason why a added Matt as co-author. To be continued... [OpenSSL 3.0 Wiki]: https://wiki.openssl.org/index.php/OpenSSL_3.0 Co-authored-by: Matt Caswell <[email protected]>
c321b8e to
49a790e
Compare
|
This PR has been heavily revised. Please re-review. |
|
@mattcaswell you might be interested in commit 49a790e4cf87. |
I'm not decided yet how detailed the README-ENGINES should be. At least, there should be some basic introduction to the subject, giving the user as a starting point. I.e., it should point to the relevant entry points of the manual pages, and could optionally link to the wiki for additional and more current resources. |
|
|
||
| In some cases there may be minor behavioural differences between algorithm | ||
| implementations in this provider compared to the equivalent algorithm in the | ||
| default provider. This is typically in order to conform to FIPS standards. |
There was a problem hiding this comment.
typically seems wrong here. The differences are always to conform to the standards.
|
|
||
| It is also possible to load providers programmatically. For example you can | ||
| load the legacy provider into the default library context as shown below. | ||
| Note that once you have explicitly loaded a provider into the library context |
There was a problem hiding this comment.
I'd use loaded a provider into a library context
CLA: trivial (cherry picked from commit fb97b8e)
|
Editorial Note: I noticed that I should rename |
|
24 hours has passed since 'approval: done' was set, but as this PR has been updated in that time the label 'approval: ready to merge' is not being automatically set. Please review the updates and set the label manually. |
Some of the notes and readme files have been converted to markdown
format recently and renamed during this process. While adding the
.md extension was a natural step, switching to mixed cases was not
a change to the better, it gives them a ragged appearance:
NOTES.ANDROID => NOTES-Android.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-Perl.md
NOTES.UNIX => NOTES-Unix.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-Valgrind.md
NOTES.WIN => NOTES-Windows.txt
README.ENGINE => README-Engine.md
README.FIPS => README-FIPS.md
Moreover, the NOTES-Windows.txt file is the only file which has been
converted to markdown but has received a .txt file extension.
This doesn't make sense, because the OpenSSL users on Windows will
need to read the other markdown documents as well. Since they are
developers, we can trust them to be able to associate their favorite
editor with the .md extension.
In fact, having a comment at the beginning of the file saying that it
is in markdown format but we didn't dare to add the correct extension
in order not to overwhelm our Windows users can be interpreted either
as unintentionally funny or disrespectful ;-)
This commit suggests the following more consistent renaming:
NOTES.ANDROID => NOTES-ANDROID.md
NOTES.DJGPP => NOTES-DJGPP.md
NOTES.PERL => NOTES-PERL.md
NOTES.UNIX => NOTES-UNIX.md
NOTES.VMS => NOTES-VMS.md
NOTES.VALGRIND => NOTES-VALGRIND.md
NOTES.WIN => NOTES-WINDOWS.md
README.ENGINE => README-ENGINES.md
README.FIPS => README-FIPS.md
(note the plural in README-ENGINES, anticipating a README-PROVIDERS)
Reviewed-by: Paul Dale <[email protected]>
(Merged from #14042)
Formatting is still very mixed in the NOTES and README files. This commit tries to make formatting more consistent with the one introduced in pull request #10545. Reviewed-by: Paul Dale <[email protected]> (Merged from #14042)
In many locations, the files have been converted to markdown syntactically, but don't utilize the power of markdown yet. Here, instead of just repeating the file name, the markdown link now shows the title of the document. Additionally, the notes are now reference in the same order in both the README and the INSTALL file. Reviewed-by: Paul Dale <[email protected]> (Merged from #14042)
Reviewed-by: Paul Dale <[email protected]> (Merged from #14042)
The current content of this README file are just meant to be a starting point and an incentive to add more. Most of the text was borrowed from the [OpenSSL 3.0 Wiki], which is the reason why a added Matt as co-author. To be continued... [OpenSSL 3.0 Wiki]: https://wiki.openssl.org/index.php/OpenSSL_3.0 Co-authored-by: Matt Caswell <[email protected]> Reviewed-by: Paul Dale <[email protected]> (Merged from #14042)
CLA: trivial (cherry picked from commit fb97b8e) Reviewed-by: Paul Dale <[email protected]> Reviewed-by: Matthias St. Pierre <[email protected]> (Merged from #14042)
|
Merged to master, thanks for the review! |
See commit messages.