Re: Single Sourcing HTML Files and Single Sourcing HTML Followup

[Lee Bumgarner <lee -dot- bumgarner -at- VIRTUS -dot- COM>]

Techwhirlers:

I posted a request and a follow-up request to the list, and several of you
have asked that I summarize the findings. Under a time crunch, I will not
summarize but will paste together list and off-line responses.

Thanks to Sally Yeo, Lydia Wong,  Valerie Jachimowiz, Regina Caldanaro,
Scott Lovett, David Demyan, Lisa Higgins, Nick Honeycutt, and Mike Davis.

My apologies for not cobbling this together more quickly or if I have left
out any responses.

Lee B.

*********Original request with responses  ( numbered)*********
>Has anyone had experience creating single-source HTML files for the web
and for publishing hardcopy? ( numbered)
1. Look into HTML Transit. It takes various WP and DTP formats and creates
HTML output and you have a reasonable amount of control over banner
graphics, navigation icons, etc. You can download a demo from their site.

2. I think that single-sourcing will be a little difficult unless you want
to get into big bucks for on-line publishing. EBT (a client of ours) has a
product called DynaBase about which I know little, except that it does do
Web publishing.

I would be more inclined to prepare my printed docs and then shoot the
files out to HTML. I have tried the HTML Transit eval, and it converted my
FrameMaker files very easily. There is a bit of a learning curve as you set
the HTML Transit "template" to do what you want it to do. The HTML
conversion is based on your document's styles/tags, so if you have a
well-organized document, this conversion works well.

3. I'm a FrameMaker user and trainer. Still, regardless of any personal
bias, I'd recommend doing all authoring, editing, etc., in Frame (or other
real creation/editing tool) and considering HTML, PDF, and paper as output
choices with their particular values/drawbacks.

4. We're using Frame files as a single source, then using Web Works
Publisher to convert them to HTML (and thereafter to WinHELP). Frame gives
you the tools to control the design of the paperdocuments, as well as a
(relatively) simple way to generate TOCs and indexes. The conversion from
Frame to HTML goes fairly smoothly because WWP allows us to map Frame
paragraph andcharacter tags to specific (even nested) HTML tags.

5. I suggest you check out the SGML Standard (ISO 8879). SGML is
specifically intended to solve the problem of using the same document for
more than one purpose. SGML is particularly good at doing paper + web for
many reasons -not least of which is that HTML is an application of SGML.
Try www.sgmlopen.com and/or www.sil.org/sgml for more info.

6. I think I'd vote for the FrameMaker solution first, especially if the
number of documents was relatively small, say under a total of a thousand
pages or so. FrameMaker is a known and popular package with conditional
text capability and lots of third-party software for making docs into HTML.
You can find FrameMaker operators without much trouble and you can
similarly find support in most places. We use FrameMaker commonly for
creating two or more versions of a single document.

I'd recommend looking at SGML only when the load becomes enormous. It's a
lesser-known technology and its tools aren't widely known, either. You'll
have to retool more to work in an SGML environment. Of course, if you
already know Frame, you can move to its SGML tool, although it's probably
not the equal of many specifically SGML packages. In short, there's a
ballistic learning curve and lots of initial investment. However, if you're
planning for tens of thousands of pages, go to SGML.

7.  I don't have much to tell you, but did want to recommend checking out
the article "Converting Your Documents to HTML" in the May 96 Intercom (STC
newsletter). The author
discusses converting Frame to HTML, and he lists some tools. (This is
assuming you're looking mostly at Frame- HTML production.)

We downloaded trial versions of Quadralay's WebWorks Publisher
(http://www.quadralay.com) and WebMaker (http://www.harlequin.com). We were
very impressed with Quadralay's WebWorks product (very expensive, though!).
We converted one of our Frame-produced books to HTML very quickly with few
problems as a trial case. We DO NOT use the tool every day, though, and we
haven't released any docs in HTML. But just for ease of use and power (you
just tell it the Frame book filename, and it reads in the files and
converts the book), I recommend you check out WebWorks (they offer a free
30-day trial version that seems fully functional). We'll definitely
consider it more as we get closer to
HTML docs.

I'm afraid we haven't looked into printers working with HTML files for
production (we were glad to find one who was comfy with Frame and
reasonably priced!). I wonder if you wouldn't get into a whole other realm
of issues what with needing to provide templates/document definitions for
HTML tag layout, etc. We'll watch with interest to see what other writers'
responses are to your questions!

8. Of interest, these folks are presenting at the SIGDOC this fall on
single-sourcing: Thyra Rauch and Dana Gillihan, Information Access: Single
Source, Multiple Use, IBM-RTP, Research Triangle Park, NC, USA . I think
Dana was working with HTML in her current job. The other presenters in the
category are:  John Horner, Pat Moell, Cindy Roposh, Hanna Schoenrock,
Helen Weeks, andSusan Willard, Publications Division, SAS Institute, Cary,
NC, USA , Developing Single-Source Documentation for Multiple Formats. I
could be all wet, but perhaps HTML is part of their single-sourcing.

9. I saw your post and thought you might be interested in our authoring
product E-Publish. Briefly, it takes Word or RTF source files and allows
you to create markup rules, defining hotwords and their behaviour, index
structures, etc based on paragraph styles, formatting or pattern matching.
The rules are then applied to the source files to produce HTML output or a
standalone electronic publication using our viewer technology for
distribution on disk, CD-ROM or network. Your Word or RTF source files can
be used for both hardcopy and HTML production. More details are available
on our Web site. An evaluation copy of the>current version is available
from our web site. We will have an>evaluation copy of the upcoming version
on the Web site next week. www:  http://www.stattech.com.au

10. NOTE: I  posited the same question to local printer Mike Davis at Theo
Davis, Inc. He indicated that he knows of no technology to print HTML files
commercially. He indicates that in his experience in this region, most
>folks are creating single-source files in a word processing package and
then sending the files to the printer for printing and using a converter
(either within the WP application or using an after-market tool). He
indicated that FrameMaker is most popular WP tool, followed by PageMaker,
QuarkXPress; he is not aware of the HTML conversion tools that are being used.

*********Follow-up request*********
(Two responses in followup: A and B)
A. >(1) Do these conversion tools allow the user to set up a type of
document style or template to be converted to? Say, certain levels of
headers, spacing, etc. Or have you had to go to an editor or a WYSIWYG
editor to>create a style more to your liking?

HTML Transit handles both. Style tags to be converted have flexible (within
the limits of HTML 3.0) formatting options. This allows you to emulate the
original look of the document. To post-process with HTML Transit, you
specify the editor you want to use in clean-up. I like to use Netscape Gold
3.0, which allows table editing. HTML Transit does not offer a lot of
flexibility in translated tables, so I like to "tweak" them in NS Gold.
Also, NS Gold allows you to fix links easily, re-import graphics, fix line
spacing, change fonts, apply color, etc. etc. The decision to re-convert
with Transit or just fix it up in the post-processor depends on how often
you will need to translate same or similar documents (hopefully based on
the same word processor template). This way, if you need a conversion
template that will work in the future with similar documents, you can build
it as
you go.

>(2) Do these conversion tools have editors for the clean up that
>invariably follows conversion?

See previous comment.

>(3) Do these conversion tools have WYSIWYG editors for the clean up that
>invariably follows conversion?

No, but HTML Transit does allow you to specify the post-processor you want
to use. I chose Netscape Gold 3.0 because it is WYSIWYG (more so than most
others I have used).

>(4) Has anyone had any experience dealing with converting programming
>source code and done so successfully?

Limited experience going to Acrobat. It worked well because Acrobat did
change the font or indents and presented source pretty much as it
originally looked with the headings I added before comments.

B. Overall, I still say that you're going to end up doing so much in the
way of cleanup, you're probably better off working from ASCII text
(that's been my experience, anyway.) And if you REALLY REALLY don't want to
do the HTML by hand, you could get an editor thingy to do it in.

Lee Bumgarner // Gross-Smelling Word Weenie // Virtus Corporation 114
MacKenan Dr., #100 // Cary, NC 27511 Voice: (919) 467-9700 x 3046 // FAX
(919) 460-4530 Website: http://www.virtus.com

                  TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send administrative commands
         ALL other questions or problems concerning the list
       should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-