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:
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.
|Entity name||for the DataHub||for Connect||Usage|
|hubcont||the Cascade DataHub||Cascade Connect||As a noun, full name.|
|hubcont-||the DataHub||Connect||As a noun, informally.|
|hubconT||The Cascade DataHub||Cascade Connect||Full name, beginning of sentence.|
|hubconT-||The DataHub||Connect||Informally, beginning of sentence.|
|hubcon||Cascade DataHub||Cascade Connect||As an adjective, full name.|
|hubcon-||DataHub||Connect||As an adjective, informally.|
|hubconl-||datahub||connect||As a system item, eg. domain name.|
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 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.
Copyright © 1995-2004 by Cogent Real-Time Systems, Inc. All rights reserved.