TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: On-line help from SGML for UNIX/Windows From:Chet Ensign <Chet_Ensign%LDS -at- NOTES -dot- WORLDCOM -dot- COM> Date:Thu, 28 Sep 1995 11:07:21 LCL
Jim Snowden asks:
>> Does anyone have any recommendations/experience of writing on-line help that
is
>> to be used for UNIX and Windows? Ideally, the on-line help should be able to
be
>> generated from SGML (created using Arbortext Adept Publisher).
Jim, we did a project like this for Novell's UNIX division using the Docbook
DTD as the data structure and DynaText from Electronic Book Technologies as the
delivery engine. We're writing up an article on how it was done for the new
"Nuts & Bolts" column on SGML in the STC's revised Intercom magazine.
Basically, both the online doc and the context-sensitive help were in the same
SGML source document. Using the ROLE attribute in the content, we distinguished
between text that was for doc-only, help-only or both.
When the user requested help, the DynaText opened the document to the
appropriate location using a style sheet specifically tailored for the help
display. Only content with the attribute value ROLE="HELP" would be displayed.
If the user then searched for more info or clicked on a 'book' button, the
stylesheet would be changed to display the online book instead.
This was strictly for UNIX. The other option you could try would be to write a
conversion routine (using a programming tool like Omnimark or Balise) for
turning your SGML into RTF structured for the Windows Help compiler. In this
sort of scenario -- we did this for a Windows and UNIX-based database system --
you have to take apart your SGML and restructure it into the hypertext
structure that Windows help demands, with hypertext links at the bottom of each
topic creating the jumps to subdivisions within the section or to other parts
of the doc, etc. etc. This kind of conversion takes a bit of time to write, but
once it is done the process of generating help from your doc file is totally
automated and easily modified if you need to change the presentation within the
help system.
The way we got the UNIX help on that one was to use Bristol Technology's
product -- Hyperhelp?? It is basically a Winhelp compiler for UNIX. Took the
same RTF input and generated a help file for X-Windows.
Hope this helps. If you'd like more details, feel free to email me.
Best regards,
/chet
Chet Ensign
Logical Design Solutions
571 Central Avenue http://www.lds.com
Murray Hill, NJ 07974 cworl -at- lds -dot- com [email]
908-771-9221 [Phone] 908-771-0430 [FAX]
