When you use Stylus Studio to diff documents (or folders), you select a source and a target. Stylus Studio considers the source document or folder to be the baseline, or current standard; the target document or folder is assumed to be some other version (it might be older or newer, for example) of the source. The Stylus Studio Diff tool illustrates how this other version, the target, differs from the source (or sources) you have selected.


Tip		You can open source and target documents in the XML Editor from the XML Diff Viewer - right click on the XML Diff Viewer background and select the document you want to edit from the short-cut menu of source and target documents displayed by Stylus Studio. This feature is context-sensitive - if you right-click on a node that has been removed, the target document will not be listed, for example.

The Diff Configuration File

You can save the information associated with a given XML diff session in a diff configuration file. Diff configuration files make it easy to perform a diff on the same set of XML documents over time. Examples of the information saved with the diff configuration file include the URLs of the source and target documents, and any settings made on the XML Diff menu or tool bar. Diff configuration files are created with a .dff extension.

Changes made to the source and target documents are detected by Stylus Studio the next time you open the diff configuration file, allowing you to diff the files at that time. (Whether or not the diff is run automatically when you open the diff configuration file depends on Autorun Diff settings on the Engine page of the Options dialog box. See When Does the Diff Run? for more information.)

What Diffs Are Calculated?

This section describes how Stylus Studio diffs XML documents and folders.

Documents - The Stylus Studio Diff engine compares source and target documents in their entirety. If you want, you can use the Engine page of the Options dialog box to exclude certain items from the diff calculation. These items include:

Processing instructions

You can also specify whether or not you want Stylus Studio to:

Use URIs to compare namespaces

Expand entity references

Ignore text formatting characters (new lines, carriage returns, and tabs)

See Modifying Default Diff Settings to learn how to set these and other diff options.

Folders - Options for diffing XML documents do not affect how Stylus Studio diffs folders. When diffing folders, Stylus Studio compares one folder's contents with another. See Diffing Foldersfor more information on this topic.

Tuning the Diffing Algorithm

The purpose of any diffing tool is to identify the list of logical operations required to change the source document into the target document. Examples of logical operations include additions, revisions, and deletions. Even diffs between simple XML documents can yield a long list, sometimes with redundant operations. Ideally, the list of operations should be reduced to make it as economical as possible; that is, the list should be able to answer the question, What are the fewest number of changes required to turn the source into the target?

Calculating such a list can be time-consuming and resource intensive, and these costs might not be worth the benefits to a given user. For this reason, Stylus Studio provides settings that let you tune the diffing algorithm used by the XML Diff engine. Tuning settings are displayed in the Performance group box on the Engine page of the Options dialog box.

Figure 127. Performance Settings Let You Tune the Diffing Algorithm

You can

Select a tuning that optimizes the algorithm to provide the most economical set of changes possible (Optimize change description). As described earlier, this calculation, though it yields the best results, can be costly in terms of time and processing resources.

Select a tuning that optimizes the algorithm to provide the set of changes in the shortest time possible (Optimize calculation time).

Let Stylus Studio decide (Autodetect). By default, Stylus Studio tries to provide the most economical set of changes possible, but if it determines that processing resources are limited or that the calculation will take too much time, it reverts to the algorithm tuning that is optimized for speed.

Handling Large Documents

The Optimize for large documents with few changes setting helps speed the diffing of large (greater than 1MB) documents. This setting can be used in conjunction with any of the algorithm tuning settings and is on by default.

When Does the Diff Run?

Stylus Studio runs the diff automatically, as soon as you specify the target document or folder. Whether or not subsequent changes cause Stylus Studio to automatically recalculate the diff is determined by the Autorun Diff settings on the Engine page of the Options dialog box. Changes that can make a diff recalculation necessary include adding new source and target documents, changing the underlying source and target documents themselves, or to changes to certain Engine settings.

Options That Affect When the Diff Runs

These settings, on the Engine page of the Options dialog box, determine when and whether Stylus Studio automatically recalculates the diff.

On changes - Certain types of changes to the diff configuration file require Stylus Studio to recalculate the diff. These changes include:

Adding a new source document

Changing the target document

Changing the Use URI to compare namespaces setting

Changing the Expand entity references setting

If the On changes setting is on, Stylus Studio automatically runs the diff when any of these changes occurs.

If files modified - If you make and save changes to a source or target document, Stylus Studio automatically runs the diff if this setting is on.


Note		These settings do not affect the diffing of folders.

See Modifying Default Diff Settingsto learn more about setting these and other Diff options.

Running the Diff Manually

You can run the diff manually by clicking the Calculate diff button ( ). Stylus Studio activates this button when it detects the need to recalculate the diff, and the On changes or If files modified settings are off. These settings, as described in When Does the Diff Run?, cause Stylus Studio to run the diff automatically.

You can also run the diff from the command line. See Running the Diff Tool from the Command Line.

Symbols and Background Colors

Stylus Studio uses symbols and background colors to alert you to differences in diffed documents and folders. The following table summarizes the symbols and default background colors, and the types of changes they represent.

Table 16. Default Colors Used for Diffing Files and Folders
Symbol	Background Color	Identifies
	Light green	Added items; appears in the target document and identifies an item that is present in the target but absent from the source
	Light red	Removed items; appears in the source document and identifies an item that is present in the source but absent from the target.
	Light yellow	Changed items; can appear in both source and target documents.
	Light gray	Collapsed item containing changes (such as an added, changed, or removed node).

You can change the background colors on the Presentation page of the Options dialog box.

Combined Symbols

As described in Table 16, Default Colors Used for Diffing Files and Folders, Stylus Studio displays a turquoise block ( ) when a node that you have collapsed contains changes. Sometimes, the node itself has changes. In this case, Stylus Studio combines two symbols - one indicating the change of a child within the collapsed node, and one to the node itself. Consider the following illustration: