View source for Compare topic maps

== Using comparison tool ==

Topic map comparison tool compares two topic maps finding differences between the two. To start the tool select '''File > Compare and patch > Compare topic maps...''' This will open the comparison tool dialog. 

[[Image:Wandora_compare.gif|center]]

In the tool dialog you need to select source for the two topic maps to be compared. You can select a file, a single layer in the currently open project or the entire layer stack of the currently open project.

Finally you must select an output format. Currently two formats are available. '''HTML format''' produces a human readable output while '''patch format''' produces a more compact representation. The output of patch format can also be used with the [[Topic map patcher]] tool.

The output of the comparison tool will be opened in a simple text editor that can also be used to save the output, for example to save a patch file for the patcher tool.

== Comparison details ==

Comparison is done by processing each topic and association of both topic maps separately. Two topics in different topic maps are considered to be the same topic when they merge with each other but with no other topic in the other topic map. That is, when there is a clear one to one merging relationship between the topics. This is the basis of the topic map comparison and the principle how topics in the two topic maps are matched.

Comparison tool will produce five kinds of output entries: topic changed, topic added, topic deleted, association added or association deleted. The topic entries will also contain sub entries containing details about the changes made to the topic.

Topic changed entries will be produced when two topics are matched, as described above, but their contents are not identical. If the contents are identical, no output entry is generated for either of the topics. Topic contents consist of the base name, subject identifiers, subject locator, types and variant names. Associations are not part of topic contents as they are processed independently.

Topic added entries are produced when the second topic map contains a topic that cannot be matched with any topic in the first topic map. Topic deleted entries are produced in opposite cases when the first topic map contains a topic that cannot be matched with any topic in the second topic map. 

Topic added and deleted entries are also produced when one topic in either topic map matches with more than one topic in the other topic map. These are cases when two topics have been merged or split. Topics in the first topic map are reported as deleted and topics in the second topic map as added.

Associations are never reported as changed. Associations in the first topic map that are not found in the second topic map are reported as deleted and vice versa, associations in the second topic map that are not found in the first topic map are reported as added.

Note that association matching is dependent on topic matching. Association type, all roles and all players need to match for two associations to be considered the same. If there are more than one merging topic for any one of these in the other topic map then there will be no matching association for that association in the other topic map.

Similarly the comparison of topic contents depends on matching of other topics. Specifically, topic types and variant name scopes are dependent on this. Variant names can be considered identical or changed only when the scope topics match the topics of a scope in the other topic. In other cases variant names will be reported as deleted and/or added.