RE: context-sensitive help and the printed manual

["Smith, Martin" <martin -dot- smith -at- encorp -dot- com>]

I received a number of off-line responses for more information about how I
wrote scripts to publish HTML Help, DHTML, and printed manuals from a single
set of FrameMaker source files. I thought I'd summarize my responses here.

In the original post, I mentioned that our manuals are also procedural in
nature. In order to produce context-sensitive on-line help for our Windows
applications, I prefer to add a chapter to the beginning of the manual that
only appears in the on-line version. This chapter has headings that
correspond to each screen in the software interface. I document the purpose
of the screen in each of these sections followed by cross references to the
procedural "How To" information inside the manual. When compiled into a help
system, each section in this chapter becomes a topic with context-sensitive
hooks into our Windows application.

The solution that I developed to single source our documentation is based on
two main scripts. Both scripts run from a FrameMaker book file. The first
script opens every file in the book and takes inventory of all paragraph,
character, table, and conditional text formats. It then produces a
FrameMaker document that I call a Map File. This file contains a table for
each of the aforementioned styles. The script fills in the first column of
each table with the names of each style. Additional columns are filled out
by the user once the script is finished. For example, the Paragraph Style
Table looks something like this:
----------------------------------------------------------------------------
-----------
Style Name  | Include Y/N | Starts Topic Y/N | Ends Topic Y/N | HTML Begin |
HTML End |
----------------------------------------------------------------------------
-----------

The user fills in either a yes or no for columns 2-4 and the HTML code to
wrap around the paragraph text in columns 5-6. Note that the ability to
start and end topics based on paragraph tags makes it possible to exclude
everything *except* the procedural how-to information from the help system.
Once the tables are filled out, the user runs the second script which
generates the HTML.

For example, let's say that, by convention, the manual is organized such
that procedural information always begins at Heading 3. If the first chapter
in the book documents the screens, as stated earlier, then the cross
references at the end of each topic would point at the relevant Heading 3
tagged paragraphs. In addition, if the book is structured such that another
Heading 3 tag (or a heading further up in the hierarchy such as Heading 2)
always indicates the end of the procedural information, the script can be
programmed to end the topic at the appropriate location and exclude any
extraneous information. Implementing this approach simply involves filling
out the Paragraph Style table as follows. 
----------------------------------------------------------------------------
-----------------------
Style Name  | Include Y/N | Starts Topic Y/N | Ends Topic Y/N | HTML Begin
| HTML End |
----------------------------------------------------------------------------
-----------------------
Heading 1   | No          | No               | Yes            | <h1
class="my_class">  | </h1>    |
Heading 2   | No          | No               | Yes            | <h2
class="my_class">  | </h2>    |  
Heading 3   | Yes         | Yes              | Yes            | <h3
class="my_class">  | </h3>    |
Body        | Yes         | No               | No             | <p
class="my_class">   | </p>     |
----------------------------------------------------------------------------
-----------------------

There is, of course, more to the script than this. I also needed to handle
index and cross reference markers, for example, and construct the table of
contents and index. And the HTML code that initializes and terminates each
topic resides in yet another table. Nonetheless the two scripts only amount
to  about 3,000 lines of code.

The script also generates the table of contents for the help system. Here to
one can get creative. One of the nicest HTML Help systems that I've seen
lately contained three or four main headings in the Table of Contents,
including the headings Reference and How-To. The reference section contained
screen-by-screen reference material, similar to the reference information I
described earlier. The How-To section contained an alphabetized list of
How-To topics (it wasn't an overly long list). If the script was used to
lift how-to information from the chapters based on paragraph tags, then the
script could also alphabetize these links in the table of contents. 

What really interests me in this discussion isn't so much the
implementation. I chose to code in FrameScript, which is a language that I
understand. I think one could probably do something similar in WebWorks but
I am not good enough at writing regular expressions to know for sure. I've
read the Regular Expressions manual from O'Riley and Associates several
times over but still have a long way to go before I become proficient. One
could also export Frame books to .mif and write a similar program in PERL.
In fact, some of the FrameMaker help authoring tools on the UNIX side are
.mif based. I am, however, very interested in strategies for organizing
books in ways that facilitate printed and on-line distribution. I am also of
the opinion that clever programming can be used to produce help systems and
web pages that restructure information contained in the source files of
FrameMaker documents.

Sorry to go on for so long. But I like this subject much more than debating
Andrew Plato's consulting and posting practices :-)

Martin