> deraadt> > On Sun, 2 Apr 2000, Richard Levitte - VMS Whacker wrote:
> deraadt> >
> deraadt> > > There's another variant that was proposed here, but hasn't yet
> deraadt> > > been implemented, and it's that the section wouldn't just be a
> deraadt> > > number. Instead, something like 1ssl, 3ssl, 5ssl and 7ssl would
> deraadt> > > be used. The result is that you'd get a threads(3ssl), err(3ssl),
> deraadt> > > passwd(1ssl), rc4(3ssl).
> deraadt> >
> deraadt> > Why not openssl_passwd, openssl_err, etc?
> deraadt>
> deraadt> I think you missed the point I was making.
> deraadt>
> deraadt> Why not ERR_get_error(3)?
>
> Thing is, that man page is not just about those functions, it's the
> general description on how error codes work in OpenSSL, even how to
> extend OpenSSL itself if you want to.
I disagree. I think that the name that shows up in the top banner of
a man page is of no consequence, as long as there are no extra section
3 man pages for things which "do not exist", or "which conflict with
system provided routines".
> So actually, even if you'd
> choose one of the functions as the name of the file, the rest of them
> will also appear in the whatis (apropos?) database, along with err
> (actually, as it's written right now, with *only* err in the name, you
> won't see the function names at all, which is not quite right).
Well, in this case I think you forgot that err(3) is a man page in a
BSD system. But rand(3) is similar.
And, the links are easy to handle. I will append some chunks at the
end of our Makefile, so that you can see what I am currently doing.
If you accept the recommendations I am making, I will try to make a
larger patch. It means renaming about 15 files in the doc/crypto
directory.
Again, "err" should not be a published interface, in the same way that
FILE(3) does not exist in the section 3 man pages. (Hmm, we have a
stdio(3) man page -- I'm going to see about getting rid of that, since
there is no stdio function or variable. Gotta clean our own house at
the same time).
> So, since that page is about OpenSSL error codes and the handling of
> them, rather than just a description of the functions you use, it's
> slightly odd to have it function-based. Therefore, openssl_err is
> actually a good idea.
But it is not odd to have things function based! Regular manual pages
have been oriented that way for a very long time.
----------------------------------------
PRINTF(3) OpenBSD Programmer's Manual PRINTF(3)
NAME
printf, fprintf, sprintf, snprintf, asprintf, vprintf, vfprintf,
vsprintf, vsnprintf, vasprintf, vansprintf - formatted output conversion
SYNOPSIS
#include <stdio.h>
int
printf(const char *format, ...);
...
int
vasprintf(char **ret, const char *format, va_list ap);
DESCRIPTION
The printf() family of functions produces output according to a format as
----------------------------------------
And of course, if you "man fprintf", you'll discover that "fprintf" is
a link the "printf" man page, and voila, you've got the information
you want. And you see what the other functions are all about, and it
is nicely clustered so that you can make a programming better
decision.
As you can see, it is easy, obvious, and simple for a man page
covering a whole set of related functions to be named by the most
common of the functions it describes. For the case of err(3), a
programmer is going to learn about that entire class of functions
through ERR_get_error first -- everything which at the moment links to
err(3) in fact is telling people to look there specifically because
the function they're using documents that they should get familiar
with ERR_get_error(). So why not just link to the ERR_get_error(3)
page?
> Hmm, or rather, BOTH are good ideas. I'm suddenly getting the feeling
> that pages like err(3) should really be split in two: openssl_err(7)
> and ERR_<whatever>(3). Remember, section 7 is miscellaneous, and I
> have a hard time thinking of any other section that could be used for
> more general concept description. Theo, what do you say about that
> thought? Everyone else, what do you say? Yes, it does require a bit
> more work, but might be rewarding and perhaps give an even better
> clarity to the OpenSSL functions.
I have no problem with a section 7 man page, except that there really is
no need to force a programmer to read two man pages at the same time. All
the issues which relate to openssl errors are really pretty much the same
topic that a researcher of ERR_whatever would be searching for. So, I think
that a section 7 man page is excessive; why not carefully put all the related
> Another thing remains that you haven't said one thing about, Theo.
> Things like passwd(1), which is an OpenSSL manpage that conflicts with
> the standard passwd(1), what would you do with those? It might be a
> good thing to reconsider the 1ssl section I suggested earlier. There
> are references from openssl(1) or openssl(1ssl), whichever you'd choose...
I have no idea what to do about those. We don't even install the
extra commands yet (just openssl(1) so far) -- as they are now their
naming is very obtuse. I really think you should rename the ones that
would collide with the components which are normally included in a
unix system, or you're shooting yourself in the foot. And I suspect
that some of them will be so rarely used, that it may make sense to
build a scaffolding containing multiple commands in one. I do not
think you're going to convince a lot of Unix vendors to ship with all
those commands in /usr/bin. If it's not too late, why not make that
more sleek, so that vendors can put it in /usr/bin. I mean, it would
sure rock if openssl was included in all systems, wouldn't it?
--------------------------------------------------
First off, my (BSD'ish) Makefile contains something like this, which
describes the section 3 pages we wish to build.
MANALL= ssl.cat3 SSL_get_error.cat3 \
BN_CTX_new.cat3 OPENSSL_VERSION_NUMBER.cat3 BN_CTX_start.cat3 \
OpenSSL_add_all_algorithms.cat3 BN_add.cat3 RAND_add.cat3 BN_add_word.cat3 \
RAND_bytes.cat3 BN_bn2bin.cat3 RAND_cleanup.cat3 BN_cmp.cat3 RAND_egd.cat3 \
BN_copy.cat3 RAND_load_file.cat3 BN_generate_prime.cat3 \
RAND_set_rand_method.cat3 BN_mod_inverse.cat3 RSA_blinding_on.cat3 \
...
An implicit rule converts .pod files to .cat3 files, thus:
.PATH: ${.CURDIR}/src/doc/crypto ${.CURDIR}/src/doc/ssl ${.CURDIR}/src/doc/apps
.SUFFIXES: .pod
.pod.cat3:
( cd `dirname ${.ALLSRC}` && pod2man --section=3 --official \
--center='OpenSSL' --release="OpenBSD `uname -r`" \
`basename ${.ALLSRC}` ) | nroff -Tascii -man > ${.TARGET}
The file err.pod is not installed at all, since all (almost?) it's
contents are more specifically documented in more specific pages, ie,
ERR_get_error.pod already exists. Instead, we change all the manual
pages to instead reference ERR_get_error(3) instead, since all of them
specifically are already suggesting people read that.
Some files are named incorrectly when they install, so we rename them
when installing them, and thus avoid the implicit rule described
above:
RIPEMD160.cat3: ripemd.pod
( cp ${.ALLSRC} RIPEMD160.pm && pod2man --section=3 --official \
--center='OpenSSL' --release="OpenBSD `uname -r`" \
RIPEMD160.pm ) | nroff -Tascii -man > ${.TARGET}
When such a rename happens, some other files link to the old name; for
instance sha.pod (which we generate into SHA1.cat3 using a explicit
rule) has the following diff to rename a few links:
-L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)>
+L<RIPEMD160(3)|RIPEMD160(3)>, L<HMAC(3)|HMAC(3)>,
+L<EVP_DigestInit(3)|EVP_DigestInit(3)>
This renaming is happening because actual functions exist called
RIPEMD160(), HMAC() and SHA1(). Since they exist, their pages should
be SHA1(3) and such, not sha(3), since there is no function called
sha().
We also install various man page links, throughout our manual page
subsystem, so that you can get the page you want. For instance;
MLINKS+=BN_CTX_new.3 BN_CTX_init.3 BN_CTX_new.3 BN_CTX_free.3 \
BN_CTX_start.3 BN_CTX_get.3 BN_CTX_start.3 BN_CTX_end.3 \
BN_add.3 BN_sub.3 BN_add.3 BN_mul.3 BN_add.3 BN_div.3 \
BN_add.3 BN_sqr.3 BN_add.3 BN_mod.3 BN_add.3 BN_mod_mul.3 \
BN_add.3 BN_exp.3 BN_add.3 BN_mod_exp.3 BN_add.3 BN_gcd.3 \
BN_add_word.3 BN_sub_word.3 BN_add_word.3 BN_mul_word.3 \
BN_add_word.3 BN_div_word.3 BN_add_word.3 BN_mod_word.3 \
BN_bn2bin.3 BN_bin2bn.3 BN_bn2bin.3 BN_bn2hex.3 \
BN_bn2bin.3 BN_bn2dec.3 BN_bn2bin.3 BN_hex2bn.3 \
BN_bn2bin.3 BN_dec2bn.3 BN_bn2bin.3 BN_print.3 \
BN_bn2bin.3 BN_print_fp.3 BN_bn2bin.3 BN_bn2mpi.3 \
BN_bn2bin.3 BN_mpi2bn.3 \
BN_cmp.3 BN_ucmp.3 BN_cmp.3 BN_is_zero.3 BN_cmp.3 BN_is_one.3 \
BN_cmp.3 BN_is_word.3 BN_cmp.3 BN_is_odd.3 \
BN_copy.3 BN_dup.3 \
BN_generate_prime.3 BN_is_prime.3 \
BN_generate_prime.3 BN_is_prime_fasttest.3 \
BN_mod_mul_montgomery.3 BN_MONT_CTX_new.3 \
...
RIPEMD160.3 RIPEMD160_Init.3 RIPEMD160.3 RIPEMD160_Update.3 \
RIPEMD160.3 RIPEMD160_Final.3 \
...
There's about 300 lines of those, where for instance it says to create
a link called RIPEMD160_Init -> RIPEMD160; RIPEMD160_Update -> RIPEMD160,
etc, since RIPEMD160_Init() and RIPEMD160_Update() exist.
So if you do
% man RIPEMD160_Init
You get the RIPEMD160(3) man page, and it documents the entire family
of RIPEMD160 functions. If you want to use one, you should be aware
of the others.
All in all, what I've done here was a lot of work, and it's not
perfect yet. But the goal I think is noble. I'm learning a heck of
lot now because it is so easy to find manual pages for the various
functions. All of this is also applicable towards web reading
systems, or whatever else, especially the MLINK specification I've got
here. It is specific to our Makefiles, but for instance the renaming
and such that I am having to do now is a pain; I would be much happier
if the next release of OpenSSL had these changes in it.
If someone wants to work with me to start merging this in, I would
be very happy to do so in the next few days.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
