Dynamic Merge
WebWorks Help 5.0 output that contains multiple books (two or more) can be merged dynamically. Instructions for dynamically merging WebWorks Help 5.0 are available. Currently Quadralay maintains a vb script called: wwh5merge.vbs that can be used to perform the actual merge operation.
Why is it Useful?
There are many applications of Dynamic Merge for WebWorks Help, but the underlying usefulness comes from the fact that you can take 2 or more independently generated WebWorks Help help-sets and combine then together, creating what appears to be a single and unified help-set of all the volumes merged together in a controllable display order. Some example uses:
- Breaking large projects into multiple, smaller projects.
- Use an end-user installation script to merge separate help-sets based on the end-user's needs.
Limitations
- Does not resolve hypertext links and cross-references between documents that are not in the same ePublisher project.
Merging by Hand
Any two or more generated WebWorks Help 4 or 5 volumes can be merged without using any script, however it is somewhat manual and requires post editing of certain output files. This should not be attempted without detailed knowledge of the WebWorks Help format.
Automating Dynamic Merge
Example using AutoMap and DMerge script
Demonstrates how to use the automap command line, wwh5merge.vbs script, and multiple express projects to create a unified help volume.
Ready-to-use zip file at: DynamicMerge.zip. Contains dmerge script, sample projects, stationery, and windows batch file.
Stationery Requirements
- Configure a marker style that captures the merge order value
- Configure a marker style that captures the merge grouping hierarchy value
Source Content Requirements
It is required that for every top-level ePublisher group, there is one document that contains a marker instance with the value of the merged sort order.
Available only in ePublisher 9.3 and above.
Prior to ePublisher 9.3 you were required to create an info.txt file in the wwhdata folder for each book (i.e Book Alpha, Book Beta) (See below, "Under the Hood").
- ePublisher Document Manager
- Marker with merge order value
- Marker with merge display value
Preparing Your Output Folders for Merging
Create an empty folder that will become the new merged WebWorks Help volume.
Copy the output folder of each separate previously generated WebWorks Help volume into a uniquely named sub-folder of your new folder.
- Run the wwh5merge.vbs script using the path of your new folder as the argument to the script.
- Your new folder is now ready to be used.
Running wwh5merge.vbs Using Windows CLI
Open command prompt and type the following:
cscript [path to wwh5merge.vbs] "[path to WebWorks Help 5.0 output folder]"
Windows CLI
What does wwh5merge.vbs do?
- With the output from each project deployed to a common “output” folder, with each sub-folder representing the output from each helpset, the script copies the index.html file and wwhelp folder from the first sub-folder to the root level of the output folder.
- Then it scans the collective output folder, finds the individual groups with their marker-configured info.txt files, and merges everything into a single cohesive helpset, accessible via the top-level index.html file.
- It also removes the duplicate wwhelp runtimes.
When the script is done, the contents of the new output folder are ready for distribution as a merged WebWorks Help 5.0 helpset.
Under the Hood
This section describes what the wwh5merge.vbs script is doing to the help volumes in order to create a final merged volume that is in the proper order.
Our example WebWorks Help 5.0 output contains two books (also known as groups) Book Alpha and Book Beta. Each of these books appear as top level groups in the ePublisher Document Manager (see below).
Document Manager
Volume Order in info.txt
The info.txt file can be empty or contain sort order information, contain additional group information, or both; however, info.txt must be present in order for the dynamic merge script (wwh5merge.vbs) to work correctly.
If info.txt is empty, the resultant merged WebWorks Help 5.0 helpset will display the default merge behavior, with both groups appearing as top level.
Default Merging
Changing the Volume Order
The sort order of each book can be changed by adding a numerical value to the first line of info.txt. For example, to display Book Alpha and Book Beta in reversed order, open info.txt for Book Alpha and enter 200 on the first line (See Figure 4). Then, open info.txt for Book Alpha and enter 100 on the first line (See Figure 5).
info.txt for Book Alpha
info.txt for Book Beta
The resultant merged WebWorks Help 5.0 helpset will display the specifed sort behavior, with both groups appearing in reversed order (see below).
Merge Order Modified
Adding Additional Group-Topics
Additional group-topics can be added to the display plane by specifiying your desired hiearchy in the second line of info.txt. For example, if you would like to nest Book Alpha under Nest_1/Down you will need to enter Nest_1/Down in the second line of info.txt (See Figure 7). If you would like to nest Book Beta under Nest_2/Down, you will need to enter Nest_2/Down in the second line of info.txt (See Figure 8).
info.txt for Book Alpha
info.txt for Book Beta
The resultant merged WebWorks Help 5.0 helpset will display the additional group-topics (See Figure 9).
Merge Groups Created
NOTE: You can specify both sort order and additional group-topics in info.txt for the merged helpsystem by including a numerical value (i.e. 100) in the first line and group-topic hiearchy (i.e. Nest/Down) in the second line.