On Tue, 09 Aug 2005, Igor Sobrado wrote:
>   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:

No, there's a huge difference.  In the case of nmh, each command is
implemented via an executable in the PATH, and each nmh command is also
a shell command.  One uses shell commands like "scan", not "nmh scan",
so it's quite appropriate for there to be a scan(1) man page.

But in the case of openssl, most openssl commands are not also shell
commands, and do not have executable files in the default PATH.  One
uses shell commands like "openssl ca", not just "ca".  So it's less
obvious that there should be a ca(1) man page (and I argue below that
there should not).

>        STANDARD COMMANDS
> 
>        asn1parse Parse an ASN.1 sequence.
> 
>        ca        Certificate Authority (CA) Management.
> 
>        ciphers   Cipher Suite Description Determination.
	 [...]

These are commands that one invokes from a shell like "openssl asn1parse
-foo bar", not like "asn1parse -foo bar".  So I think it's wrong to get
to the man page via "man asn1parse", and right to get to the man page
via "man openssl".  If the openssl man page wants to split itself up
into a different page per command, then I'd like the pages all to be
related somehow, and using "man openssl_asn1parse" to get to the man
page for the "openssl asn1parse command seems fine to me.  (Note that
it's not the "asn1parse" command; there is no asn1parse anywhere in the
default PATH.)

I dislike namespace pollution in general, so I prefer not having "man
speed", "man passwd", "man verify" refer to openssl-specific things
when it's quite obvious that those are generic terms.  I also prefer
not having "man ca" refer to something openssl-specific, because "ca"
is a short name that might be better used to refer to something else in
future.  I counted 81 different commands in the openssl(1) man page,
and each of those could potentially have its own man page in the future
(though there are only 35 openssl_* man pages today).  This is another
reason to use "man openssl_asn1parse" and "man openssl_passwd" instead
of "man asn1parse" and "man passwd".

The above arguments implies that the "SEE ALSO" section of the
openssl(1) man page should refer to "openssl_asn1parse(1)", and that the
"NAME" section of the openssl_asn1parse(1) man page should say "openssl
asn1parse", not just "asn1parse".

--apb (Alan Barrett)