Re: unix man pages

[Caryn Rizell <CARYN_RIZELL -at- HP-ROSEVILLE-OM2 -dot- OM -dot- HP -dot- COM>]

Sally:

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.

Thanks

Caryn Rizell


______________________________ 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
> 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
past.

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