Skip to content
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

Fix typos and repeated words #12370

Closed

Conversation

@gustafn
Copy link
Contributor

@gustafn gustafn commented Jul 4, 2020

CLA: trivial

This is essentially a backport of pull request #12320 to the OpenSSL_1_1_1-stable branch where also the recommended notation from the Linux man pages (https://man7.org/linux/man-pages/man7/man-pages.7.html) are respected.

Checklist
  • [ x] documentation is added or updated
@mspncp mspncp self-requested a review Jul 4, 2020
@@ -29,7 +29,7 @@ B<u> as the callback parameters.

The error strings will have the following format:

[pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
[pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message]

This comment has been minimized.

@InfoHunter

InfoHunter Jul 13, 2020
Member

I wonder why the word filename should be treated as a whole while others like library name is not...

This comment has been minimized.

@gustafn

gustafn Jul 13, 2020
Author Contributor

This change follows the conventions of the Linux man page project [1], which seem to be as well the preferred rule set in OpenSSL 3 [2]. These conventions state that "file name" should avoided and "filename" should be used instead. "Filename" is in some common dictionaries [3,4], while "libraryname" is not.

[1] https://man7.org/linux/man-pages/man7/man-pages.7.html
[2] https://github.com/openssl/openssl/blob/master/util/find-doc-nits#L552
[3] https://dictionary.cambridge.org/dictionary/english/filename
[4] https://www.macmillandictionary.com/dictionary/british/filename

@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 15, 2020

I'm a little bit confused, because it seems like you made some additional corrections here in #12370, which you didn't make in #12320 (see listing at the end). Some of these replacements seem ok, they preexisted on master (like time stamp -> timestamp), but others, most notably the changes non-blocking -> nonblocking and non-negative -> nonnegative appear to be new. At least, I still see a lot of misspelled instances on master (in the doc directory). Was this intentional or by mistake? If you did it intentionally, you might want to do it on master, too?

A propos: it seems like you made the corrections in the doc directory only, but there are also some misspellings in source code comments. Have you tried to correct those, too? Or did you avoid them in order not to break anything accidentally?

Here is my quick and dirty comparison of your two pull requests:

git show gh-12320 | grep '^[+-]' | grep -v -F -e '+++' -e '---' | sort > changes-12320
git show gh-12370 | grep '^[+-]' | grep -v -F -e '+++' -e '---' | sort > changes-12370
diff changes-12320 changes-12370

(watch out for the green lines, ++ vs. +-)

--- changes-12320	2020-07-15 19:22:39.056029036 +0200
+++ changes-12370	2020-07-15 19:22:46.952046672 +0200
@@ -1,119 +1,199 @@
++0 if their keys are equal, nonzero otherwise.
+-0 if their keys are equal, non-zero otherwise.
+-1 the shared secret is padded with zeroes up to the size of the DH prime B<p>.
++1 the shared secret is padded with zeros up to the size of the DH prime B<p>.
 +acceleration such as AES-NI (the low-level interfaces do not provide the
 -acceleration such as AES-NI (the low level interfaces do not provide the
++account for clock skew the B<maxsec> field can be set to nonzero in
+-account for clock skew the B<maxsec> field can be set to non-zero in
 +a client certificate. Therefore, merely including a client certificate
 +a client certificate. Therefore, merely including a client certificate
 -a client certificate. Therefore merely including a client certificate
 -a client certificate. Therefore merely including a client certificate
++Actually, any nonzero value means that this certificate could have been
+-Actually, any non-zero value means that this certificate could have been
++additionally store the filename and line number where
+-additionally store the file name and line number where
++adds them to the PRNG. If B<max_bytes> is nonnegative,
+-adds them to the PRNG. If B<max_bytes> is non-negative,
 +AES128-SHA based ciphers that have this capability. However, these are for
 -AES128-SHA based ciphers that have this capability. However these are for
-+    'a.k.a.'        => 'aka',
 +aka AVX512IFMA extension;
 -a.k.a. AVX512IFMA extension;
-+  * All of the low-level AES, Blowfish, Camellia, CAST, DES, IDEA, RC2,
--  * All of the low level AES, Blowfish, Camellia, CAST, DES, IDEA, RC2,
-+  * All of the low-level DH, DSA, ECDH, ECDSA and RSA public key functions
--  * All of the low level DH, DSA, ECDH, ECDSA and RSA public key functions
-+  * All of the low-level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224,
--  * All of the low level MD2, MD4, MD5, MDC2, RIPEMD160, SHA1, SHA224,
 +already operational and couldn't be successfully initialised (e.g. lack of
 -already operational and couldn't be successfully initialised (eg. lack of
-+    alternatives should be used instead: pkey, pkeyparam and genpkey.
--    alternatives should be used intead: pkey, pkeyparam and genpkey.
++also have nonblocking behaviour.
+-also have non-blocking behaviour.
 +Although low-level algorithm specific functions exist for many algorithms
 -Although low level algorithm specific functions exist for many algorithms
 +A method contains a few functions that implement the low-level of the
 -A method contains a few functions that implement the low level of the
 +and checked. However, some servers only request client authentication
 -and checked. However some servers only request client authentication
--and issue the following commands to build OpenSSL.
--and option to disable it:
++and match, both absent or present in the response only. A nonzero return
+-and match, both absent or present in the response only. A non-zero return
++and the timestamp token itself (ContentInfo), if the token generation was
+-and the time stamp token itself (ContentInfo), if the token generation was
 +an existing structure. Therefore, the following:
 -an existing structure. Therefore the following:
++a nonce value. The nonce length is given by B<15 - L> so it is 7 by default for
 +an RSA structure. However, the public key is encoded using a
 -an RSA structure. However the public key is encoded using a
++any previously specified hostname or names.  If B<name> is NULL,
+-any previously specified host name or names.  If B<name> is NULL,
 +          * anyway, e.g. the server could only possibly create 1 session
 -          * anyway, eg. the server could only possibly create 1 session
++applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g. B<prime256v1>). Group
++applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g. B<prime256v1>). Group
+-applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
+-applicable (e.g. B<X25519>) or an OpenSSL OID name (e.g B<prime256v1>). Group
 +application), which might lead to malfunctions. Therefore, each application
 -application), which might lead to malfunctions. Therefore each application
--as an alternative to the publically known i2d and d2i functions.  It's
-+as an alternative to the publicly known i2d and d2i functions.  It's
++ASN1_TYPE_cmp() returns 0 if the types are identical and nonzero otherwise.
+-ASN1_TYPE_cmp() returns 0 if the types are identical and non-zero otherwise.
++as the return value when they differ is undefined, other than being nonzero.
+-as the return value when they differ is undefined, other than being non-zero.
++a timestamp request to the TSA and one for sending the timestamp response
++A timestamp response (TimeStampResp) consists of a response status
+-A time stamp response (TimeStampResp) consists of a response status
 +authentication, however, due to a bug only MSIE 5.0 and later support
 -authentication, however due to a bug only MSIE 5.0 and later support
++avoid the misconception that nonblocking SSL_write() behaves like
+-avoid the misconception that non-blocking SSL_write() behaves like
 +be automatically passed to the relevant BIO. However, this can cause
 -be automatically passed to the relevant BIO. However this can cause
++be interpreted primarily as a hostname or a service name in ambiguous
+-be interpreted primarily as a host name or a service name in ambiguous
 +below) and TLSv1.3. However, the RFC has this note of caution:
 +below) and TLSv1.3. However, the RFC has this note of caution:
 -below) and TLSv1.3. However the RFC has this note of caution:
 -below) and TLSv1.3. However the RFC has this note of caution:
 +be performed. However, since the chance of random data passing the test
 -be performed. However since the chance of random data passing the test
++B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a
+-B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
 -BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt an variable
 +BF_cfb64_encrypt() and BF_ofb64_encrypt() are used to encrypt a variable
++B<hostname> on port B<port>. B<path> specifies the HTTP pathname to use
+-B<hostname> on port B<port>. B<path> specifies the HTTP path name to use
 +B<int64_t> type. However, in many cases (for example version numbers) they
 -B<int64_t> type. However in many cases (for example version numbers) they
 +BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of
 -BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
--B<q>, B<g>, and the public and and private key components.  Public keys
-+B<q>, B<g>, and the public and private key components.  Public keys
++B<name> clearing any previously specified hostname or names.  If
+-B<name> clearing any previously specified host name or names.  If
++BN_mod_add() adds I<a> to I<b> modulo I<m> and places the nonnegative
+-BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative
++BN_mod_mul() multiplies I<a> by I<b> and finds the nonnegative
+-BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative
++BN_nnmod() reduces I<a> modulo I<m> and places the nonnegative
+-BN_nnmod() reduces I<a> modulo I<m> and places the non-negative
++B<num> is too small for the pathname, an error occurs.
+-B<num> is too small for the path name, an error occurs.
++B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts
+-B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts
++B<r> (C<r=a/2^n>). Note that B<n> must be nonnegative. BN_rshift1() shifts
+-B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts
+-B<to>. The result is padded with zeroes if necessary. If B<tolen> is less than
++B<to>. The result is padded with zeros if necessary. If B<tolen> is less than
++B<where> is a bit mask made up of the following bits:
+-B<where> is a bitmask made up of the following bits:
 +by the OpenSSL high-level public key API. Contexts B<MUST NOT> be shared between
 -by the OpenSSL high level public key API. Contexts B<MUST NOT> be shared between
--callback multipe times (one for each capability). Capabilities can be useful for
-+callback multiple times (one for each capability). Capabilities can be useful for
 +callback. The callback is called during most high-level BIO operations. It can
 -callback. The callback is called during most high level BIO operations. It can
-+Capabilities describe some of the services that a provider can offer.
--Capabilties describe some of the services that a provider can offer.
++can be used to make sure the buffers are preallocated. This can be used to
+-can be used to make sure the buffers are pre-allocated. This can be used to
++(CBC) mode of DES.  If the I<encrypt> argument is nonzero, the
+-(CBC) mode of DES.  If the I<encrypt> argument is non-zero, the
++certificate matches a given hostname, email address, or IP address.
+-certificate matches a given host name, email address, or IP address.
 -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.
++checks are not performed on the peer certificate.  When a nonempty
+-checks are not performed on the peer certificate.  When a non-empty
 +cleanly supported at the low-level and some operations are more efficient
 -cleanly supported at the low level and some operations are more efficient
++ command line arguments that look like filenames get translated from
+- command line arguments that look like file names get translated from
++connection, it behaves nonblocking and will return as soon as the write
+-connection, it behaves non-blocking and will return as soon as the write
++Create a timestamp request, write it to file3.tsq, send it to the server and
+-Create a time stamp request, write it to file3.tsq, send it to the server and
++create strings with the hostname and service name and give those
+-create strings with the host name and service name and give those
++creating a timestamp request based on a data file,
+-creating a time stamp request based on a data file,
++creating a timestamp response based on a request, verifying if a
+-creating a time stamp response based on a request, verifying if a
++CRYPTO_memcmp() returns 0 if the memory regions are equal and nonzero
+-CRYPTO_memcmp() returns 0 if the memory regions are equal and non-zero
 +default implementation for a given task, e.g. by ENGINE_get_default_RSA(),
 -default implementation for a given task, eg. by ENGINE_get_default_RSA(),
--Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
-+Disables the KM-XTS-AES and the KIMD-SHAKE function codes:
++description "pass phrase" and the filename "foo.key", that becomes
+-description "pass phrase" and the file name "foo.key", that becomes
++descriptors but will still populate B<*numfds>. Therefore, application code is
+-descriptors but will still populate B<*numfds>. Therefore application code is
++descriptors. Conversely, a nonzero argument enables the retention of
+-descriptors. Conversely, a non-zero argument enables the retention of
++DES_set_key_checked() if the I<DES_check_key> flag is nonzero,
+-DES_set_key_checked() if the I<DES_check_key> flag is non-zero,
++DH_set_method() returns nonzero if the provided B<meth> was successfully set as
+-DH_set_method() returns non-zero if the provided B<meth> was successfully set as
++do not print out the timezone: it either prints out "GMT" or nothing. But all
+-do not print out the time zone: it either prints out "GMT" or nothing. But all
++DSA_set_method() returns nonzero if the provided B<meth> was successfully set as
+-DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
++early data setting for a server is nonzero then replay protection is
+-early data setting for a server is non-zero then replay protection is
 +ECDSA_do_sign_ex - low-level elliptic curve digital signature algorithm (ECDSA)
 -ECDSA_do_sign_ex - low level elliptic curve digital signature algorithm (ECDSA)
 +(e.g. B<prime256v1>). Curve names are case sensitive.
 -(e.g B<prime256v1>). Curve names are case sensitive.
-+(e.g. B<prime256v1>). Group names are case sensitive. The list should be
--(e.g B<prime256v1>). Group names are case sensitive. The list should be
-+(e.g. B<prime256v1>). Group names are case sensitive. The list should be in
--(e.g B<prime256v1>). Group names are case sensitive. The list should be in
 +(e.g. see SSL_CTX_set_psk_find_session_callback(3)). Therefore, extreme caution
 -(e.g. see SSL_CTX_set_psk_find_session_callback(3)). Therefore extreme caution
++ emulated filesystem name space with POSIX-y root, mount points, /dev
+- emulated file system name space with POSIX-y root, mount points, /dev
++encodings and nonzero otherwise.
+-encodings and non-zero otherwise.
 +ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command.
 -ENGINE, ie. the ENGINE's ctrl() handler is not used for the control command.
--EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitalised.
-+EVP_RAND_STATE_UNINITIALISED: this DRBG is currently uninitialised.
--EVP_RAND_strength() returns the strenght of the random number generator in bits.
-+EVP_RAND_strength() returns the strength of the random number generator in bits.
-+  * Experimental macOS support
--  * Experimental MacOS support
-+Feature options always come in pairs, an option to enable feature
--Feature options always come in pairs, an option to enable feature `xxxx`, and
-+for more information about implicit fetches.
-+for more information about implicit fetches.
-+for more information about implicit fetches.
--for more information about implict fetches.
--for more information about implict fetches.
--for more information about implict fetches.
-+For more information about the callback data see the NOTES section.
--For more information about the the callback data see the NOTES section.
--form, this key is commonly refered to as the "origin".
-+form, this key is commonly referred to as the "origin".
++enter cacert.pem when prompted for the CA filename.
+-enter cacert.pem when prompted for the CA file name.
++example) be because of nonblocking IO, or some invalid message having been
+-example) be because of non-blocking IO, or some invalid message having been
+-Files are loaded in a single pass. This means that an variable expansion
++Files are loaded in a single pass. This means that a variable expansion
++Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags.
+-Finally, OPENSSL_INIT_set_file_flags can be used to specify non-default flags.
++For both blocking or nonblocking sockets, the details state information
+-For both blocking or non-blocking sockets, the details state information
++for nonblocking BIOs. Call SSL_get_error() with the return value B<ret>
++for nonblocking BIOs. Call SSL_get_error() with the return value B<ret>
++for nonblocking BIOs. Call SSL_get_error() with the return value B<ret>
+-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
+-for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
 +for testing any SSL/TLS code (e.g. proxies) that wish to deal with multiple
 -for testing any SSL/TLS code (eg. proxies) that wish to deal with multiple
--for the B<wbio>.
++Function and reason codes should consist of uppercase characters,
+-Function and reason codes should consist of upper case characters,
++Get a timestamp response for file1.tsq and file2.tsq over HTTP showing
+-Get a time stamp response for file1.tsq and file2.tsq over HTTP showing
++Get a timestamp response for file1.tsq over HTTP, output is written to
+-Get a time stamp response for file1.tsq over HTTP, output is written to
++Get a timestamp response for file1.tsq over HTTPS with certificate-based
+-Get a time stamp response for file1.tsq over HTTPS with certificate-based
++Get a timestamp response for file1.tsq over HTTPS without client
+-Get a time stamp response for file1.tsq over HTTPS without client
 +handshake. Therefore, just because one ticket is unacceptable it does not mean
 -handshake. Therefore just because one ticket is unacceptable it does not mean
+-HMAC_CTX_reset() zeroes an existing B<HMAC_CTX> and associated
++HMAC_CTX_reset() zeros an existing B<HMAC_CTX> and associated
 +However, a verification callback is B<not> essential and the default operation
 -However a verification callback is B<not> essential and the default operation
 +However, if the call was an SSL_write() or SSL_write_ex(), it should be called
 -However if the call was an SSL_write() or SSL_write_ex(), it should be called
-+However, in most cases OpenSSL will choose a suitable default method,
--However in most cases OpenSSL will choose a suitable default method,
-+   However, in this context it is only used for building OpenSSL.
--   However in this context it is only used for building OpenSSL.
 +However, the handshake will continue and send a warning alert instead. The value
 -However the handshake will continue and send a warning alert instead. The value
 +However, very few applications currently support the control interface and so
@@ -124,78 +204,162 @@
 -IDs (eg. with a certain prefix).
 +ids. However, OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
 -ids. However OpenSSL allows two modes of ticket operation in TLSv1.3: stateful
-+(i.e. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
--(ie. the prime bit size) or NULL if the arguments are not valid SRP group parameters.
++If both B<*pday> and B<*psec> are nonzero they will always have the same
+-If both B<*pday> and B<*psec> are non-zero they will always have the same
++If B<verify> is nonzero, the password will be verified as well.
+-If B<verify> is non-zero, the password will be verified as well.
 +If TCP is being used then there is no need to use SSL_stateless(). However, some
 -If TCP is being used then there is no need to use SSL_stateless(). However some
--If this fixes a github issue, make sure to have a line saying 'Fixes #XXXX' (without quotes) in the commit message.
-+If this fixes a GitHub issue, make sure to have a line saying 'Fixes #XXXX' (without quotes) in the commit message.
++If the I<encrypt> argument is nonzero (DES_ENCRYPT), the I<input>
+-If the I<encrypt> argument is non-zero (DES_ENCRYPT), the I<input>
++If the port name is supplied as part of the hostname then this will
+-If the port name is supplied as part of the host name then this will
++If the underlying accept socket is nonblocking and BIO_do_accept() is
+-If the underlying accept socket is non-blocking and BIO_do_accept() is
++If the underlying BIO is B<nonblocking>, a read function will also return when
+-If the underlying BIO is B<non-blocking>, a read function will also return when
++If the underlying BIO is B<nonblocking>, SSL_accept() will also return
+-If the underlying BIO is B<non-blocking>, SSL_accept() will also return
++If the underlying BIO is B<nonblocking>, SSL_connect() will also return
+-If the underlying BIO is B<non-blocking>, SSL_connect() will also return
++If the underlying BIO is B<nonblocking>, SSL_do_handshake() will also return
+-If the underlying BIO is B<non-blocking>, SSL_do_handshake() will also return
++If the underlying BIO is B<nonblocking>, SSL_shutdown() will also return
+-If the underlying BIO is B<non-blocking>, SSL_shutdown() will also return
++If the underlying BIO is B<nonblocking> the write functions will also return
+-If the underlying BIO is B<non-blocking> the write functions will also return
 +implementations (e.g. from an ENGINE module that supports embedded
 -implementations (eg. from an ENGINE module that supports embedded
++In a nonblocking environment applications must be prepared to handle
+-In a non-blocking environment applications must be prepared to handle
 +indexed in the hash table (i.e. it is returned as "const" from
 -indexed in the hash table (ie. it is returned as "const" from
 +information. Therefore, appropriate security precautions should be taken if
 -information. Therefore appropriate security precautions should be taken if
--is consumed
++inherit the behaviour of B<fd>. If B<fd> is nonblocking, the B<ssl> will
+-inherit the behaviour of B<fd>. If B<fd> is non-blocking, the B<ssl> will
++instance of L<openssl(1)> is trying to create a timestamp
+-instance of L<openssl(1)> is trying to create a time stamp
++into lowercase and underscores changed to spaces.
+-into lower case and underscores changed to spaces.
 +is included, commonly as one of the first included headers. Therefore,
 +is included, commonly as one of the first included headers. Therefore,
 +is included, commonly as one of the first included headers. Therefore,
 -is included, commonly as one of the first included headers. Therefore
 -is included, commonly as one of the first included headers. Therefore
 -is included, commonly as one of the first included headers. Therefore
-+issue the following commands to build OpenSSL.
--It can contain the legacy form of keys -- i.e. pointers to the low
-+It can contain the legacy form of keys -- i.e. pointers to the low-level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
++It can occur if an action is needed to continue the operation for nonblocking
+-It can occur if an action is needed to continue the operation for non-blocking
 -=item -1 an error condition has occured
 -=item -1 an error condition has occured
 +=item -1 an error condition has occurred
 +=item -1 an error condition has occurred
 +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
-+length for the chosen cipher or an error is returned. Moreover, the
--length for the chosen cipher or an error is returned. Moreover the
--level key types, such as B<RSA>, B<DSA> and B<EC> --, but also the
--L<Text::Temlate|https://metacpan.org/pod/Text::Template>
-+L<Text::Template|https://metacpan.org/pod/Text::Template>
++last timestamp response created. This number is incremented by 1 for
+-last time stamp response created. This number is incremented by 1 for
++length parameter associated with this DH object. If the length is nonzero then
+-length parameter associated with this DH object. If the length is non-zero then
++lingual environment, encode filenames in UTF-8.
+-lingual environment, encode file names in UTF-8.
++List of files containing B<RFC 3161> DER-encoded timestamp requests. If no
+-List of files containing B<RFC 3161> DER-encoded time stamp requests. If no
++list will only contain one file descriptor. However, if multiple asynchronous
+-list will only contain one file descriptor. However if multiple asynchronous
++looks for a non-critical extension a nonzero value looks for a critical
+-looks for a non-critical extension a non-zero value looks for a critical
++many input bytes as possible (for nonblocking reads) or not. For example if
+-many input bytes as possible (for non-blocking reads) or not. For example if
 +many references being held.  Therefore, applications should
 -many references being held.  Therefore applications should
-+more information about implicit fetches.
-+more information about implicit fetches.
-+more information about implicit fetches.
--more information about implict fetches.
--more information about implict fetches.
--more information about implict fetches.
++means standard output. In case of multiple timestamp requests or the absence
+-means standard output. In case of multiple time stamp requests or the absence
+-Name (SAN) or Subject CommonName (CN) matches the specified host
++Name (SAN) or Subject CommonName (CN) matches the specified hostname, 
+-name, which must be encoded in the preferred name syntax described
 + NDK. It's available for Linux, macOS and Windows, but only Linux
 - NDK. It's available for Linux, Mac OS X and Windows, but only Linux
-+  * New 'rsautl' application, low-level RSA utility.
--  * New 'rsautl' application, low level RSA utility.
-+obtain administrative privileges depends on the operating system.
--obtain administrative privileges depends on the operating sytem.
++needed, for example when some nondefault initialisation is required. The
++needed, for example when some nondefault initialisation is required. The
+-needed, for example when some non-default initialisation is required. The
+-needed, for example when some non-default initialisation is required. The
++ - Netwide Assembler, aka NASM, available from https://www.nasm.us,
+- - Netwide Assembler, a.k.a. NASM, available from https://www.nasm.us,
++nonblocking I/O. Error conditions are not handled and must be treated
+-non-blocking I/O. Error conditions are not handled and must be treated
++nonblocking socket, nothing is to be done, but select() can be used to check
+-non-blocking socket, nothing is to be done, but select() can be used to check
++nonblocking then the B<ssl> object will also have nonblocking behaviour. This
+-non-blocking then the B<ssl> object will also have non-blocking behaviour. This
++nonblocking write().
+-non-blocking write().
+-nonce value. The nonce length is given by B<15 - L> so it is 7 by default for
++nondefault application name.
+-non-default application name.
++nondefault filename, which is copied and need not refer to persistent storage.
+-non-default filename, which is copied and need not refer to persistent storage.
++nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
+-non-empty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
++ noninteractive service applications might feel concerned about
+- non-interactive service applications might feel concerned about
++nonnegative integer representing where in the certificate chain the error
+-non-negative integer representing where in the certificate chain the error
++nonnegative result in I<r>.
+-non-negative result in I<r>.
++nonnegative value can be included.
+-non-negative value can be included.
++nonnegative value indicates the chain depth at which the TLSA record matched a
+-non-negative value indicates the chain depth at which the TLSA record matched a
++nonzero if yes it will expire or zero if not.
+-non-zero if yes it will expire or zero if not.
++nonzero otherwise.
+-non-zero otherwise.
++No support for timestamps over SMTP, though it is quite easy
+-No support for time stamps over SMTP, though it is quite easy
++    Note: on VMS, you must quote any argument that contains uppercase
+-    Note: on VMS, you must quote any argument that contains upper case
++Note that I<a> must be nonnegative and smaller than the modulus.
+-Note that I<a> must be non-negative and smaller than the modulus.
++Note: these functions provide a low-level interface to ECDSA. Most
+-Note: these functions provide a low level interface to ECDSA. Most
++objects from a repository of any kind, addressable as a filename or
+-objects from a repository of any kind, addressable as a file name or
 +occurrences is an error. Therefore, the B<idx> parameter is usually B<NULL>.
 -occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
-+of auditing may be required. Therefore, the logging facility supports a severity
--of auditing may be required. Therefore the logging facility supports a severity
++OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and nonzero
+-OCSP_id_cmp() and OCSP_id_issuer_cmp() returns zero for a match and non-zero
++OCSP_sendreq_bio() does not support retries and so cannot handle nonblocking
+-OCSP_sendreq_bio() does not support retries and so cannot handle non-blocking
++OCSP_sendreq_nbio() performs nonblocking I/O on the OCSP request context
+-OCSP_sendreq_nbio() performs non-blocking I/O on the OCSP request context
++OCSP_single_get0_status(). If B<sec> is nonzero it indicates how many seconds
+-OCSP_single_get0_status(). If B<sec> is non-zero it indicates how many seconds
++of a timestamp response (TimeStampResp). (Optional)
++of a timestamp response (TimeStampResp). (Optional)
+-of a time stamp response (TimeStampResp). (Optional)
+-of a time stamp response (TimeStampResp). (Optional)
 +one of the first included headers. Therefore, it is defined as an
 -one of the first included headers. Therefore it is defined as an
--                   Only install the OpenSSL html documentation.
-+                   Only install the OpenSSL HTML documentation.
-+on success, or 0 on failure. An error is placed on the error stack if a
--on success, or 0 on failure. An error is placed on the the error stack if a
-+or for any other reason want to minimize the data
--or for any other reason want to to minimize the data
--OSSL_PARAM_construct_octet_ptr() is a function that constructes an OCTET string
-+OSSL_PARAM_construct_octet_ptr() is a function that constructs an OCTET string
--OSSL_PARAM_construct_utf8_ptr() is a function that constructes a UTF string
-+OSSL_PARAM_construct_utf8_ptr() is a function that constructs a UTF string
--other then one reference is consumed for the B<rbio> and one reference
-+Otherwise, the value should be a hex string to output directly, however, this
--Otherwise, the value should be a hex string to output directly, however this
++on error or when IO might otherwise block and nonblocking is being used.
+-on error or when IO might otherwise block and non-blocking is being used.
++on the 16-bit DOS platform). This should be sufficient for usual certificate
+-on the 16bit DOS platform). This should be sufficient for usual certificate
++operation from a nonblocking B<BIO>.
+-operation from a non-blocking B<BIO>.
++otherwise it is a timestamp token (ContentInfo).
+-otherwise it is a time stamp token (ContentInfo).
 +ownership of one reference. Therefore, it may be necessary to increment the
 -ownership of one reference. Therefore it may be necessary to increment the
++particular when the source/sink is nonblocking or of a certain type
+-particular when the source/sink is non-blocking or of a certain type
 +passed to an ENGINE B<before> attempting to initialise it, i.e. before
 -passed to an ENGINE B<before> attempting to initialise it, ie. before
--pointer to the associated value is is passed as the second argument.
-+pointer to the associated value is passed as the second argument.
++ [pid]:error:[error code]:[library name]:[function name]:[reason string]:[filename]:[line]:[optional text message]
+- [pid]:error:[error code]:[library name]:[function name]:[reason string]:[file name]:[line]:[optional text message]
++preallocated B<BN_CTX> (to save the overhead of allocating and
+-pre-allocated B<BN_CTX> (to save the overhead of allocating and
++preallocated B<EVP_PKEY_CTX> should be assigned to the B<EVP_MD_CTX>. This is
+-pre-allocated B<EVP_PKEY_CTX> should be assigned to the B<EVP_MD_CTX>. This is
 +preference to the low-level interfaces. This is because the code then becomes
 +preference to the low-level interfaces. This is because the code then becomes
 +preference to the low-level interfaces. This is because the code then becomes
@@ -208,47 +372,124 @@
 -preference to the low level interfaces. This is because the code then becomes
 -preference to the low level interfaces. This is because the code then becomes
 -preference to the low level interfaces. This is because the code then becomes
-+reference is consumed for the B<wbio>.
-+representation. This function is used for B<X509v3> extensions.
--representation. This function is used for B<X509v3> extentions.
+-RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of a the derivation function
++RAND_DRBG_FLAG_CTR_NO_DF, which disables the use of the derivation function
++random blinding factor. B<ctx> is B<NULL> or a preallocated and
+-random blinding factor. B<ctx> is B<NULL> or a pre-allocated and
++relax the semantics of the function - if set nonzero it will only return
+-relax the semantics of the function - if set non-zero it will only return
 +request DN, however, it is good policy just having the e-mail set into
 -request DN, however it is good policy just having the e-mail set into
 +required. However, clients may have tickets containing the previously configured
 -required. However clients may have tickets containing the previously configured
++response or timestamp token based on a request and printing the
+-response or time stamp token based on a request and printing the
 +return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP
 -return any SCTP based addresses when calling getaddrinfo(). Therefore if an SCTP
-+return no file descriptors but will still populate I<*numfds>. Therefore,
--return no file descriptors but will still populate I<*numfds>. Therefore
++return nonzero to indicate that the ENGINE is now operational and will
+-return non-zero to indicate that the ENGINE is now operational and will
++return value is nonzero. Technically if both parameters are NULL the two
+-return value is non-zero. Technically if both parameters are NULL the two
 +RSA_private_encrypt, RSA_public_decrypt - low-level signature operations
 -RSA_private_encrypt, RSA_public_decrypt - low level signature operations
+-seconds, that  need to be included in the time field. The trailing zeroes
++seconds, that  need to be included in the time field. The trailing zeros
++server is configured with a nonzero max early data value. With replay
+-server is configured with a non-zero max early data value. With replay
++server. The timestamp response will be written to the given output file. '-'
+-server. The time stamp response will be written to the given output file. '-'
 +session lookups in the external cache (i.e. for session-resume requests) would
 -session lookups in the external cache (ie. for session-resume requests) would
-+Sets the CCM nonce (IV) length. This call can only be made before specifying a 
++Sets the CCM nonce (IV) length. This call can only be made before specifying 
 -Sets the CCM nonce (IV) length. This call can only be made before specifying an
-+ Special notes for Universal Windows Platform builds, aka VC-*-UWP
-- Special notes for Universal Windows Platform builds, a.k.a. VC-*-UWP
++Sets the socket to nonblocking mode.
+-Sets the socket to non-blocking mode.
++Setting B<SSL_MODE_AUTO_RETRY> for a nonblocking B<BIO> will process
+-Setting B<SSL_MODE_AUTO_RETRY> for a non-blocking B<BIO> will process
++signs them and sends the timestamp token back to the client. By
+-signs them and sends the time stamp token back to the client. By
++specified in B<RFC 3161>, to a timestamp server over HTTP or HTTPS and storing
+-specified in B<RFC 3161>, to a time stamp server over HTTP or HTTPS and storing
++specified the output is always a timestamp response (TimeStampResp),
+-specified the output is always a time stamp response (TimeStampResp),
++Specifies a previously created timestamp response or timestamp token
+-Specifies a previously created time stamp response or time stamp token
++SSL_clear_mode() removes the mode set via bit mask in B<mode> from B<ssl>.
+-SSL_clear_mode() removes the mode set via bitmask in B<mode> from B<ssl>.
++SSL_clear_options() clears the options set via bit mask in B<options> to B<ssl>.
+-SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
++SSL_CTX_clear_mode() removes the mode set via bit mask in B<mode> from B<ctx>.
+-SSL_CTX_clear_mode() removes the mode set via bitmask in B<mode> from B<ctx>.
++SSL_CTX_clear_options() and SSL_clear_options() return the new options bit mask
+-SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
++SSL_CTX_clear_options() clears the options set via bit mask in B<options>
+-SSL_CTX_clear_options() clears the options set via bitmask in B<options>
++SSL_CTX_get_mode() and SSL_get_mode() return the current bit mask.
+-SSL_CTX_get_mode() and SSL_get_mode() return the current bitmask.
++SSL_CTX_get_options() and SSL_get_options() return the current bit mask.
+-SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
++SSL_CTX_set_mode() adds the mode set via bit mask in B<mode> to B<ctx>.
+-SSL_CTX_set_mode() adds the mode set via bitmask in B<mode> to B<ctx>.
++SSL_CTX_set_mode() and SSL_set_mode() return the new mode bit mask
+-SSL_CTX_set_mode() and SSL_set_mode() return the new mode bitmask
++SSL_CTX_set_options() adds the options set via bit mask in B<options> to B<ctx>.
+-SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
++SSL_CTX_set_options() and SSL_set_options() return the new options bit mask
+-SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
 + SSL_operations(); /* e.g. SSL_read and SSL_write */
 - SSL_operations(); /* e.g SSL_read and SSL_write */
++SSL_set_mode() adds the mode set via bit mask in B<mode> to B<ssl>.
+-SSL_set_mode() adds the mode set via bitmask in B<mode> to B<ssl>.
++SSL_set_options() adds the options set via bit mask in B<options> to B<ssl>.
+-SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
+-stamp request to the TSA and one for sending the time stamp response
+-stamp token is valid and matches a particular time stamp request or
 +successfully initialise - i.e. to assume that this corresponds to
 -successfully initialise - ie. to assume that this corresponds to
++successful. The B<-reply> command is for creating a timestamp
+-successful. The B<-reply> command is for creating a time stamp
 +supports certain specific commands it might want to use (e.g. application "foo"
 -supports certain specific commands it might want to use (eg. application "foo"
++Tests nonblocking I/O
+-Tests non-blocking I/O
 +than the current time. However, since the signing time is supplied by the
 +than the current time. However, since the signing time is supplied by the
 -than the current time. However since the signing time is supplied by the
 -than the current time. However since the signing time is supplied by the
--That is, the B<NUL> character and and of C<()*>.
-+That is, the B<NUL> character and of C<()*>.
++that parameter. EVP_PKEY_CTX_gen_keygen_info() with a nonnegative value for
+-that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for
++that the input is a DER encoded timestamp token (ContentInfo) instead
++that the input is a DER encoded timestamp token (ContentInfo) instead
+-that the input is a DER encoded time stamp token (ContentInfo) instead
+-that the input is a DER encoded time stamp token (ContentInfo) instead
++The action depends on the underlying BIO. When using a nonblocking socket,
++The action depends on the underlying BIO. When using a nonblocking socket,
++The action depends on the underlying BIO. When using a nonblocking socket,
++The action depends on the underlying BIO. When using a nonblocking socket,
+-The action depends on the underlying BIO. When using a non-blocking socket,
+-The action depends on the underlying BIO. When using a non-blocking socket,
+-The action depends on the underlying BIO. When using a non-blocking socket,
+-The action depends on the underlying BIO. When using a non-blocking socket,
 +The B<cleanup_entropy>() callback is called from the B<drbg> to clear and
 -The B<cleanup_entropy>() callback is called from the B<drbg> to to clear and
 +The B<EVP_PKEY>I<XXX> functions provide a high-level interface to
 -The B<EVP_PKEY>I<XXX> functions provide a high level interface to
-+the B<I<TYPE>> part of B<PEM_write_bio_I<TYPE>> functions as well
--the B<I<TYPE>> part of of B<PEM_write_bio_I<TYPE>> functions as well
++The B<flags> argument is a bit mask of the features to enable or disable.
+-The B<flags> argument is a bitmask of the features to enable or disable.
++The B<pkeyutl> command can be used to perform low-level public key operations
+-The B<pkeyutl> command can be used to perform low level public key operations
++The B<-query> switch can be used for creating and printing a timestamp
+-The B<-query> switch can be used for creating and printing a time stamp
++The B<tsget> command can be used for sending a timestamp request, as
+-The B<tsget> command can be used for sending a time stamp request, as
++The B<-verify> command is for verifying if a timestamp response or 
+-The B<-verify> command is for verifying if a time stamp response or time
 +The context can then be reused with a new call to X509_STORE_CTX_init().
 -The context can then be reused with an new call to X509_STORE_CTX_init().
-+The default value used if this is not set is the maximum value of
--The default valure used if this is not set is the maximum value of
++The data file for which the timestamp request needs to be
+-The data file for which the time stamp request needs to be
+-The encoded data is in binary form and may contain embedded zeroes.
++The encoded data is in binary form and may contain embedded zeros.
 +The EVP cipher routines are a high-level interface to certain
 -The EVP cipher routines are a high level interface to certain
 +The EVP digest routines are a high-level interface to message digests,
@@ -259,10 +500,6 @@
 +The EVP envelope routines are a high-level interface to envelope
 -The EVP envelope routines are a high level interface to envelope
 -The EVP envelope routines are a high level interface to envelope
-+The EVP KDF routines are a high-level interface to Key Derivation Function
--The EVP KDF routines are a high level interface to Key Derivation Function
-+The EVP RAND routines are a high-level interface to random number generators
--The EVP RAND routines are a high level interface to random number generators
 +The EVP signature routines are a high-level interface to digital
 -The EVP signature routines are a high level interface to digital
 +The EVP signature routines are a high-level interface to digital signatures.
@@ -271,72 +508,137 @@
 -The EVP signature routines are a high level interface to digital signatures.
 +The EVP signature verification routines are a high-level interface to digital
 -The EVP signature verification routines are a high level interface to digital
-+the list will only contain one file descriptor. However, if multiple asynchronous
--the list will only contain one file descriptor. However if multiple asynchronous
++the input is a token and the output is a timestamp response a default
+-the input is a token and the output is a time stamp response a default
++The name of the file containing a DER encoded timestamp request. (Optional)
+-The name of the file containing a DER encoded time stamp request. (Optional)
++The options are coded as bit masks and can be combined by a bitwise B<or>
+-The options are coded as bitmasks and can be combined by a bitwise B<or>
++The original timestamp request in DER format. The B<-data> and B<-digest>
+-The original time stamp request in DER format. The B<-data> and B<-digest>
++The output is a timestamp token (ContentInfo) instead of timestamp
+-The output is a time stamp token (ContentInfo) instead of time stamp
 +Therefore, any FILE pointers or BIOs should be opened in binary mode.
 -Therefore any FILE pointers or BIOs should be opened in binary mode.
 +Therefore, data that was not retrieved at the last read call can still be
 -Therefore data that was not retrieved at the last read call can still be
-+Therefore, the client offers the possibility to read
--Therefore the client offers the possibility to read
-+Therefore, the function should return 1 on success and 0 on failure.
--Therefore the function should return 1 on success and 0 on failure.
++Therefore, in order to perform nondefault initialisation,
++Therefore, in order to perform nondefault initialisation,
+-Therefore, in order to perform non-default initialisation,
+-Therefore, in order to perform non-default initialisation,
 +Therefore, there will either be three or five bits set dependent on whether the
 -Therefore there will either be three or five bits set dependent on whether the
-+Therefore, these credentials are easily recovered by anyone able to sniff/trace
--Therefore these credentials are easily recovered by anyone able to sniff/trace
++There is one DER encoded protocol data unit defined for transporting 
+-There is one DER encoded protocol data unit defined for transporting a time
 +there will only ever be two possible values for y. Therefore, a point can be set
 -there will only ever be two possible values for y. Therefore a point can be set
 +these functions do not perform a digest of the data to be signed. Therefore,
 -these functions do not perform a digest of the data to be signed. Therefore
 +These functions handle RSA signatures at a low-level.
 -These functions handle RSA signatures at a low level.
-+These functions use an B<EVP_PKEY_CTX> context, which should primarily
--These functions use an B<EVP_PKEY_CTX> context, which should primarly
-+this by default.  However, if on a platform where this is not the case then this
--this by default.  However if on a platform where this is not the case then this
-+This command can be used to perform low-level public key
--This command can be used to perform low level public key
--to each
-+to each other, then one reference is consumed for the B<rbio> and one 
++The shutdown state of an ssl connection is a bit mask of:
+-The shutdown state of an ssl connection is a bitmask of:
++the timestamp response in a file. This tool cannot be used for creating the
+-the time stamp response in a file. This tool cannot be used for creating the
++The timestamp response that needs to be verified in DER format. (Mandatory)
+-The time stamp response that needs to be verified in DER format. (Mandatory)
++The tool sends the following HTTP request for each timestamp request:
+-The tool sends the following HTTP request for each time stamp request:
++The TSA client receives the timestamp token and verifies the
+-The TSA client receives the time stamp token and verifies the
++The URL of the HTTP/HTTPS server listening for timestamp requests.
+-The URL of the HTTP/HTTPS server listening for time stamp requests.
++The value is a filename.
+-The value is a file name.
++they are identical and nonzero otherwise.
+-they are identical and non-zero otherwise.
++This option specifies a previously created timestamp request in DER
+-This option specifies a previously created time stamp request in DER
++timestamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
+-time stamp requests, tsa.opentsa.org listens at port 8080 for HTTP requests
++timestamp token. Either the dotted OID notation or OID names defined
+-time stamp token. Either the dotted OID notation or OID names defined
++timestamp token is valid and matches a particular timestamp request or
++To add 'granted' status info to a timestamp token thereby creating a
+-To add 'granted' status info to a time stamp token thereby creating a
++to a nonblocking B<BIO> and it was unable to sent all data to the B<BIO>.
+-to a non-blocking B<BIO> and it was unable to sent all data to the B<BIO>.
++To create a similar timestamp request with specifying the message imprint
+-To create a similar time stamp request with specifying the message imprint
++To create a timestamp request for design1.txt with SHA-1
+-To create a time stamp request for design1.txt with SHA-1
++To create a timestamp request which includes the MD-5 digest
+-To create a time stamp request which includes the MD-5 digest
++To create a timestamp response for a request:
+-To create a time stamp response for a request:
++To create a timestamp token instead of timestamp response:
+-To create a time stamp token instead of time stamp response:
++To extract the timestamp token from a response:
+-To extract the time stamp token from a response:
++token or you want to extract the timestamp token from a response. If
+-token or you want to extract the time stamp token from a response. If
++To print a timestamp reply to stdout in human readable format:
+-To print a time stamp reply to stdout in human readable format:
++To print a timestamp token to stdout in human readable format:
+-To print a time stamp token to stdout in human readable format:
++To verify a timestamp reply against a request:
+-To verify a time stamp reply against a request:
++To verify a timestamp reply that includes the certificate chain:
+-To verify a time stamp reply that includes the certificate chain:
++To verify a timestamp token against a message imprint:
+-To verify a time stamp token against a message imprint:
++To verify a timestamp token against the original data file:
+-To verify a time stamp token against the original data file:
 +treated as handles - i.e. not only as pointers, but also as references to
 -treated as handles - ie. not only as pointers, but also as references to
++Turns on nonblocking I/O
+-Turns on non-blocking I/O
 +types could be absent OPTIONAL fields and so should match, however, passing
 -types could be absent OPTIONAL fields and so should match, however passing
-+unique integer NID value. However, support for some groups may be added by
--unique integer NID value. However support for some groups may be added by
 +using the high-level interface.
 -using the high level interface.
++value under BER can have any nonzero encoding but ASN1_TYPE_cmp() will
+-value under BER can have any non-zero encoding but ASN1_TYPE_cmp() will
++value will be used as the seed filename.
+-value will be used as the seed file name.
++verification, therefore, this description applies to these verify operations
+-verification, therefore this description applies to these verify operations
 +versions of new algorithms cannot be accessed using the low-level functions.
 -versions of new algorithms cannot be accessed using the low level functions.
 + version was actually tested. There is no reason to believe that macOS
 - version was actually tested. There is no reason to believe that Mac OS X
 +viewed and checked. However, some servers only request client authentication
 -viewed and checked. However some servers only request client authentication
-+ Visual C++ native builds, aka VC-*
-- Visual C++ native builds, a.k.a. VC-*
++ Visual C++ builds, aka VC-*
+- Visual C++ builds, a.k.a. VC-*
 + We have only tested with DEC C (aka HP VMS C / VSI C) and require
 - We have only tested with DEC C (a.k.a HP VMS C / VSI C) and require
 +When a default ENGINE is requested for a given abstraction/algorithm/mode, (e.g.
 -When a default ENGINE is requested for a given abstraction/algorithm/mode, (eg.
 +When the B<BIO> is writable again, the same function can be called again.
 -When the B<BIO> is writeable again, the same function can be called again.
++When the return value is nonnegative, the storage pointed to by the B<usage>,
+-When the return value is non-negative, the storage pointed to by the B<usage>,
++When using a nonblocking socket, nothing is to be done, but select() can be
+-When using a non-blocking socket, nothing is to be done, but select() can be
++When using nonblocking sockets, the function call performing the handshake
+-When using non-blocking sockets, the function call performing the handshake
++whether initialisation has been completed for this BIO or not. A nonzero value
+-whether initialisation has been completed for this BIO or not. A non-zero value
++which must be encoded in the preferred name syntax described
 +will ignore them. Therefore, it is possible for no more bytes to be readable from
 -will ignore them. Therefore it is possible for no more bytes to be readable from
 +with a dot (e.g. ".example.com"), it will be matched by a certificate
 -with a dot (e.g ".example.com"), it will be matched by a certificate
--With the DER library, this is the correspoding code, given two OpenSSL
-+With the DER library, this is the corresponding code, given two OpenSSL
-+    won't resume sessions. Fixed in 1.0.0n-dev
--    wont resume sessions. Fixed in 1.0.0n-dev
++with a filename of the form I<hash>.I<N> for a certificate, or
+-with a file name of the form I<hash>.I<N> for a certificate, or
 +work with certain DSA_METHOD implementations (e.g. from an ENGINE module
 -work with certain DSA_METHOD implementations (eg. from an ENGINE module
 +work with certain RSA_METHOD implementations (e.g. from an ENGINE module
 -work with certain RSA_METHOD implementations (eg. from an ENGINE module
--"x448" repsectively for those algorithms. This is only present for consistency
-+"x448" respectively for those algorithms. This is only present for consistency
 -X509_STORE_CTX_get0_chain() returns a the internal pointer used by the
 +X509_STORE_CTX_get0_chain() returns the internal pointer used by the
-+X509_STORE_CTX_new() returns a newly allocates context or B<NULL> is an
++X509_STORE_CTX_get_error_depth() returns a nonnegative error depth.
+-X509_STORE_CTX_get_error_depth() returns a non-negative error depth.
++X509_STORE_CTX_new() returns a newly allocated context or B<NULL> if an
 -X509_STORE_CTX_new() returns an newly allocates context or B<NULL> is an
-+`xxxx`, and an option to disable it:
@gustafn
Copy link
Contributor Author

@gustafn gustafn commented Jul 15, 2020

Some of these replacements seem ok, they preexisted on master (like time stamp -> timestamp), but others, most notably the changes non-blocking -> nonblocking and non-negative -> nonnegative appear to be new.

As indicated in the commit message, i have additionally introduced changes are due to the conventions of the Linux man page project [1]. The change non-blocking -> nonblocking is explicitly mentioned in the section "Hyphenation with multi, non, pre, re, sub, and so on". I was just restricting the changes to the one explicitly mentioned. One more of frequent change was from zeroes -> zeros.

I am in not way religious on these topics. I had the impression that OpenSSL is trying to follow the rules of the Linux man project. If you prefer some of the rules left out, just let me know, and i will undo it. It would certainly make sense to document the agreed on rule set somewhere (maybe in "find-doc-nits").

it seems like you made the corrections in the doc directory only, but there are also some misspellings in source code comments.

Of course, there are many. I have not worked on the source files yet. My goal was first to get a deeper understanding of what's wanted and what's not (e.g. by this pull request) before I dig into this (on the master branch).

[1] https://man7.org/linux/man-pages/man7/man-pages.7.html

@richsalz
Copy link
Contributor

@richsalz richsalz commented Jul 15, 2020

It would be nice if you considered updating find-doc-nits to capture the preferred spelling of things you changed.

@gustafn
Copy link
Contributor Author

@gustafn gustafn commented Jul 15, 2020

update find-doc-nits
I can do so for the common changes (you might have notices, i've done so already for "aka" on master). When i do so, there will be no guarantees on false-positive changes that the script will find.

Does this still make sense for the OpenSSL_1_1_1-stable branch?

@richsalz
Copy link
Contributor

@richsalz richsalz commented Jul 15, 2020

any effort to prevent "backsliding" is good, thanks.

@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 15, 2020

I am in not way religious on these topics.

Sorry, maybe my statement was a bit misunderstandable: I am not opposed to your suggested changes and you gave a good reason for making them. I was just a little bit irritated by the fact that your backport introduces new corrections which are not on master (yet). So if you don't mind the effort, I would be happy to see a pull request on master which applies the same corrections, too.

@gustafn
Copy link
Contributor Author

@gustafn gustafn commented Jul 15, 2020

I've applied the changes as suggested by the Linux Documentation Project to the master branch and updated the doc-nits, .... after rebasing my fork to the current version, but strangely enough, GitHub has greyed out the "create pull" request button.

image

Maybe it is too late already for me to see the obvious. The easiest is probably to delete my fork and apply the changes to a fresh fork, but i am afraid, that will kill the current pull request for the 1.1.1 branch, which is still open..... or i can create another for another organization. Any quick recommendation?

@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 16, 2020

I'm not sure. But maybe it's because your gustafn-master branch (see below) contains merge commits.

~/src/openssl$ git fetch https://github.com/gustafn/openssl.git master
remote: Enumerating objects: 250, done.
remote: Counting objects: 100% (211/211), done.
remote: Compressing objects: 100% (18/18), done.
remote: Total 109 (delta 98), reused 102 (delta 91), pack-reused 0
Receiving objects: 100% (109/109), 14.73 KiB | 4.91 MiB/s, done.
Resolving deltas: 100% (98/98), completed with 79 local objects.
From https://github.com/gustafn/openssl
 * branch                  master     -> FETCH_HEAD
~/src/openssl$ git checkout -b gustafn-master FETCH_HEAD
Switched to a new branch 'gustafn-master'
~/src/openssl$ git log --oneline gustafn-master master   

41bd6bc060 (HEAD -> gustafn-master) Align documentation with recommendation of the Linux Documentation Project
e8e6fa4d9c Merge branch 'master' of https://github.com/gustafn/openssl
252d52c63b revised version for pull request
5ff9aa2b70 fixed typos and repeated words CLA: trivial
c565301dca Merge remote-tracking branch 'upstream/master'
55affcadbe (origin/master, origin/HEAD, github/master, github/gh-2067, master) Configure: fix minor typo in apitable comment
@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 16, 2020

Also, I would recommend to always create a dedicated topic branch for every pull request, instead of reusing your master or OpenSSL_1_1_1-stable branch. This might be another reason why GitHub might be confused.

@gustafn
Copy link
Contributor Author

@gustafn gustafn commented Jul 16, 2020

yes, you are right. Created a new branch and added an additional pull request (#12460)

@mspncp
mspncp approved these changes Jul 16, 2020
Copy link
Contributor

@mspncp mspncp left a comment

LGTM

gustafn added a commit to gustafn/openssl that referenced this pull request Jul 17, 2020
This change applies the recommendation of the Linux Documentation Project
to the documentation files of OpenSSL. Additionally, util/find-doc-nits
was updated accordingly.

The change follows a suggestion of mspncp on openssl#12370
and incoporates the requested changes on the pull request
@mspncp mspncp force-pushed the gustafn:OpenSSL_1_1_1-stable branch to 0642972 Jul 20, 2020
@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 20, 2020

@gustafn since your CLA has now been filed, I amended your commit to remove the 'CLA: trivial' tag from the commit message (see 0642972) and force-pushed the commit without tree changes. (No further action from you is required, the pull request is simply waiting for a second approval.)

openssl-machine pushed a commit that referenced this pull request Jul 22, 2020
This change applies the recommendation of the Linux Documentation Project
to the documentation files of OpenSSL. Additionally, util/find-doc-nits
was updated accordingly.

The change follows a suggestion of mspncp on #12370
and incoporates the requested changes on the pull request

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from #12460)
@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 23, 2020

ping

Copy link
Contributor

@paulidale paulidale left a comment

Look good!

@openssl-machine
Copy link

@openssl-machine openssl-machine commented Jul 24, 2020

This pull request is ready to merge

openssl-machine pushed a commit that referenced this pull request Jul 24, 2020
Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from #12370)
@mspncp
Copy link
Contributor

@mspncp mspncp commented Jul 24, 2020

Merged to 1.1.1. in 6328d36, thank you!

@mspncp mspncp closed this Jul 24, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

6 participants