These manuals contain over 90% common information, except that throughout each book, the word "DataHub" in the Cascade DataHub book becomes "Connect" in the Cascade Connect book. This is done through the use of entities, as well as a script that rewrites all the files and puts them into a common directory. Here's how it works:

Directory Setup

There is one directory, doc/i/datahubwin/ that holds all the files for both the DataHub manual and the Connect manual. SGML source files common to both books are in this directory. It also contains two subdirectories: c/ and d/. Files unique to Connect are kept in the c/ directory, those unique to the DataHub go in the d/ directory.

When it's time to process the document, the Makefile first calls the copydatahub.sh script, which runs through the text of each file, changes all &hub; entities to either ccw or dhw, and then writes the output respectively to doc/i/datahub/ccwcomplete or doc/i/datahub/dhwcomplete.

This could be considered an abuse of SGML, since I'm not actually using the &hub; entity as an entity per se, but rather as an easily-identifiable placeholder that will never be confused with anything else. The advantage is that the SGML parser will overlook it during editing time but flag an error during processing if it hasn't been changed correctly.

Interchanging Names

Entity Definitions

The entities for the books are defined in two entity definition files: c/entities and d/entities in the doc/i/datahubwin directory. Part of the DataHub entity definition file looks like this:

...
<!entity hubchap-intouch            SYSTEM "chap_intouch.sgml">
<!entity hubchap-databrowser        SYSTEM "chap_databrowser.sgml">
<!entity hubchap-eventlog           SYSTEM "chap_eventlog.sgml">
<!entity hubsect-test               SYSTEM "sect_test.sgml">
<!entity hubsect-excelexample       SYSTEM "sect_excelexample.sgml"> <!--blank-->
<!entity hubsect-connprotsopc       SYSTEM "sect_connprotsopc.sgml">
...

The hubsect-excelexample has a <!--blank--> comment at the end to remind us that this example section doesn't appear in the DataHub book, only in the Connect book. The entity still needs to be defined for the DataHub book, though, since both books share a common source file. But the actual file is blank.

Images

Images follow the general pattern given above. Images unique to the Connect manual are all prefixed with ccw, those for the DataHub manual with dhw. In the source text, the &hub; entity is used as a place-holder, and gets replaced with the correct name by the copydatahub.sh script. For example, the image referred to as &hub;-smallicon.gif would be correspond to the image files ccw-smallicon.gif and dhw-smallicon.gif.

There are some images that are identical for both books. These are labelled with the prefix dcw-, which means they apply to both Connect and the DataHub. For example, the image named dcw-prop-butdde.gif is the DDE properties button, which is the same in both GUIs.