[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openssl-dev
Subject:    Re: [openssl.org #370] Duplicate manuals in 0.9.7-stable
From:       "Richard Levitte - VMS Whacker via RT" <rt () openssl ! org>
Date:       2002-11-29 14:53:36
[Download RAW message or body]


In message <rt-370-2654.11.6987356727891@openssl.org> on Fri, 29 Nov 2002 15:35:29 \
+0100 (MET), "Lutz Jaenicke via RT" <rt@openssl.org> 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 \ LeViMS@stacken.kth.se
Redakteur@Stacken  \ S-168 35  BROMMA  \ T: +46-8-26 52 47
                    \      SWEDEN       \ or +46-708-26 53 44
Procurator Odiosus Ex Infernis                -- poei@bofh.se
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                       openssl-dev@openssl.org
Automated List Manager                           majordomo@openssl.org


[prev in list] [next in list] [prev in thread] [next in thread]