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.