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: Moving Files for Hardcopy to PDF and HTML From:"Martha R. Breil" <mbreil -at- LYCOS -dot- COM> Date:Wed, 28 Jan 1998 13:04:37 -0500
Joe Miller wrote:
> We're thinking of providing our user's manuals in PDF format
> HTML format, or both, using one set of source files to produce
> a manual's hardcopy version, PDF version and/or HTML version.
I think that producing both HTML and PDF documentation may be overkill,
but I don't know the specifics. I definitely wouldn't want to update
three sets of docs every time something changed, but things around here
change frequently, and I'm the sole TW. I prefer to use HTML if the
site is configured well because it's one less step, (i.e. I don't have
to open Adobe Reader to access the docs).
> I'm hoping one of you knows how to get around HTML's lack of
> support for captions. Without them, a textual reference to
> "See Figure 2.3" won't be much help. I don't want my group to
> have to do a massive search and replace with editing every time
> we create HTML files, but I do want to produce usable docs.
> Is there a workaround, do you omit figures entirely,
HTML 3.2 does support a <caption> tag within the boundary of a table,
but I don't know if it will allow you the flexibility that you need.
Generally, you should use either internal or external links to take the
user to the (table, caption, graphic, etc), to which you refer.
Tables are used for formatting in HTML; they're not necessarily visible
to the end user. HTML 4.0 may offer more options, but I haven't
investigated it yet.
What conversion software are you using to get the hard copy docs into
HTML? The ones I've used leave much to be desired and don't produce
very clean HTML. Hence, I'd recommend one that allows you to view the
HTML raw code and edit it as necessary.
> or do you just leave the textual cross-references in place as an >exercise for the reader?
I don't know what you're getting at here. I definitely would not leave
it up to the reader to find the text without linking them to it.
Hope it helps,
Martha
--
Martha R. Breil
Sr. Technical Writer
Lycos, Inc. http://www.lycos.com/
"Get Lycos or Get Lost"
