Re: unix man pages

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
> Hi!

> 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?

> Thanks

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 work.

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! :-)

Sally Derrick
Tivoli Systems Inc.
sally -at- tivoli -dot- com

Previous by Author: Re: Nice HTML Style Guide
Next by Author: Re: Re. Certification (sorry, its long)
Previous by Thread: Re: unix man pages
Next by Thread: Re: unix man pages

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

Sponsored Ads