Re: Single-sourcing, SGML, Online Help

[Mark Baker <mbaker -at- OMNIMARK -dot- COM>]

Kandis Weiner wrote:

>Can the qualities of SGML facilitate single-sourcing of online help and
>hardcopy documentation.

In concert with other technologies and tools, and with the appropriate
modifications to the authoring process, yes.

But remember, different media not only have different formatting, they have
different structure. If you convert from one media to another, the structure
of the information product in your target media will be dictated by the
structure of your source, rather than by good structure for the target
media.

It you want to have fully functional well designed information products in
different media, and single soure the information in them, you need to
create the information in a way that is structurally neutral as well as
formatting neutral.

SGML (or XML) is a very useful tool in building a system to do this.

>For example, can tags be created that indicate what
>information will go into online help, printed docs, and both?

Tags can be created to mean anything you like, because you define the tags.
But SGML does not have any processing characteristics, it is simply a markup
specification language. You will need to create a processing application to
manipulate your data according to the tags you use.

It is not good practice, however, to encode media preferences into the data
itself. Presumably, the information is chosen for one media or another based
on some property of the information itself. Your markup should express the
properties of the information. Your processing application should act on the
properties of the information to create appropriate output for the media you
choose. Not only is it easier to author this way, but when a new media comes
along, you will be able to create output for it without editing your data.

>And, are
>there tags that can be designed to indicate hypertext link in online help
>or cross-references in printed docs?

Same answer as above. There are some formal schemes for expressing links in
SGML and XML (Hytime and XLL respectively), but in most cases you would be
better advised to mark-up your data for what it is and then have a
processing application create links automatically based on the inherent
properties and relationships of your information.

>Can then some macro be run to extract
>the informaiton required foir online help?

You will require a program rather than a macro for this purpose. OmniMark is
the premier programming language for SGML, XML, and the Web.

>Once this information is
>extracted, maybe it can be easily(?) converted to HTML Help (Save As HTML)?

This is what your processing application does for you. Since your source
markup is particular to your own data and your own business model,
conversion to standard formats is necessarilly a matter for custom
development, but this in not difficult in principle.

>I would greatly appreciate any information concerning the tools and
>especially the processes people are using to implement a single-source
>environment with Frame + SGML.

Frame is an editor and an formatter for paper, but it is not a complete
single sourcing solution. It can be used effectively with the other
components that make up a single sourcing solution, a system we call a
content management system. For more information, see the OmniMark web site
(http://www.omnimark.com), particularly the white paper on content
management.

---
Mark Baker
Manager, Corporate Communications
OmniMark Technologies Corporation
1400 Blair Place
Gloucester, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com
Web: http://www.omnimark.com