Re: Frame > Online Help

[jeremy@xxxxxxxxx (Jeremy H. Griffith)]

On Thu, 15 Jul 1999 16:19:07 -0400, William Swallow <WSWALLOW@commsoft.net>
wrote:

>I didn't say that your product doesn't support single-sourcing. I made a
>suggestion if these people were not going to single-source.

I'm sorry, I still can't understand the reason for that qualification.  
Why would the suggestion only apply "if these people were not going to 
single-source"?  This implies that if they *were* going to single-source, 
the suggestion would not be relevant.  How come?  I really don't get it...
maybe I'm being dense.  Those two sentences just look contradictory to me.

>I don't know your most recent product. Does it have an authoring interface
>or does it just convert? Can you create/alter topics with it or does that
>need to be done in Frame.

Our whole design concept is to use Frame to do everything possible, and
supplement that where necessary with info stored in an associated .ini
file.  The user work with the added info within Frame, via a Conversion
Designer closely modelled on the Paragraph (or Table) Designer.  So for
most cases you never leave Frame.

We see a topic as consisting of a title and body, where the title is
identified by its para style, and the body consists of everything up
to the next title.  For each style in your doc, you can specify the
added "help properties" that apply to it, such as topic start (and
many others).  So you create and alter topics in Frame, which already
*is* a perfectly good authoring interface.  We don't think people who
are familiar with Frame should have to learn any other ways of doing
anything that Frame does perfectly well itself.

>The reason I suggested a HAT was that if you are NOT single-sourcing, it's
>much easier to use a HAT to organize and create Help. Most HATs today have
>visual interfaces that show the topical structure of the Help you're
>creating. They automate tasks, yet allow you to proceed manually if you so
>desire. There's no conversion involved - just compilation.

This fails as soon as you have any changes in your master Frame doc,
which seems inevitable in the real world.  This is where you lose all
the advantages of single-sourcing.  You have just two alternatives,
both bad:

1. Alter the content within the HAT to match the changes in Frame.
Trouble is, you are bound to miss some, or mistype something.  Even
if you cut and paste every change you see, to prevent typos, you
will never be sure you got them all.

2. Re-convert the Frame file into the form used by the HAT, usually
RTF.  Then you get to redo every single thing you did in the HAT for
the previous revision.  Again, you will never know if you miss one.

That is why we have gone to great lengths to make sure that every
construct you may want in the help file can be specified within the
Frame document (or the .ini file).  We know that "to err is human",
and so we eliminate the step in which your print and Help docs can
get out of sync.  And since most files convert in a few seconds,
you can check your work in the *real* WinHelp environment as you
go along; no need for an inaccurate simulation of WinHelp.

>I'm not knocking your product. 

Didn't think you were.  Just wanted to be clear on how it's best used.

>If Help is to be created from scratch, it's
>much easier to do so in a WYSIWYG environment - especially for beginners, as
>I believe the person who posted the initial question that started this
>thread is. If your product allows this stand-alone WYSIWYG authoring mode,
>then great! 

What we do ourselves is have Frame and Help Workshop both open on the
desktop.  (We still use NT 3.51. ;-)  We load a book in Frame.  We use
File | Set Up mif2rtf... to produce an initial .ini and .hpj.  We load
the .hpj in Help Workshop.  We use the Conversion Designer to see what
styles the filter thought should start topics, and modify those choices
as needed.  (It's smart, but doesn't *always* get it right.)  Then we
use File | Save Using mif2rtf... which generates all the .rtf files
and .cnt file for the whole book from two mouse clicks.  We move to
Help Workshop, click its Compile icon, and watch the messages (if any).
(You can also do this as part of the Save, automatically, but we prefer
the more "hands-on" method.)  Then we click Help Workshop's View icon, 
and try out the real WinHelp file.

>From then on, as we edit in Frame, we click File | Save Using... to
update the currect file's RTF (and the full .cnt), in a few seconds.
Then we click Help Workshop's Compile and View icons (several more
seconds), and see what happened.  That's WYSIWIG enough for us!  And
it's a WYSIWIG that does *not* compromise single sourcing one bit!

>And if not I still recommend your tool for converting what PARTS
>of their documentation they want to include in their non-single-sourced
>Help.

Thank you for your recommendation.  I hope I've clarified how we
think people should use mif2rtf a bit better...

-- Jeremy H. Griffith, at Omni Systems Inc.
  (jeremy@omsys.com)  http://www.omsys.com/

** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **