Subject: Re: more OpenSSL man pages issues
To: None <>
From: Igor Sobrado <>
List: netbsd-docs
Date: 08/09/2005 11:41:47
Hi again!

I worked a bit on these issues this night.  As a fix to these problems,
I suggest:

  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
     it describes.

  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.