Re: WebWorks Publisher limitations; the state of Frame Help

[Craig Sanders <csanders -at- BEST -dot- COM>]

Hi, Mark!

Comments below:

Mark Dempsey wrote:

> Craig,
>
> I've used the demo of v4.0.  The templates are, well, lame.  Unless I
> ensure each topic is no longer than one screen long, the navigation
> buttons disappear.  Compare the result to the help in your Netscape
> browser (NetHelp) and you'll see fixed navigation buttons, as well as a
> searchable index (not a separate "index" topic).

Again, what are you are looking for can be done, but it involves a bit of
programming, and also may mean you have to restrict your users to a given browser.
This is, unfortunately, due to browser idiosyncrasies, rather than Publisher.

>
>
> FYI, here's another response I received from Lydia Wong about making an
> actual help system using
> Webworks:
>
> "We are gradually making it work, but it has taken weeks of set up, and
> thousands of dollars (we hired a consultant to help us). For us, we
> think it is worth it, but it has been far more work than we anticipated.
>
> As our consultant says: "Does it work?" Yes. "Is it easy?" No, in fact,
> it's pretty hard."

I definitely agree here. Publisher is a comprehensive tool suite that can perform a
multitude of tasks. The more things an application can do, the longer the learning
curve. Consider FrameMaker for an example. Frame is probably the best technical
documentation tool available (I can hear the religious wars starting again), but you
don't learn to use it in a couple of weeks. Also, admittedly, much of the difficulty
in learning Publisher is due to less than acceptable documentation, but this is most
definitely changing.

>
>
> So call me difficult to please.  I've already asked Lydia if she'll sell
> her templates to us...
>
> Incidentally, I've not seen any templates specific to JavaHelp or Oracle
> help.  Am I missing something?

You can download these templates from ftp.quadralay.com. Look in the
wpublish\templates directory. The file names are javahelp.zip and orahelp.zip,
respectively. A note about these templates. Yes, they do convert Frame files to
JavaHelp and OracleHelp. However, neither Sun's JavaHelp or Oracle's OracleHelp are
finished products. These Publisher templates use the early release versions of these
applications, and as such, are not what they will be as finished, released products.
This is due to the current limitations of the Sun and Oracle products, rather than
Publisher.

Hope this helps,
Craig Sanders

>
>
> Craig Sanders wrote:
> >
> > Hello, Mark!
> >
> > Which version of WebWorks Publisher are you using?
> >
> > The reason I ask is that version 4.0 contains templates for a variety of online
> > help formats: HTMLHelp, WinHelp, JavaHelp, and OracleHelp. If you haven't
> > already, you might want to look at the new product.
> >
> > In response to your evaluation of Publisher:
> >
> > Mark Dempsey wrote:
> >
> > > I've been trying to get an online help system from Webworks publisher's
> > > translation of FrameMaker files with only limited success.
> > >
> > > The advantages of Webworks:
> > >
> > > 1. Much better batch processing of many files than Frame's individual
> > > file conversion to HTML.  Style construction and mapping are complex,
> > > with only rudimentary doc's, but are serviceable. You can, for example,
> > > exclude conditional text from your help file (and specify which
> > > conditions).
> >
> > I agree that Publisher affords far superior overall conversion capabilities.
> > And yes, template design is complex with poor support from the documentation
> > (this is changing as I write this). Regarding your specific comment about
> > conditional text tags: I have designed and produced single-source docs in Frame
> > that contain both classic doc material (print or straight HTML) and the
> > associated online 'Help' material. When I do my conversion runs, I simply
> > separate out the two using Publisher's conditional tag feature. This way, I can
> > use a single authoring tool and write both manual and online help material
> > concurrently.
> >
> > >
> > >
> > > 2. Excellent transformation of Frame to HTML.  Since Frame has absolute
> > > tabs, and HTML has relative tabs, you'll still have to tweak the output,
> > > though. (The solution would be to have Webworks compare tabs to rulers
> > > in Frame and make the correct substitution in the HTML output.  I'm
> > > forwarding this to Quadralay...)
> >
> > Agreed: This is a knotty problem. But this is more a limitation of HTML than of
> > Publisher. I am curious to see what Quadralay's response will be.
> >
> > >
> > >
> > > Disadvantages:
> > >
> > > 1. The output is *not* a help system as fully featured as HTMLhelp
> > > (Microsoft) or NetHelp (Netscape).  It does not contain an index, for
> > > example (unless that's one of the Frame files you converted).  NetHelp
> > > is a must for me because it requires Netscape to work (as HTMLhelp
> > > requires Internet explorer) and only Netscape is available across all
> > > UNIX platforms (IE is in beta for Solaris only, as far as I know).
> >
> > You can use the HTMLHelp template provided with Publisher 4.0 to produce true
> > HTMLHelp, including the ActiveX TOC. In fact, when you install Publisher 4.0,
> > the Microsoft HTMLHelp Workshop is also installed. This application is called
> > by Publisher when you do your conversion run and actually compiles the HTMLHelp
> > for you. However, this does not address the cross-platform compatibility issue
> > your also raised. My suggestion would be to have a look at the new JavaHelp and
> > OracleHelp templates provided with Publisher 4.0. You might also want to have a
> > look at www.quadralay.com/cdex. Therein you will find some notes about an
> > upcoming product (CD Express) that provides both a true cross-platform
> > capability, plus a client-side search engine, plus a dynamic update utility
> > using the Internet.
> >
> > >
> > >
> > > 2. The appearance of Webworks help is unnecessarily amateurish, IMHO.
> > > For example, if you have a screen that must scroll, the navigation
> > > buttons are not in a frame by themselves, so they disappear.
> >
> > Agreed. However, remember that if one frame in an HTML frameset controls
> > scrolling in another frame, you must use some methodology to maintain state
> > (that is, one frame must know what another frame is doing). Characteristically,
> > this is done using cookies. You can do this, and you can set up Publisher to
> > automatically incorporate the required scripting (I've done it), but there are
> > some nasty gotchas waiting in the bushes. The worst is that IE 4.0 does not
> > support cookies in a disk-based environment. If you want, have a look at
> > http://www.alchemy-computing.co.uk/index.htm?/joust_intro.htm for a truly slick
> > implementation of just this. I modified the public domain code provided at this
> > site to produce just what you are talking about. All of the JavaScript required
> > for the implementation was designed into my Publisher templates, and
> > incorporated in the HTML automatically at the time of conversion.
> >
> > >
> > >
> > > 3. You cannot use Webworks output for NetHelp (a real help system with a
> > > frame for navigation buttons, and an index) without some extraordinary
> > > tweaking (so far, more than I'm willing to do).
> >
> > Agreed. I believe the decision to do this was based on Netscape's action in
> > dissolving the NetHelp department (No further development work is being done by
> > Netscape in this arena). However, it's not impossible that a NetHelp template
> > might suddenly become available from Quadralay.
> >
> > >
> > >
> > > Incidentally, I'd like to hear from anyone who's developed online help
> > > using WebWorks.  How do you make it work?
> > >
> > > Finally, I've just been to the Seybold convention where the Adobe people
> > > say they're in negotiations with a Virginia development company to
> > > provide a real help tool for converting Frame docs.  Is this true?  Is
> > > this vaporware?
> >
> > I wouldn't mind hearing more about this either.
> >
> > Hope all this helps,
> > Craig Sanders
> >
> > >
> > >
> > > Anyone know?
> > > --
> > > Regards,
> > >
> > > -- mailto:Mark -dot- Dempsey -at- osi -dot- com
> > > --
> > > -- Mark Dempsey
> > > -- Technical Publications
> > > -- Objective Systems Integrators
> > > -- 101 Blue Ravine Rd, Folsom, CA 95630
> > > -- 916.353.2400 x 4777
> > >
> > > From ??? -at- ??? Sun Jan 00 00:00:00 0000==
> >
> > --
> >
> > "We do not see things as they are...
> > we see things as we are."
> >  -Anais Nin
>
> --
> Regards,
>
> -- mailto:Mark -dot- Dempsey -at- osi -dot- com
> --
> -- Mark Dempsey
> -- Technical Publications
> -- Objective Systems Integrators
> -- 101 Blue Ravine Rd, Folsom, CA 95630
> -- 916.353.2400 x 4777
>
> From ??? -at- ??? Sun Jan 00 00:00:00 0000==

--


"We do not see things as they are...
we see things as we are."
 -Anais Nin

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=