is it possible to single-source online & print and author in HTML?

[Chuck Martin <cwmartin -at- US -dot- ORACLE -dot- COM>]

The subject line asks in a nutshell a question that I have not yet been
able to find a reasonable answer for (other than "no"). It is a problem
that is in need of a solution here. Here's the scenario (it's long;
please be patient):

Some time back (before I began working here) a decision was apparently
made to eliminate our printed documentation set for our set of database
development tools. As a result, authoring was moved completely to
RoboHELP, producing WinHelp for the product on Windows, and then either
the source or the output was tweaked somehow (I don't know how) to
produce online docs for UNIX.

Last year there was a customer demand for *some* of the documentation
set to be provided in printed form. Not PDF, but a real,
hold-in-your-hand, book. I was tasked with developing procedures to
extract the correct source information and provide files that could be
sent to our printer. It was not an easy task. RoboHELP produces horrible
print output, and the way it does it doesn't lead to well-formed print
output: use the TOC to determine the topics and ordering of the output,
but in a good Help system, the TOC doesn't link to every topic. The
onerousness of the task was added to because I could not upgrade to Word
97. What is essentially needed is the reference information picked out
and put in a book.

Now we've decided to not only move to HTML-based Help, but also there is
a push to author directly in HTML. (Technically, we're producing Oracle
Help for Java output, which is more HTML/Java-based Help.) Within our
suite of products, the Help systems run from a few hundred Help topics
to more than 6000. (Note: there is a move afoot to spend some resources
consolidating some Help topics, actually a good idea for this particular
Help system, but we'll still be talking about several thousand HTML
files.)

Awhile back, Eric responded to a post in a somewhat similar vein that
moving to HTML is essentially a one-way process. Once you get
something--particularly something structured--into the unstructured
environment of hypertext, going back the other way at the very least
isn't one bit pretty.

So I've been researching potential tools and solutions without finding
anything that comes close to our needs. I have talked to a number of
Help vendors directly, both at the Online Help Conference and the
JavaHelp JumpStart Conference, and they have had neither solutions nor
ideas. One suggestion has been to break down the authoring environment
into subdirectories by the type of Help information. That sort of gets
part-way to a solution, but it does nothing for *ordering* the
information properly.

Complicating things is a desire to perform some customization on the
HTML files. That seems to rule out document-based authoring solutions,
such as RoboHELP, because every time you output the HTML, you have to
have well-written and tested scripts to tun against the hundreds or
thousands of HTML files, a rather non-productive process. Thus the
desire to work directly in HTML, where you create files the way you want
them to appear.

I've been poking around this small tool I found called HTML2Frame. It
seems to be made by a small company somewhere in Europe. The
documentation that comes with it is sparse. I'm not confident that it
would be a good solution.

Despite that, I have higher hopes for somehow being able to work within
the framework of FrameMaker. Part of my hopes are tied to the fact that
our corporate standard templates are all in Frame. (With dozens of
paragraph tags.) But there are a couple of Frame issues. Importing from
WinHelp projects is almost impossible. Heck, I even tried importing a
small, plain Word document and was unable to apply paragraph styles from
within Frame. Trying to go from HTML to Frame still leaves both the
ordering issue and figuring out how to go from a small set of tags
(HTML) to a large set of paragraph styles (Frame).

Interestingly, Adobe announced with its Acrobat 4 product the ability to
go from HTML to PDF. What I've not been yet able to investigate is just
how order is imposed on the imported HTML files. Where's the entry point
for the PDF file? How to you create an ordered table of contents from an
unordered set of heavily hyperlinked HTML files?

As a small side note, there is a bit of sorrow in feeling the need to
leave a Word-based authoring environment because I'm reasonably
proficient in WordBASIC and have used it successfully to do a lot of
document manipulation.

I'm continuing my investigations, but I would appreciate any insights or
suggestions from the larger technical writing community. Boiling this
whole thing down to a reasonably simple question, I need to find the
answer to: is it possible to author documentation of hundreds or
thousands of topics directly in HTML and also produce ordered print
output from a specific subset of the topics?

Ideas and suggestions are ever so much appreciated.


--
"[Programmers] cannot successfully be asked to design for users
because...inevitably, they will make judgments based on the
difficult of coding and not on the user's real needs."
        - Alan Cooper
        "About Face: The Essentials of User Interface Design"

Chuck Martin
Principal Technical Writer, Oracle Developer
Tools Division, Oracle Corporation

cwmartin"at"us.oracle.com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=