From 6e4618a0d7e84e70703d546a194df887fd624727 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Fri, 4 Oct 2019 17:09:19 -0400 Subject: [PATCH] Fix L<> entries without sections Add sections (almost always "(3)" to L<> references that were missing them. Among other things, this Fixes: #10226 Also remove two references to non-existant manpages that have never existed, and with the 3.0 structure, are unlikely to do so. Reviewed-by: Tomas Mraz Reviewed-by: Richard Levitte (Merged from https://github.com/openssl/openssl/pull/10240) --- doc/internal/man3/evp_generic_fetch.pod | 2 +- doc/internal/man3/ossl_param_bld_init.pod | 2 +- doc/man1/openssl-ciphers.pod | 2 +- doc/man1/openssl-pkcs8.pod.in | 1 - doc/man1/tsget.pod | 6 +++--- doc/man3/BIO_get_data.pod | 2 +- doc/man3/BIO_meth_new.pod | 8 ++++---- doc/man3/BIO_push.pod | 2 +- doc/man3/BIO_should_retry.pod | 2 +- doc/man3/CMS_get0_type.pod | 3 ++- doc/man3/CTLOG_STORE_new.pod | 2 +- doc/man3/DSA_meth_new.pod | 3 +-- doc/man3/DSA_set_method.pod | 2 +- doc/man3/EVP_CIPHER_meth_new.pod | 2 +- doc/man3/EVP_EncryptInit.pod | 2 +- doc/man3/EVP_PKEY_new.pod | 8 ++++---- doc/man3/EVP_set_default_properties.pod | 2 +- doc/man3/OSSL_CMP_CTX_new.pod | 3 ++- doc/man3/OSSL_STORE_expect.pod | 2 +- doc/man3/RSA_meth_new.pod | 3 +-- doc/man3/SCT_print.pod | 2 +- doc/man3/SSL_CTX_set_client_hello_cb.pod | 2 +- doc/man3/SSL_CTX_set_ctlog_list_file.pod | 2 +- doc/man3/SSL_CTX_set_session_ticket_cb.pod | 4 ++-- doc/man3/SSL_alloc_buffers.pod | 2 +- doc/man3/SSL_read_early_data.pod | 2 +- doc/man3/o2i_SCT_LIST.pod | 4 ++-- doc/man5/x509v3_config.pod | 2 +- doc/man7/EVP_KDF-KRB5KDF.pod | 4 ++-- doc/man7/EVP_KDF-SSHKDF.pod | 2 +- util/find-doc-nits | 18 ++++++++++++++++++ 31 files changed, 60 insertions(+), 43 deletions(-) diff --git a/doc/internal/man3/evp_generic_fetch.pod b/doc/internal/man3/evp_generic_fetch.pod index c4734394bb..4cff97def8 100644 --- a/doc/internal/man3/evp_generic_fetch.pod +++ b/doc/internal/man3/evp_generic_fetch.pod @@ -252,7 +252,7 @@ And finally, the library functions: =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/internal/man3/ossl_param_bld_init.pod b/doc/internal/man3/ossl_param_bld_init.pod index 062e2c293c..2fb7c4f359 100644 --- a/doc/internal/man3/ossl_param_bld_init.pod +++ b/doc/internal/man3/ossl_param_bld_init.pod @@ -178,7 +178,7 @@ public key. =head1 SEE ALSO -L, L +L, L =head1 HISTORY diff --git a/doc/man1/openssl-ciphers.pod b/doc/man1/openssl-ciphers.pod index ed8e1a95a5..8ba80ba15d 100644 --- a/doc/man1/openssl-ciphers.pod +++ b/doc/man1/openssl-ciphers.pod @@ -149,7 +149,7 @@ cipher list in order of encryption algorithm key length. The cipher string B<@SECLEVEL>=I can be used at any point to set the security level to I, which should be a number between zero and five, inclusive. -See L for a description of what each level means. +See L for a description of what each level means. The cipher list can be prefixed with the B keyword, which enables the default cipher list as defined below. Unlike cipher strings, diff --git a/doc/man1/openssl-pkcs8.pod.in b/doc/man1/openssl-pkcs8.pod.in index c9d8b9c5a8..72717f2147 100644 --- a/doc/man1/openssl-pkcs8.pod.in +++ b/doc/man1/openssl-pkcs8.pod.in @@ -77,7 +77,6 @@ file in a format specified by B<-inform>. The output file will be encrypted PKCS#8 format using the specified encryption parameters unless B<-nocrypt> is included. - =item B<-traditional> When this option is present and B<-topk8> is not a traditional format private diff --git a/doc/man1/tsget.pod b/doc/man1/tsget.pod index 6e013b9e68..0287bc94be 100644 --- a/doc/man1/tsget.pod +++ b/doc/man1/tsget.pod @@ -24,7 +24,7 @@ B<-h> I =head1 DESCRIPTION This command can be used for sending a timestamp request, as specified -in B, to a timestamp server over HTTP or HTTPS and storing the +in RFC 3161, to a timestamp server over HTTP or HTTPS and storing the timestamp response in a file. It cannot be used for creating the requests and verifying responses, you have to use L to do that. This command can send several requests to the server without closing the TCP @@ -121,7 +121,7 @@ The name of an EGD socket to get random data from. (Optional) =item I ... -List of files containing B DER-encoded timestamp requests. If no +List of files containing RFC 3161 DER-encoded timestamp requests. If no requests are specified only one request will be sent to the server and it will be read from the standard input. (Optional) @@ -188,7 +188,7 @@ example: L, L, L, -L +L =head1 COPYRIGHT diff --git a/doc/man3/BIO_get_data.pod b/doc/man3/BIO_get_data.pod index 31c4635748..aeb6b1c7e9 100644 --- a/doc/man3/BIO_get_data.pod +++ b/doc/man3/BIO_get_data.pod @@ -47,7 +47,7 @@ BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag. =head1 SEE ALSO -L, L +L, L =head1 HISTORY diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod index 9045d16777..b2e2c24692 100644 --- a/doc/man3/BIO_meth_new.pod +++ b/doc/man3/BIO_meth_new.pod @@ -60,7 +60,7 @@ BIO_meth_set_callback_ctrl - Routines to build up BIO methods The B type is a structure used for the implementation of new BIO types. It provides a set of functions used by OpenSSL for the implementation -of the various BIO capabilities. See the L page for more information. +of the various BIO capabilities. See the L page for more information. BIO_meth_new() creates a new B structure. It should be given a unique integer B and a string that represents its B. @@ -72,7 +72,7 @@ include B and B. Filter BIOs should have a type which have the "filter" bit set (B). Source/sink BIOs should have the "source/sink" bit set (B). File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the -"descriptor" bit set (B). See the L page for +"descriptor" bit set (B). See the L page for more information. BIO_meth_free() destroys a B structure and frees up any memory @@ -108,7 +108,7 @@ application calling BIO_gets(). The parameters for the function have the same meaning as for BIO_gets(). BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for -processing ctrl messages in the BIO respectively. See the L page for +processing ctrl messages in the BIO respectively. See the L page for more information. This function will be called in response to the application calling BIO_ctrl(). The parameters for the function have the same meaning as for BIO_ctrl(). @@ -146,7 +146,7 @@ The B functions return the corresponding function pointers. =head1 SEE ALSO -L, L, L, L, L +L, L, L, L, L =head1 HISTORY diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod index c5919f3cfd..236ac480e0 100644 --- a/doc/man3/BIO_push.pod +++ b/doc/man3/BIO_push.pod @@ -71,7 +71,7 @@ be written to B as before. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/BIO_should_retry.pod b/doc/man3/BIO_should_retry.pod index 686eef1f04..25d3f2e230 100644 --- a/doc/man3/BIO_should_retry.pod +++ b/doc/man3/BIO_should_retry.pod @@ -128,7 +128,7 @@ BIO_get_retry_reason() returns the reason for a special condition. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/CMS_get0_type.pod b/doc/man3/CMS_get0_type.pod index 986154fc71..12c2e650a8 100644 --- a/doc/man3/CMS_get0_type.pod +++ b/doc/man3/CMS_get0_type.pod @@ -20,7 +20,8 @@ an ASN1_OBJECT pointer. An application can then decide how to process the CMS_ContentInfo structure based on this value. CMS_set1_eContentType() sets the embedded content type of a CMS_ContentInfo -structure. It should be called with CMS functions (such as L, L) +structure. It should be called with CMS functions (such as L, +L) with the B flag and B the structure is finalised, otherwise the results are undefined. diff --git a/doc/man3/CTLOG_STORE_new.pod b/doc/man3/CTLOG_STORE_new.pod index 24919c539b..5b5d8a1ba6 100644 --- a/doc/man3/CTLOG_STORE_new.pod +++ b/doc/man3/CTLOG_STORE_new.pod @@ -25,7 +25,7 @@ logs). The list can be loaded from one or more files and then searched by LogID CTLOG_STORE_new() creates an empty list of CT logs. This is then populated by CTLOG_STORE_load_default_file() or CTLOG_STORE_load_file(). CTLOG_STORE_load_default_file() loads from the default file, which is named -"ct_log_list.cnf" in OPENSSLDIR (see the output of L). This can be +"ct_log_list.cnf" in OPENSSLDIR (see the output of L). This can be overridden using an environment variable named "CTLOG_FILE". CTLOG_STORE_load_file() loads from a caller-specified file path instead. Both of these functions append any loaded CT logs to the CTLOG_STORE. diff --git a/doc/man3/DSA_meth_new.pod b/doc/man3/DSA_meth_new.pod index bdf3f293d4..c5e6ccd052 100644 --- a/doc/man3/DSA_meth_new.pod +++ b/doc/man3/DSA_meth_new.pod @@ -88,8 +88,7 @@ DSA_meth_set_keygen - Routines to build up DSA methods The B type is a structure used for the provision of custom DSA implementations. It provides a set of functions used by OpenSSL for the -implementation of the various DSA capabilities. See the L page for more -information. +implementation of the various DSA capabilities. DSA_meth_new() creates a new B structure. It should be given a unique B and a set of B. The B should be a NULL terminated diff --git a/doc/man3/DSA_set_method.pod b/doc/man3/DSA_set_method.pod index f5c64ef393..0895e7ad0b 100644 --- a/doc/man3/DSA_set_method.pod +++ b/doc/man3/DSA_set_method.pod @@ -49,7 +49,7 @@ be released during the change. It is possible to have DSA keys that only work with certain DSA_METHOD implementations (eg. from an ENGINE module that supports embedded hardware-protected keys), and in such cases attempting to change the DSA_METHOD for the key can have unexpected -results. See L for information on constructing custom DSA_METHOD +results. See L for information on constructing custom DSA_METHOD objects; DSA_new_method() allocates and initializes a DSA structure so that B diff --git a/doc/man3/EVP_CIPHER_meth_new.pod b/doc/man3/EVP_CIPHER_meth_new.pod index 8a6a4b99de..272e80115c 100644 --- a/doc/man3/EVP_CIPHER_meth_new.pod +++ b/doc/man3/EVP_CIPHER_meth_new.pod @@ -234,7 +234,7 @@ respective B function. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/EVP_EncryptInit.pod b/doc/man3/EVP_EncryptInit.pod index 31e2fdeaf0..46e6a42a28 100644 --- a/doc/man3/EVP_EncryptInit.pod +++ b/doc/man3/EVP_EncryptInit.pod @@ -456,7 +456,7 @@ EVP_CIPHER_CTX_rand_key() returns 1 for success. All algorithms have a fixed key length unless otherwise stated. -Refer to L for the full list of ciphers available through the EVP +Refer to L for the full list of ciphers available through the EVP interface. =over 4 diff --git a/doc/man3/EVP_PKEY_new.pod b/doc/man3/EVP_PKEY_new.pod index 8b3b012b1c..3a2034d3dc 100644 --- a/doc/man3/EVP_PKEY_new.pod +++ b/doc/man3/EVP_PKEY_new.pod @@ -95,8 +95,8 @@ general private key without reference to any particular algorithm. The structure returned by EVP_PKEY_new() is empty. To add a private or public key to this empty structure use the appropriate functions described in -L, L, L or -L. +L, L, L or +L. =head1 RETURN VALUES @@ -109,8 +109,8 @@ EVP_PKEY_get_raw_public_key() return 1 for success and 0 for failure. =head1 SEE ALSO -L, L, L or -L +L, L, L or +L =head1 HISTORY diff --git a/doc/man3/EVP_set_default_properties.pod b/doc/man3/EVP_set_default_properties.pod index 077913c281..6231fde627 100644 --- a/doc/man3/EVP_set_default_properties.pod +++ b/doc/man3/EVP_set_default_properties.pod @@ -34,7 +34,7 @@ The latter adds an error on the error stack. =head1 SEE ALSO -L +L =head1 HISTORY diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index b4bfc546a4..96d6841fb2 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -532,7 +532,8 @@ CertRepMessage or Revocation Response or error message, or NULL if unset. OSSL_CMP_CTX_get_failInfoCode() returns the error code from the failInfo field of the last received CertRepMessage or Revocation Response or error message. -This is a bit field and the flags for it are specified in L. +This is a bit field and the flags for it are specified in the header file +F<< >>. The flags start with OSSL_CMP_CTX_FAILINFO, for example: OSSL_CMP_CTX_FAILINFO_badAlg. Returns -1 if the failInfoCode field is unset. diff --git a/doc/man3/OSSL_STORE_expect.pod b/doc/man3/OSSL_STORE_expect.pod index 1a270c8490..ac414e9701 100644 --- a/doc/man3/OSSL_STORE_expect.pod +++ b/doc/man3/OSSL_STORE_expect.pod @@ -32,7 +32,7 @@ grained search of objects. OSSL_STORE_supports_search() checks if the loader of the given OSSL_STORE context supports the given search type. -See L for information on the +See L for information on the supported search criterion types. OSSL_STORE_expect() and OSSL_STORE_find I be called before the first diff --git a/doc/man3/RSA_meth_new.pod b/doc/man3/RSA_meth_new.pod index 10eb3e754d..100c64cbce 100644 --- a/doc/man3/RSA_meth_new.pod +++ b/doc/man3/RSA_meth_new.pod @@ -125,8 +125,7 @@ RSA_meth_get_multi_prime_keygen, RSA_meth_set_multi_prime_keygen The B type is a structure used for the provision of custom RSA implementations. It provides a set of functions used by OpenSSL -for the implementation of the various RSA capabilities. See the L -page for more information. +for the implementation of the various RSA capabilities. RSA_meth_new() creates a new B structure. It should be given a unique B and a set of B. The B should be a diff --git a/doc/man3/SCT_print.pod b/doc/man3/SCT_print.pod index ead151b99a..c7ace453af 100644 --- a/doc/man3/SCT_print.pod +++ b/doc/man3/SCT_print.pod @@ -16,7 +16,7 @@ Prints Signed Certificate Timestamps in a human-readable way =head1 DESCRIPTION -SCT_print() prints a single Signed Certificate Timestamp (SCT) to a L in +SCT_print() prints a single Signed Certificate Timestamp (SCT) to a B in a human-readable format. SCT_LIST_print() prints an entire list of SCTs in a similar way. A separator can be specified to delimit each SCT in the output. diff --git a/doc/man3/SSL_CTX_set_client_hello_cb.pod b/doc/man3/SSL_CTX_set_client_hello_cb.pod index 002e90f827..f70b147fc5 100644 --- a/doc/man3/SSL_CTX_set_client_hello_cb.pod +++ b/doc/man3/SSL_CTX_set_client_hello_cb.pod @@ -110,7 +110,7 @@ SSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure =head1 SEE ALSO L, L, -L +L =head1 HISTORY diff --git a/doc/man3/SSL_CTX_set_ctlog_list_file.pod b/doc/man3/SSL_CTX_set_ctlog_list_file.pod index d99659ba9e..31f82dc51c 100644 --- a/doc/man3/SSL_CTX_set_ctlog_list_file.pod +++ b/doc/man3/SSL_CTX_set_ctlog_list_file.pod @@ -24,7 +24,7 @@ See L for the file format. =head1 NOTES These functions will not clear the existing CT log list - it will be appended -to. To replace the existing list, use L first. +to. To replace the existing list, use L first. If an error occurs whilst parsing a particular log entry in the file, that log entry will be skipped. diff --git a/doc/man3/SSL_CTX_set_session_ticket_cb.pod b/doc/man3/SSL_CTX_set_session_ticket_cb.pod index 409dfc6ed8..8cdb88cc55 100644 --- a/doc/man3/SSL_CTX_set_session_ticket_cb.pod +++ b/doc/man3/SSL_CTX_set_session_ticket_cb.pod @@ -43,7 +43,7 @@ decryption has been attempted and any session ticket application data is available. If ticket decryption was successful then the B argument contains the session data. The B and B arguments identify the key used to decrypt the session ticket. The B argument is the result of the -ticket decryption. See the L section below for further details. The value +ticket decryption. See the L section below for further details. The value of B is the same as that given to SSL_CTX_set_session_ticket_cb(). The B callback is defined as type B. @@ -168,7 +168,7 @@ failure. The B callback must return 1 to continue the connection. A return of 0 will terminate the connection with an INTERNAL_ERROR alert. -The B callback must return a value as described in L above. +The B callback must return a value as described in L above. =head1 SEE ALSO diff --git a/doc/man3/SSL_alloc_buffers.pod b/doc/man3/SSL_alloc_buffers.pod index 1bebeeddc9..b6ce1d9075 100644 --- a/doc/man3/SSL_alloc_buffers.pod +++ b/doc/man3/SSL_alloc_buffers.pod @@ -53,7 +53,7 @@ SSL_alloc_buffers(). L, L, L, L, -L +L =head1 COPYRIGHT diff --git a/doc/man3/SSL_read_early_data.pod b/doc/man3/SSL_read_early_data.pod index 416feebbe6..4f1593638c 100644 --- a/doc/man3/SSL_read_early_data.pod +++ b/doc/man3/SSL_read_early_data.pod @@ -65,7 +65,7 @@ yet completed the authentication stage of the handshake. Early data has weaker security properties than other data sent over an SSL/TLS connection. In particular the data does not have forward secrecy. There are also -additional considerations around replay attacks (see L +additional considerations around replay attacks (see L below). For these reasons extreme care should be exercised when using early data. For specific details, consult the TLS 1.3 specification. diff --git a/doc/man3/o2i_SCT_LIST.pod b/doc/man3/o2i_SCT_LIST.pod index e7ecfae1dc..1c3468a132 100644 --- a/doc/man3/o2i_SCT_LIST.pod +++ b/doc/man3/o2i_SCT_LIST.pod @@ -19,13 +19,13 @@ decode and encode Signed Certificate Timestamp lists in TLS wire format The SCT_LIST and SCT functions are very similar to the i2d and d2i family of functions, except that they convert to and from TLS wire format, as described in -RFC 6962. See L for more information about how the parameters are +RFC 6962. See L for more information about how the parameters are treated and the return values. =head1 RETURN VALUES All of the functions have return values consistent with those stated for -L and L. +L and L. =head1 SEE ALSO diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod index 5a84be53c2..3d92c9f098 100644 --- a/doc/man5/x509v3_config.pod +++ b/doc/man5/x509v3_config.pod @@ -50,7 +50,7 @@ use is defined by the extension code itself: check out the certificate policies extension for an example. If an extension type is unsupported then the I extension syntax -must be used, see the L section for more details. +must be used, see the L section for more details. =head1 STANDARD EXTENSIONS diff --git a/doc/man7/EVP_KDF-KRB5KDF.pod b/doc/man7/EVP_KDF-KRB5KDF.pod index 08f50d1c05..6291a11d37 100644 --- a/doc/man7/EVP_KDF-KRB5KDF.pod +++ b/doc/man7/EVP_KDF-KRB5KDF.pod @@ -51,7 +51,7 @@ parameter to the L function, and MUST match the key length for the chosen cipher or an error is returned. Moreover the constant's length must not exceed the block size of the cipher. Since the KRB5KDF output length depends on the chosen cipher, calling -L to obtain the requisite length returns the correct length +L to obtain the requisite length returns the correct length only after the cipher is set. Prior to that B is returned. The caller must allocate a buffer of the correct length for the chosen cipher, and pass that buffer to the L function along @@ -94,7 +94,7 @@ RFC 3961 =head1 SEE ALSO -L, +L, L, L, L, diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index 107b289392..1f7f3a55ec 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -91,7 +91,7 @@ A context for SSHKDF can be obtained by calling: The output length of the SSHKDF derivation is specified via the I parameter to the L function. -Since the SSHKDF output length is variable, calling L +Since the SSHKDF output length is variable, calling L to obtain the requisite length is not meaningful. The caller must allocate a buffer of the desired length, and pass that buffer to the L function along with the desired length. diff --git a/util/find-doc-nits b/util/find-doc-nits index 12d832b4da..f07929f946 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -447,6 +447,24 @@ sub check { check_section_location($id, $contents, "EXAMPLES", "SEE ALSO"); } + # Make sure every link has a section. + while ( $contents =~ /$markup_re/msg ) { + my $target = $1; + next unless $target =~ /^L, or + next if $target =~ /::/; # links to a Perl module, or + next if $target =~ m@L$@; # it has a section, or + next if $target =~ m@\([1357]\)/.*>$@; # it has a section/anchor + err($id, "Section missing in $target") + } + # Check for proper in-man-3 API links. + while ( $contents =~ /L<([^>]*)\(3\)(?:\/.*)?>/g ) { + my $target = $1; + err($id, "Bad L<$target>") + unless $target =~ /^[_[:alpha:]][_[:alnum:]]*$/ + } + unless ( $contents =~ /=for openssl generic/ ) { if ( $filename =~ m|man3/| ) { name_synopsis($id, $filename, $contents); -- 2.25.1