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: unix man pages From:Sally Derrick <sally -at- RUSHMORE -dot- TIVOLI -dot- COM> Date:Tue, 26 Dec 1995 07:41:02 -0600
Caryn Rizell writes:
> Item Subject: cc:Mail Text
> Do any of you write unix man pages? If so, have you found a way to author
> the man pages in something other than nroff, then convert to nroff? Are
> there any tools for converting to nroff format?
The writer's at my company have been plagued with this problem for TOO
long. We have the added pleasure of providing hardcopy as well as the
troff. With our total product line we easily have 2,000 man pages.
For a while we tried maintaining separate source files. Obviously not
the right answer. Then we tried maintaining them in troff and
importing them to Frame. We used both the filter provided in Frame and
a home-grown filter. The amount of clean-up required was HUGE!
We finally decided to take the process the other way - write them in
Frame and convert to troff. I sent a request for filters to this list.
About the only one I heard about was (I believe) called FM2ASCII.
My biggest problem with this was it converted a single Frame file
into a single ASCII file. I would still have to break the ASCII file
into separate man page files and add the required .TH line at the
beginning of each man page file. Seemed like it was still too much
What we used the last time was Quadralay's WebWorks Publisher. I
know, that's a Frame-to-HTML converter. WebWorks allows you to modify
or create your own HTML tags, which a mapped to Frame para tags. I
simply created my own tags in WebWorks that used troff macros instead
of HTML codes. Because it's a Web conversion tool, it lets you specify
which Frame para tag should cause a new file. It also lets you
specify text to add at the beginning of each file (the .TH line).
This method worked very well with one exception of definition
lists. There was no way to tell WebWorks that a tab in this particular
Frame component needs a line feed in the troff file. This was a bit of
a pain in the arguments/options section of the man pages. It was a
small thing compared to the amount of clea-up we've had to do in the
Although that process worked fairly well, I think we've finally found
the ultimate answer to this problem. We're not providing troff
anymore! Our new help system will be Web-based and all man pages will
be done in HTML. I'm finally free from troff!!! Hurray!! Let there
be dancing in the streets! :-)
Tivoli Systems Inc.
sally -at- tivoli -dot- com