Re: Are UNIX manpages obsolete?

[Sandra Demi <Sandra_Demi -at- TRANSARC -dot- COM>]

Stuart Burnfield <slb -at- fs -dot- com -dot- au> writes:
> Sandy Demi said:
> > . . .our company has traditionally provided UNIX-style manpages for the
> > C and C++ APIs for the product.  Now that there are alternative ways
> > to provide online documentation (we also provide all our documentation
> > online in HTML), we're wondering if UNIX manpages are still necessary.


> Another option is to provide the same information in both formats.
> Normally single-sourcing like this is fool's gold, but man pages are

We already use a single source (SGML), which we then convert to both
HTML and manpage format.  Generating the manpages is not the problem;
what is causing me to reconsider our use of manpages is the addition
of C++ and Java (and possibly other languages) interfaces to the
existing C interfaces.

In my opinion, manpages don't seem to work as well with
object-oriented languages.  Typically (from what I've seen, at least),
a reference page for a class includes all the documentation for the
member functions, constructor, operators, etc., which could result in
extremely long manpages.  (We _do_ plan to continue providing manpages
for our C interfaces and for all command-line interfaces.)

The fact that we're providing the same interfaces in multiple
languages causes another problem that we have no solution for (so
far).  If there is a C++ class named "Foo" and a Java class named
"Foo", which one should the user see when they enter "man Foo"?  There
are situations in which a programmer might be using both languages,
for example, writing a Java client and a C++ server application.

Perhaps it's just wishful thinking on my part that UNIX manpages will
become obsolete... ;-)

Thanks.