Subject: Re: more OpenSSL man pages issues
To: None <firstname.lastname@example.org>
From: Igor Sobrado <email@example.com>
Date: 08/09/2005 11:41:47
I worked a bit on these issues this night. As a fix to these problems,
1. Changing the name of man pages for functions of the crypto library
from openssl_*.<section> to *.<section> (removing the openssl_ sufix)
The name of the manual pages should be exactly the name of the function
2. Following the MH/nmh style for manual pages of commands to the
openssl(1) command line tool. Let me explain briefly my proposal:
MH/nmh is a MUA that we can consider as a set of 30, or so, commands.
The main page for this MUA (e.g., nmh(1)) has a brief description to
each command and each command has its own man page. openssl(1) has
exactly the same structure:
asn1parse Parse an ASN.1 sequence.
ca Certificate Authority (CA) Management.
ciphers Cipher Suite Description Determination.
crl Certificate Revocation List (CRL) Management.
crl2pkcs7 CRL to PKCS#7 Conversion.
dgst Message Digest Calculation.
We can rename, we say, openssl_crl2pkcs7(1) to simply crl2pkcs7(1)
and not changing the synopsis to the command "openssl crl2pkcs7..."
The only risk is that, perhaps, there are collisions between the
names of these commands and other man pages in the same section
of the on-line manual.
In short, there is no reason for starting each man page with openssl_
if the function names and commands to openssl(1) do not start with
the same suffix.
I will greatly appreciate any feedback on this issue.