Summary: Using Word's Hidden Text as a conditional text hack (long)

[RJACOBSE -at- GPS -dot- COM]

Roy Jacobsen -at- GPS
06/04/97 10:41 AM

Here's a summary that's way overdue. Some time ago, I posted the following
query to WINHLP-L and TECHWR-L:

> We're using MS Word and dealing with a large doc set (printed and online)
> that spans three product lines, complicated by a severely
> stretched writing team (isn't that a unique situation <frown>).
> The three product lines share many common features and
> the basic interface is the same. We're able to use some
> of the docs for all three products as is, however, some
> portions of the docs need to be customized to varying
> degrees for each product.
>
> My idea is to use a single doc source for all product lines,
> incorporating ALL information EVERYWHERE, and to use
> templates and styles that would show each audience only
> the pertinent information: Product A would have Template A,
> and in Template A, any text referring to Product B features
> would have a Product B style and would be hidden text.
> When creating a Product B document, we would attach
> the master file to the Product B template, revealing the B
> styles and hiding the A styles.
>
> I can already see that making sure any jump coding in
> WinHelp source files will need to be treated with kid
> gloves so switching from one template to another doesn't
> booger things up. I think I can work around that. Printed doc
> files should be a bit simpler (I think).
>
> My question is: has anyone used a similar scheme to hack
> a pseudo-conditional text feature in MS Word? Any successes
> or failures? Have I been drinking too much coffee?

Besides the suggestions that we use Framemaker instead of Word, I received
the some thought-provoking responses.

Jean Weber (jean_weber @ compuserve.com) had the following suggestion:
Roy

I prefer to use IF... THEN as a conditional. I have had some bad
experiences with hidden text, and particularly with changing templates,
mostly related to the writer/formatter failing to use styles properly all
the time, or forgetting to ensure the print options are set to not print
hidden text, or (in your case) forgetting to attach the correct template
with the "Update Styles" flag set -- all of which are fairly common
problems when everyone is overworked and on a tight deadline). With IF...
THEN you still must remember to specify the condition before you format,
but you can live with misuse of styles, for example. And the IF statements
serve as notes to the writer (for maintenance purposes) so you might not
need hidden text for your explanatory notes.

The above comments arise from two experiences: (1) I get a lot of work
cleaning up the chaos left by previous writers, who don't always understand
-- or use properly -- templates and styles. Some of these people are TWs;
some are not.  I've dealt with a lot of writers who may write well but have
recently had to switch tools and are still learning how to use them. (2)
Many of my clients prefer to maintain the documents I write for them, so I
have to make the docs as easy to maintain as possible, following brief
instructions from me. (Whether they follow those instructions is another
matter.) Your mileage may vary.

I haven't attempted to use IF... THEN when compiling WinHelp docs, so I
don't know whether it works, well or otherwise.  I must try that!

Regards,
Jean Weber
Technical Writing, Editing, Publishing Consultant
Sydney, Australia

<I responded:>
>I'm afraid you lost me. How are you using IF..THEN? In a macro you run
prior to printing? (Sorry to be dense, but I'm getting several varying
suggestions. It's hard to picture how some of them work.)<

Now you've put me on the spot (and rightly so). I haven't done this in
several years, and can't remember the details. Someone else showed me how
to do it, because it isn't explained clearly (or at all) in the Word 6 help
and user guide. The technique uses fields such as bookmarks, IF and
INCLUDETEXT (not THEN, my mistake); the mail merge facility (or a variation
on it); and an ASK field where you specify which version you're wanting to
print. I believe the ASK field would be put into a macro to run before
printing.

This probably isn't all that helpful, because of the lack of detail. If
I've wasted your time, I apologize.

Regards, Jean Weber
jean_weber @ compuserve.com


- - - - - - - - - - - - - -
David Locke (dlocke @ phoenix.net) wrote:

Since styles for headings are limited and carry a huge functional load, I
don't think styles would work. The last time I tried to create my own
Heading 1 style with a unique name, I lost TOC functionality.

A better way to deal with conditional text is to use links that reference
virtual paths. A virtual path would be a path that maps an existing
directory to a virtual drive. Mapping can be done using windows File
Manager.

Using this scheme you would write your core document and link each of the
variations. You might want to use a different style name for each
variation.

When you are ready to go to hardcopy, make copy this document, but include
only one link, delete the others. Then, link to the directory containing
the text specific to that variation and print the document.

Any way you go, text that is shared by two or three products, but not the
others is tough to do.

And, if you link to graphics, those links should always reference a virtual
(work) drive.

David

- - - - - - - - - - - - - - -
Jay Mead (jay -dot- mead -at- den -dot- galileo -dot- com) wrote:
Roy:

I had the same problem you have, and hacked together conditional text in
Word by
using templates and bookmarks.  Note that I did NOT have the Help File
component of your problem--someone else will have to ride to your
rescue on that.  But here's my Word/conditional text approach:

It's been a year, but as I remember I simply inserted a reference to a
bookmark in the main document, and then
wrote the individual text for each of the five flavors of my document and
copied a flavor's text to that flavor's template using the (same)
bookmark name. Then,
to print for Flavor A, I attached Template A, and when the bookmark
reference was reached the Flavor A text was inserted.  To print the Flavor
B version, Template B, and so on.

It's fairly labor-intensive, but I used this scheme very successfully on a
number of enormous (500+ page) documents.

Let me know if you need more details.

Jay Mead
jay -dot- mead -at- den -dot- galileo -dot- com

- - - - - - - - - - - - - - -
Charlie Munro (cmunro @ Incite.com) wrote:
I had a similar situation and considered several approaches, but decided
that the simplest method was to:

a) create separate projects for each app/product line. The reasoning is
that each version has slightly different information in the HPJ, most
notably the title and copyright (which included the app name). I could
also create individual CNT files.

b) create files that contain the unique topics. Write once, cut and
paste where possible, and customize from there.

c) create a separate folder and document that contains all common
topics. This folder and file is referenced in the [files] section of
each project.

I decided against using styles (paragraph and character). Although I
could write macros to manage the switch between versions, there were
always cases where some formatting (especially for jumps/popups) was
difficult or impossible to preserve. It's a quirk of how word stores
formatting at character/paragraph/style levels.

I decided against color coding for the same reason, plus, it would be
necessary to change the color coded text to black before compiling so
that it appears correctly in the help.

Plus I would still have to manage the changes to the HPJ file for each
version.

HTH
- - - - - - - - - - - - - - -

Thanks to all who took the time to make some good suggestions. The long and
short of it at GPS is that we're still using build tags, but we're always
trying to find something better and easier to manage.

Regards,
Roy Jacobsen
Editor
Great Plains Software
rjacobse -at- gps -dot- com

 TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot-  Send commands
   to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
  Search the archives at http://www.documentation.com/  or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html