In message <[EMAIL PROTECTED]> on Fri, 29 Nov 2002 15:35:29
+0100 (MET), "Lutz Jaenicke via RT" <[EMAIL PROTECTED]> said:
rt>
rt> On Fri, Nov 29, 2002 at 03:23:02PM +0100, Richard Levitte - VMS Whacker via RT
wrote:
rt> >
rt> > I just started working on making symlinks for all names in the NAME
rt> > section of every .pod file we're converting into manpages. The
rt> > benefit is that the manuals are available by function name, and users
rt> > won't have to try to guess the name of the manpage any more.
rt> >
rt> > Applying some changes on 0.9.7-stable, I get messages like this:
rt> >
rt> > installing man3/BIO_s_bio.3
rt> > ln:
"/home/levitte/cvswork/dev.openssl.org/installs/OpenSSL-0.9.7-stable/usr/local/ssl/man/man3/BIO_new_bio_pair.3":
Filen finns
rt> > installing man3/BIO_s_connect.3
rt> > ln:
"/home/levitte/cvswork/dev.openssl.org/installs/OpenSSL-0.9.7-stable/usr/local/ssl/man/man3/BIO_set_nbio.3":
Filen finns
rt> > installing man3/BIO_set_callback.3
rt> >
rt> >
rt> > "Filen finns" is swedish and means "file exists".
rt> >
rt> > The explanation is that the functions that make each of those already
rt> > existing file names are mentioned twice. For some of them, it's just
rt> > a duplication of names within the same manual, those are easy to fix
rt> > (I'm doing it as I write). Some of them are a little more
rt> > problematic, however, and I don't know right now how to best handle
rt> > them:
rt> >
rt> > grep -n -e BIO_new_bio_pair doc/crypto/*.pod /dev/null
rt> > doc/crypto/BIO_new_bio_pair.pod:5:BIO_new_bio_pair - create a new BIO pair
rt> > doc/crypto/BIO_new_bio_pair.pod:11: int BIO_new_bio_pair(BIO **bio1, size_t
writebuf1, BIO **bio2, size_t writebuf2);
rt> > doc/crypto/BIO_new_bio_pair.pod:15:BIO_new_bio_pair() creates a buffering BIO
pair based on the
rt> > doc/crypto/BIO_new_bio_pair.pod:25:BIO_new_bio_pair() does not check whether
B<bio1> or B<bio2> do point to
rt> > doc/crypto/BIO_new_bio_pair.pod:41: BIO_new_bio_pair(internal_bio, 0,
network_bio, 0);
rt> > doc/crypto/BIO_s_bio.pod:6:BIO_set_write_buf_size, BIO_get_write_buf_size,
BIO_new_bio_pair,
rt> > doc/crypto/BIO_s_bio.pod:24: int BIO_new_bio_pair(BIO **bio1, size_t writebuf1,
BIO **bio2, size_t writebuf2);
rt> > doc/crypto/BIO_s_bio.pod:76:BIO_new_bio_pair() combines the calls to BIO_new(),
BIO_make_bio_pair() and
rt> > doc/crypto/bio.pod:47:L<BIO_new_bio_pair(3)|BIO_new_bio_pair(3)>,
rt> >
rt> > grep -n -e BIO_set_nbio doc/crypto/*.pod /dev/null
rt> > doc/crypto/BIO_s_accept.pod:5:BIO_s_accept, BIO_set_nbio, BIO_set_accept_port,
BIO_get_accept_port,
rt> > doc/crypto/BIO_s_accept.pod:6:BIO_set_nbio_accept, BIO_set_accept_bios,
BIO_set_bind_mode,
rt> > doc/crypto/BIO_s_accept.pod:20: long BIO_set_nbio_accept(BIO *b, int n);
rt> > doc/crypto/BIO_s_accept.pod:72:BIO_set_nbio_accept() sets the accept socket to
blocking mode
rt> > doc/crypto/BIO_s_accept.pod:140:BIO_set_accept_port(), BIO_get_accept_port(),
BIO_set_nbio_accept(),
rt> > doc/crypto/BIO_s_connect.pod:8:BIO_set_nbio, BIO_do_connect - connect BIO
rt> > doc/crypto/BIO_s_connect.pod:27: long BIO_set_nbio(BIO *b, long n);
rt> > doc/crypto/BIO_s_connect.pod:86:BIO_set_nbio() sets the non blocking I/O flag to
B<n>. If B<n> is
rt> > doc/crypto/BIO_s_connect.pod:88:is set. Blocking I/O is the default. The call to
BIO_set_nbio()
rt> > doc/crypto/BIO_s_connect.pod:133:BIO_get_conn_ip(), BIO_get_conn_int_port(),
BIO_set_nbio() and
rt> > doc/crypto/BIO_s_connect.pod:158:BIO_set_nbio() always returns 1.
rt>
rt> Hmm. The entries in the NAME sections should be authoritative.
rt> Do we have more than one or two entries that accidently made it into
rt> the NAME sections of more than one .pod file?
Uhmm, did you look at the grep output? BIO_new_bio_pair is described
(and mentioned in the NAME section, which is the crucial culprit here)
in both BIO_new_bio_pair.pod and BIO_s_bio.pod. The same goes for
BIO_set_nbio, which is described both in BIO_s_accept.pod and
BIO_s_connect.pod.
rt> PS. While you are at it: some user proposed to create the "man" pages from
rt> "pod" during "make" instead of the "make install". Would it make sense
rt> to integrate such new behaviour with the processing you are currently
rt> doing?
I will look at it, but since it's a bit more complex, I think it's too
late for 0.9.7.
--
Richard Levitte \ Spannvägen 38, II \ [EMAIL PROTECTED]
Redakteur@Stacken \ S-168 35 BROMMA \ T: +46-8-26 52 47
\ SWEDEN \ or +46-708-26 53 44
Procurator Odiosus Ex Infernis -- [EMAIL PROTECTED]
Member of the OpenSSL development team: http://www.openssl.org/
Unsolicited commercial email is subject to an archival fee of $400.
See <http://www.stacken.kth.se/~levitte/mail/> for more info.
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
