This method will replace references within the given ADocument. The references to be replaced are those listed as keys in the given PropertyMap, and will be replaced by the value of each associated PropertyMap key. If the given ADocument contains any inclusions (such as file entities or XIncludes), unlike IOHost::modifyReferences, this method will descend into those inclusions in order to update any references that might be found in their content if the reference is found as a key in the given PropertyMap.

What is considered an “inclusion”, as far as this method is concerned, is limited to file entities and XIncludes. Any elements or attributes of elements which are encountered that match a customref burst configuration file rule (as found in the burst configuration file associated with the doctype of the Document or CMSObject to which the scrutinized node belongs) is not considered an “inclusion” by this method since customref is a referencing mechanism and not intended for inline inclusions. Any matching customref references will be replaced by this method, but since customref is not considered an “inclusion ” mechanism, this method will not open the file or logical id the customref references in order to descend into its contents.

All keys in the PropertyMap that reference the file system will be made a canonicalized universal name before any lookups occur. Also, each reference that is to be looked up in the PropertyMap that is a filesystem reference will also be temporarily made into a canonicalized universal name before the lookup occurs. By making all filesystem references canonicalized universal names, the caller will be assured that multiple references that use different conventions but still reference the same filesystem location are actually recognized as the same reference. No such manipulation will be made to CMS logical ID references.

If the MODIFYREF_NO_CUSTOMREF flag is not included in the flags parameter, any elements or attributes of elements that are encountered that match a customref burst configuration file rule (as found in the burst configuration file associated with the doctype of the Document or CMSObject to which the scrutinized node belongs) will be recognized as a reference and as such will be modified as long as that reference is listed as a key in the given PropertyMap. If the mode of the customref rule is “dita-full”, then the reference will be replaced with the value of the relevant PropertyMap key, appended with any DITA fragment identifier (including the leading “#”) copied from the original reference. All customref rules whose mode is “dita-partial” are always ignored and never replaced by this method, even if the reference of the “dita-partial” customref is found as a key in the given PropertyMap.

Documents and CMSObjects have a notion of whether or not they contain unsaved modifications. The modified state of the Document or CMSObject to which the given DocumentFragment belongs will be preserved by this method.