Subject: more OpenSSL man pages issues
To: None <netbsd-docs@netbsd.org>
From: Igor Sobrado <igor@string1.ciencias.uniovi.es>
List: netbsd-docs
Date: 08/08/2005 19:57:19
Hello.
Again, OpenSSL has an odd behaviour in the library functions documentation.
Take a look at this example taken from a NetBSD/i386 2.0.2 mail server
in our Campus:
----------------------
$ man -k blowfish
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt, BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options (3) - Blowfish encryption
$ man blowfish
man: no entry for blowfish in the manual.
$ man BF_set_key
man: no entry for BF_set_key in the manual.
[...]
----------------------
But if we know that these functions are in OpenSSL...
----------------------
$ man openssl_blowfish
^^^^^^^^
blowfish(3) OpenSSL blowfish(3)
NAME
blowfish, BF_set_key, BF_encrypt, BF_decrypt, BF_ecb_encrypt,
BF_cbc_encrypt, BF_cfb64_encrypt, BF_ofb64_encrypt, BF_options - Blow-
fish encryption
LIBRARY
libcrypto, -lcrypto
SYNOPSIS
[...]
----------------------
Can I suggest changing the name of the manual page and its links removing
the openssl_ sufix from it? (changing the name of the functions is NOT an
option!)
I submitted a related PR (misc/29998, this PR is open yet) in april related
with the OpenSSL documentation. I certainly disagree about how the OpenSSL
man pages are named.
For example:
"openssl_s_server" is the man page for "openssl s_server", a command
to the openssl(1) command line tool. It is not clear how naming this
manual page, and it is too long to be a section in the openssl(1) command
line tool man page.
Certainly, it is not obvious how writing documentation for this complex
toolkit. But I heartly believe that some changes (and fixes in the
references to manual pages) are required.
I will be glad to open a new PR or appending information to misc/29998
to fix these issues, but it is not obvious how fixing some references
to OpenSSL man pages.
I will be glad if someone has any suggestion.
Cheers,
Igor.