Re: Multiple (same) sets of man pages

On Wed, Apr 23, 2003 at 02:42:15PM -0400, Daniel Eischen wrote:
> On Wed, 23 Apr 2003, Ruslan Ermilov wrote:
> > On Wed, Apr 23, 2003 at 02:08:40PM -0400, Daniel Eischen wrote:
> > > On Wed, 23 Apr 2003, Mike Barcroft wrote:
> > > 
> > > > Daniel Eischen <deischen_at_freebsd.org> writes:
> > > > > [ doc_at_ bcc:'d ]
> > > > > 
> > > > > With 3 threading libraries, each with a set of the same man pages,
> > > > > how should this be handled?  It doesn't make any sense to have
> > > > > all of them installed and yet it should still be possible to
> > > > > install all 3 thread libraries.
> > > > > 
> > > > > Do we need a different heirarchy for threads?
> > > > 
> > > > Ideally, they'd all document the same specification.  Perhaps there
> > > 
> > > Right, but there may be extensions in some that aren't in the
> > > others.  So those would be library-specific man pages.  Like
> > > pthread_switch_{add,delete}_np() that I believe is only supported
> > > in libc_r.  I have no plans on supporting it in libpthread
> > > since it really doesn't make sense there.  There will also be
> > > other functions available in libpthread that aren't in libc_r
> > > (and perhaps libthr).
> > > 
> > > > would be one document that discusses the pros and cons of each
> > > > implementation with instructions on enabling them.
> > > 
> > > Right, I think an overall 'man threads' should give you that.
> > > Eventually, libc_r should be deprecated so placing the common
> > > man pages in there doesn't make sense.  Of course we can ignore
> > > it until we get to that point.
> > > 
> > > I've currently got the man pages commented out of libpthread's
> > > Makefile 'cause it doesn't make sense to install them over
> > > those installed by libc_r.  I'm just raising the issue; I'll
> > > do whatever the doc guys recommend.
> > > 
> > Since libpthread and libthr aren't getting built by default,
> > this is a minor issue now.  If you're about to enable either
> > one or both, the one that is not optional (libc_r is optional)
> > should get the common manpages.  If all libraries are optional,
> > either one (most commonly used) could get the manpages, and
> > others should have .PATH to them.  Another issue is the .Lb
> > call in these manpages.  They should be fixed to give all three
> > libraries.  I will have to fix the .Lb macro first to make
> > this work.
> 
> OK, for now I'll assume libc_r is not optional and we'll
> update the man pages within there.  And as wollman suggested,
> if there are library-specific man pages, we'll add them to
> the common set of man pages and document the differences
> from the other libraries.
> 
When I fix the .Lb macro, I will let you know.


Cheers,
-- 
Ruslan Ermilov		Sysadmin and DBA,
ru_at_sunbay.com		Sunbay Software AG,
ru_at_FreeBSD.org		FreeBSD committer,
+380.652.512.251	Simferopol, Ukraine

http://www.FreeBSD.org	The Power To Serve
http://www.oracle.com	Enabling The Information Age