TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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