Suggestions on document configuration management?

[John McMullen <johnmc -at- MKS -dot- COM>]

I'd like to hear what other people do for document configuration
management: producing a number of versions of a document, each of
which contains details specific to a particular client.

We have a software product which we supply to several OEM vendors; for
each vendor, some text in the document has to be changed.  For
example, on OEM versions of our software, the password file is stored
in /etc/passwd, while on the DOS versions, it's in $ROOTDIR/etc/passwd.
(If we do an extensive customisation job, entire chapters may be added.)

How do *you* handle conditional inclusion and formatting of text?
(That's the most general way I can think of putting it, and it doesn't
completely describe the problem.)

To demonstrate, here's what we do.  We use troff and a slew of pre-
and post-processors.

Text is included on the basis of keywords:

#if DOS
...passwords are stored in the file $ROOTDIR/etc/passwd.
#else
...passwords are stored in the file /etc/paswd.
#endif

(We don't actually use the C preprocessor, but this gets the point
across.  It's a programming paradigm.)

Anything could be in the included blocks... a troff .so (inclusion)
for a particular file, a macro or string definition.

Aside from the fact that this is really ugly, there are further
problems:

1.  Tough to maintain.

2.  It's ugly and hard to read.

3.  If one of our OEM clients wants to re-organize the manual page,
    we have to do huge #if...#else...#endif blocks

4.  The set of parameters defining a particular client's documents are
    not necessarily isolated in one neat spot.

The problem is larger -- for instance, we should switch to another
page numbering scheme (we use continuous numbering) to minimize the
effects of revisions on minor releases...currently we reprint as much
as needed.  (It's OEM with only a few clients, but we hope that will
change.)

This is my first serious grope at the problem (though I've been
thinking about it for several years), so I'll probably have to restate
it soon.

Suggestions for readings, strategies, useful processes, even software?


Thanks.

John McMullen
MKS
--
John McMullen    | "These dice have no spots!"
Technical Writer |    "Yeah, but I remember where the spots formerly were."
johnmc -at- mks -dot- com   |
                 | My opinions do not necessarily represent those of MKS.