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:Caryn Rizell <CARYN_RIZELL -at- HP-ROSEVILLE-OM2 -dot- OM -dot- HP -dot- COM> Date:Tue, 2 Jan 1996 10:36:17 -0800
Thanks for your response re using WebWorks to add the appropriate troff
tags. I would love to have more info on how you do this. Could you
provide an example tag?
Also, I am interested in your comment that you are going to produce all
your help via the web. Are you doing all unix help? Did you talk to your
customers to see what they thought of this? I am curious because we are
investigating this option, but have gotten some feedback that users aren't
quite ready for this yet. I would love to hear more about what you are
providing and how you are doing it. The web is definitely the future.
______________________________ Reply Separator _________________________________
Subject: Re: unix man pages
Author: Non-HP-TECHWR-L (TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu) at HP-Roseville,unixgw3
Date: 12/26/95 4:41 AM
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 finishing
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