Multiple (same) sets of man pages

[Daniel Eischen]

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@ 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.

-- 
Dan Eischen