Re: Are UNIX manpages obsolete?

Subject: Re: Are UNIX manpages obsolete?
From: Sandra Demi <Sandra_Demi -at- TRANSARC -dot- COM>
Date: Tue, 1 Oct 1996 15:37:45 -0400

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... ;-)

*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*
Sandy Demi Transarc Corporation
demi -at- transarc -dot- com The Gulf Tower, 707 Grant St.
(412)338-4356 Pittsburgh, PA 15219

"No matter where you go... there you are." -- Buckaroo Banzai
*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*+*


Previous by Author: Re: Are UNIX manpages obsolete?
Next by Author: Tech Writing Courses
Previous by Thread: Re: Are UNIX manpages obsolete?
Next by Thread: Re: Are UNIX manpages obsolete?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads