improved and standardised spelling #12320

gustafn · 2020-06-29T19:24:44Z

This is a revised version of the pull requests #12299 where US/UK discrepancies are left out. The changes affect only documentation files (.pod, .pod.in, .md)

CLA: trivial

Checklist

[x ] documentation is added or updated

CLA: trivial

mspncp

Nice work! Just some little corrections.

Personally, I would prefer if you wouldn't change aka to a.k.a. (see inline comment below), but if the others are o.k. with this change, I won't be dogmatic about it.

mspncp · 2020-06-29T20:28:48Z

doc/man1/openssl-pkcs8.pod.in

 pkcs-tng mailing list using triple DES, DES and RC2 with high iteration
 counts, several people confirmed that they could decrypt the private
-keys produced and Therefore it can be assumed that the PKCS#5 v2.0
+keys produced and Therefore, it can be assumed that the PKCS#5 v2.0


Therefore -> therefore

mspncp · 2020-06-29T20:42:51Z

doc/man1/openssl-s_server.pod.in

 =item B<-status>

-Enables certificate status request support (aka OCSP stapling).
+Enables certificate status request support (a.k.a. OCSP stapling).


a.k.a. used to be a normal abbreviation with three dots. However, it seems that since then it has become such a famous abbreviation that the undotted version aka is more famous and modern. Since even Merriam-Webster prefer's the latter, and since it looks less awkward, I would prefer to keep the aka.

https://grammarist.com/acronym/a-k-a-or-aka/

https://www.merriam-webster.com/dictionary/aka

https://writingexplained.org/aka-or-aka

mspncp · 2020-06-29T20:50:35Z

doc/man3/ASN1_STRING_length.pod

 for an IA5String the data will be ASCII, for a BMPString two bytes per
-character in big endian format, and for an UTF8String it will be in UTF8 format.
+character in big endian format, and for a UTF8String it will be in UTF8 format.


Nice catch: it's an IA5String, but a UTF8String, because it depends on how it is pronounced (yu̇-ˈnī-təd), not how it is spelled. :-)

mspncp · 2020-06-29T20:52:30Z

doc/man3/DSA_generate_parameters.pod

 While a candidate for q is tested by Miller-Rabin primality tests,
 B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
-(once for each witness that confirms that the candidate may be prime);
+(once for each withess that confirms that the candidate may be prime);


This is a mistake and needs to be reverted.

mspncp · 2020-06-29T20:52:43Z

doc/man3/DSA_generate_parameters.pod

 While it is tested by the Miller-Rabin primality test,
 B<BN_GENCB_call(cb, 1, i)> is called in the outer loop
-(once for each witness that confirms that the candidate may be prime).
+(once for each withess that confirms that the candidate may be prime).


mspncp · 2020-06-29T21:01:12Z

doc/man3/SSL_set_bio.pod

 If the B<rbio> and B<wbio> parameters are different and the B<wbio> is the
-same as the previously set value and the old B<rbio> and B<wbio> values
-were the same as each other then one reference is consumed for the B<rbio>
+same as the previously set value, and the old B<rbio> and B<wbio> values
+were the same as each other, then one reference is consumed for the B<rbio>


Not sure whether inserting a comma before the and is correct: why did you insert a comma at ...value, and... but not at ...different and...?

If ... are different and the wbio ... set value, and the old ...

The commas were added to improve separation of clauses.... but you are right, given the construction of the other clauses (https://www.openssl.org/docs/manmaster/man3/SSL_set_bio.html), all or none of these should be adjusted. Adjusting would require to check the sources in detail since we do not want to clarify in the wrong direction. Since the function should be avoided, it is probably the best not to touch it at all.

Many thanks for the constructive feedback, will update soon (this night or tomorrow).

mspncp · 2020-06-29T21:05:09Z

doc/man3/SSL_set_bio.pod

 If the B<rbio> and B<wbio> parameters are different and the B<wbio>
 is the same as the
 previously set value and the old B<rbio> and B<wbio> values were different
-to each
-other then one reference is consumed for the B<rbio> and one reference
-is consumed
-for the B<wbio>.
+to each other, then one reference is consumed for the B<rbio> and one 
+reference is consumed for the B<wbio>.


This sentence here is similar, but here you didn't insert any commas before and.

mspncp · 2020-06-29T21:16:51Z

In case you are wondering why the cla-check is still failing: You placed the CLA: trivial tag in the subject line of the commit message

fixed typos and repeated words CLA: trivial

but the CLA bot expects it to be in the body of the commit message, which needs to be separated from the title by an empty line, like this:

Fixed typos and repeated words

CLA: trivial

But don't worry, I can fix that when the commits get merged.

For the records: I agree that it's a (legally) trivial change.

romen · 2020-06-30T07:49:19Z

@mspncp could you also backport the relevant ones to 1.1.1?

Assuming your feedback is addressed, my approval would stand for both master and 1.1.1 (assuming the backport is going to be clean or as trivial as name files changes/dropped changes for missing functions).

romen · 2020-06-30T07:51:09Z

Thanks @gustafn for this contribution, it's always nice to have documentation improvements!

CLA: trivial

gustafn · 2020-07-01T18:32:45Z

All changes are addressed. Should I make a separate pull request for branch "OpenSSL_1_1_1-stable"?

There are many similar spelling inconsistencies in the source code. Is there some interest to reduce these as well, or is the overall opinion that this makes tracking of substantial changes more complex?

mspncp · 2020-07-01T19:54:14Z

All changes are addressed. Should I make a separate pull request for branch "OpenSSL_1_1_1-stable"?

Thanks for the offer. I would suggest that you wait a little bit until this pull request has the required two approvals. After that, I would attempt a simple cherry-pick and if that succeeds without conflicts, no separate pull requests would be necessary. If not, I would ping you and kindly ask you for the separate pull request.

There are many similar spelling inconsistencies in the source code. Is there some interest to reduce these as well, or is the overall opinion that this makes tracking of substantial changes more complex?

Since your changes affect mostly the documentation and not the source code, and since 1.1.1 is an LTS version, I think it's worth doing it.

mspncp

LGTM. If you don't mind i would like to squash the three commits, using your initial commit message (in present tense and with a capital letter at the beginning). Is that ok for you?

Fix typos and repeated words

CLA: trivial

mspncp · 2020-07-01T20:06:03Z

LGTM. If you don't mind i would like to squash the three commits, using your initial commit message (in present tense and with a capital letter at the beginning). Is that ok for you?

If not, feel free to propose your preferred wording.

P.S: I attempted a cherry-pick to OpenSSL_1_1_1-stable, it failed miserably (47 conflicting files).

slontis

LGTM

slontis · 2020-07-02T04:54:24Z

When it touches more than 100 files do you still consider this to be trivial?

mspncp · 2020-07-02T07:03:43Z

Not trivial to do (if you script it), but trivial in a legal sense, because correcting spell errors does not add any copyrightable value IMO. But of course, IANAL.

gustafn · 2020-07-02T09:24:12Z

From my point of view, squashing theses commits is the right thing. I see that present tense is the usual convention in OpenSSL, so please go ahead with this.

Cherry picking a high number of changes can be a pain, several things have changed, so let me know, whether you prefer a separate pull requests for OpenSSL_1_1_1-stable.

Would you prefer spelling changes on source on the master branch or on 1.1.1? Working though the source code files is a larger project, this will take some time.

mspncp · 2020-07-02T20:40:52Z

From my point of view, squashing theses commits is the right thing. I see that present tense is the usual convention in OpenSSL, so please go ahead with this.

Ok, I'll do that. Your pull request has the necessary number of approvals, but the 24h grace period has not expired yet. So I'll squash and merge it tomorrow.

Cherry picking a high number of changes can be a pain, several things have changed, so let me know, whether you prefer a separate pull requests for OpenSSL_1_1_1-stable.

Yes please, go ahead and raise a separate pull request against OpenSSL_1_1_1-stable. When you are ready, just post it's number here in this thread (e.g., See #xxxxx ) to draw my attention to it.

Would you prefer spelling changes on source on the master branch or on 1.1.1? Working though the source code files is a larger project, this will take some time.

We also appreciate spelling corrections in the source code. Corrections in comments are no problem at all, and the same holds for corrections of internal function or variable names in most cases. But of course, misspellings in the public API require special treatment (like deprecation of the old name) for compatibility reasons.

openssl-machine · 2020-07-03T05:00:12Z

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.

gustafn · 2020-07-04T20:10:25Z

The backport of this pull request for OpenSSL_1_1_1-stable is now on Github:
#12370

CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from #12320)

mspncp · 2020-07-04T23:52:30Z

Merged to master in 8c1cbc7. Thank you @gustafn!

gustafn added 2 commits June 29, 2020 21:13

fixed typos and repeated words

ac6ca4d

CLA: trivial

improved and standardised spelling

773d8b5

CLA: trivial

openssl-machine added the hold: cla required The contributor needs to submit a license agreement label Jun 29, 2020

mspncp suggested changes Jun 29, 2020

View reviewed changes

mspncp added cla: trivial One of the commits is marked as 'CLA: trivial' and removed hold: cla required The contributor needs to submit a license agreement labels Jun 29, 2020

mspncp self-assigned this Jun 29, 2020

romen added branch: 1.1.1 Applies to OpenSSL_1_1_1-stable branch (EOL) branch: master Applies to master branch labels Jun 30, 2020

revised version for pull request

fae7a5e

CLA: trivial

mspncp approved these changes Jul 1, 2020

View reviewed changes

slontis approved these changes Jul 2, 2020

View reviewed changes

slontis added the approval: done This pull request has the required number of approvals label Jul 2, 2020

gustafn mentioned this pull request Jul 4, 2020

Fix typos and repeated words #12370

Closed

openssl-machine pushed a commit that referenced this pull request Jul 4, 2020

Fix typos and repeated words

8c1cbc7

CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from #12320)

mspncp closed this Jul 4, 2020

gustafn mentioned this pull request Jul 24, 2020

Fix typos, repeated words, align spelling to LDP #12527

Closed

1 task

Uh oh!

improved and standardised spelling #12320

improved and standardised spelling #12320

Uh oh!

Conversation

gustafn commented Jun 29, 2020

Checklist

Uh oh!

mspncp left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mspncp commented Jun 29, 2020

Uh oh!

romen commented Jun 30, 2020

Uh oh!

romen commented Jun 30, 2020

Uh oh!

gustafn commented Jul 1, 2020

Uh oh!

mspncp commented Jul 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mspncp left a comment

Choose a reason for hiding this comment

Uh oh!

mspncp commented Jul 1, 2020

Uh oh!

slontis left a comment

Choose a reason for hiding this comment

Uh oh!

slontis commented Jul 2, 2020

Uh oh!

mspncp commented Jul 2, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gustafn commented Jul 2, 2020

Uh oh!

mspncp commented Jul 2, 2020

Uh oh!

openssl-machine commented Jul 3, 2020

Uh oh!

gustafn commented Jul 4, 2020

Uh oh!

mspncp commented Jul 4, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mspncp commented Jul 1, 2020 •

edited

Loading

mspncp commented Jul 2, 2020 •

edited

Loading