Skip to content

Comments

Revise some NOTES and README files#14042

Closed
mspncp wants to merge 7 commits intoopenssl:masterfrom
mspncp:pr-cleanup-notes-and-readme-md
Closed

Revise some NOTES and README files#14042
mspncp wants to merge 7 commits intoopenssl:masterfrom
mspncp:pr-cleanup-notes-and-readme-md

Conversation

@mspncp
Copy link
Contributor

@mspncp mspncp commented Feb 1, 2021

See commit messages.

Copy link
Contributor

@paulidale paulidale left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One wording suggestion. It was preexisting, so not critical.

@paulidale paulidale added the approval: done This pull request has the required number of approvals label Feb 2, 2021
mspncp and others added 5 commits February 2, 2021 18:46
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]>
@mspncp mspncp force-pushed the pr-cleanup-notes-and-readme-md branch from c321b8e to 49a790e Compare February 2, 2021 18:38
@mspncp mspncp changed the title Cleanup some NOTES-* and README-* files Revise some NOTES and README files Feb 2, 2021
@mspncp
Copy link
Contributor Author

mspncp commented Feb 2, 2021

This PR has been heavily revised. Please re-review.

@mspncp mspncp requested review from levitte and paulidale February 2, 2021 18:40
@mspncp
Copy link
Contributor Author

mspncp commented Feb 2, 2021

@mattcaswell you might be interested in commit 49a790e4cf87.

@mspncp mspncp added approval: review pending This pull request needs review by a committer and removed approval: done This pull request has the required number of approvals labels Feb 2, 2021
@mspncp
Copy link
Contributor Author

mspncp commented Feb 2, 2021

@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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd use loaded a provider into a library context

@mspncp mspncp mentioned this pull request Feb 6, 2021
CLA: trivial

(cherry picked from commit fb97b8e)
@slontis slontis requested a review from paulidale February 11, 2021 01:27
@paulidale paulidale added approval: done This pull request has the required number of approvals and removed approval: review pending This pull request needs review by a committer labels Feb 11, 2021
@mspncp
Copy link
Contributor Author

mspncp commented Feb 11, 2021

Editorial Note: I noticed that I should rename NOTES.WIN to NOTES-WINDOWS in the commit message of the cherry-picked commit aeb6ef7, since the file name changed. I'll do that when merging.

@openssl-machine
Copy link
Collaborator

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.

@mspncp mspncp added approval: ready to merge The 24 hour grace period has passed, ready to merge and removed approval: done This pull request has the required number of approvals labels Feb 12, 2021
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
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)
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
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)
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
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)
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
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)
openssl-machine pushed a commit that referenced this pull request Feb 12, 2021
CLA: trivial

(cherry picked from commit fb97b8e)

Reviewed-by: Paul Dale <[email protected]>
Reviewed-by: Matthias St. Pierre <[email protected]>
(Merged from #14042)
@mspncp
Copy link
Contributor Author

mspncp commented Feb 12, 2021

Merged to master, thanks for the review!

  • 70f2364 NOTES-WINDOWS: fix typo
  • a0ca1ee Add a skeleton README-PROVIDERS file
  • d507436 Add deprecation note to the README-ENGINES file
  • 4148581 Unify the markdown links to the NOTES and README files
  • dc589da Reformat some NOTES and README files
  • 9f1fe6a Revise some renamings of NOTES and README files

@mspncp mspncp closed this Feb 12, 2021
@mspncp mspncp deleted the pr-cleanup-notes-and-readme-md branch October 20, 2023 10:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approval: ready to merge The 24 hour grace period has passed, ready to merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants