Re: conditional text in Word

[Stan Brown <stbrown -at- NACS -dot- NET>]

In TECHWR-L Digest, CARYN_RIZELL -at- HP-ROSEVILLE-OM2 -dot- OM -dot- HP -dot- COM asks:
     I need to produce documentation for many different platforms from
     one single source file. Has anyone figured out how to produce
     several different versions of your documentation (either manuals
     or online) from a single Word document?  How do you handle
     conditional text in Word?

From your mentioning different platforms, I assume that there will be
many places where text differs, and that the differences will each
range from a few words to a paragraph or two.

    An alternative
    ^^^^^^^^^^^^^^
Before I give a technical solution, might I suggest an alternative? If
this works in your context, why not have only one manual that covers
all platforms? In the introduction, you would define an icon for each
supported platform, and then at the point where differences occur you
could give each version, with the appropriate icons in the margin.

Microsoft does this sort of thing in some manuals, where some
instructions have a mouse icon next to them and others a keyboard
icon.

It could simplify the development process and make life easier on your
reviewers, since it would be clear to them what the (claimed)
differences were among the platforms. It might also simplify your
client's inventory and reduce the printing bill. But it could be
confusing to the reader (and therefore a Bad Thing) if there were,
say, half a dozen versions and the reader couldn't easily tell where
the common text began again.

    Using multiple styles meets your stated requirement
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
So, on to a solution that does what you asked for. It depends on using
styles in a disciplined way in Word, and is best illustrated by
example. Say you have decided to define a style called Instruction for
step-by-step instructions. After defining that style, you would then
define an additional style for each platform -- say Instruction UNIX,
Instruction VAXVMS, Instruction NT, Instruction OS360 <grin>, and so
on -- all based on the Instruction style and differing from it only in
having the Hidden text attribute set. You'd do the same thing for each
character or paragraph style in your document, always using consistent
suffixes. (A simple macro could define the derived styles for you.)

You'd format any instructions that were common to all platforms in the
base Instruction style. But instructions that applied only to VAX/VMS
would be formatted in Instruction VAXVMS, and similarly for the other
platforms. It's important that you _never_ redefine the derived
styles, but make any changes to the "base" style.

Now when you want to produce the VAX/VMS style of your document, you
simply redefine all the VAXVMS styles to be _not_ hidden. (Be sure to
save the document under a different name so that you don't overwrite
your base document. You'll probably need to repaginate as well.) And
you'd proceed in the same way for each platform.

You might well choose to write a macro to make those changes for you.
You'll need to use CountStyle() to tell how many styles there are,
StyleName$() to get the name of each style, Right$() to test the style
name against your platform name, and FormatStyle and FormatFont to
change the definition of the style. (See online help or, better,
_Hacker's Guide to Word for Windows_ for details.)

Since Word 6 introduced character styles, this approach can be used
for varying words or phrases within a common paragraph, as well as
paragraphs that appear only for one platform. If a paragraph appears
for multiple platforms but not for all, you can either duplicate the
text or use an insert field to pull the text in from a separate file.

Regards,
Stan Brown, Oak Road Systems      Cleveland, Ohio  USA      +1 216 371-0043
email: stbrown -at- nacs -dot- net                   Web: http://www.nacs.net/~stbrown