Documentation Center

IPublishPostProcessPlugin - IshCheckReferences

This plugin will check that all link, image, hyperlink and conref, conrefend targets of every exported object refer to an existing object in the current publish operation. Optionally, some conversion can be done to convert a legacy target syntax (having GUID-X#ELEMENTID) to a correct DITA syntax (using GUID-X#TOPICID/ELEMENTID).

Plugin Input

Plugin configuration parameters
ParameterRequiredDefault valueAllowed valuesDescription
CorrectLegacyHyperlinkSyntaxToDITANonoyes, noWhen set to yes, the plugin will also correct legacy hyperlink syntax to valid DITA syntax.
DraftWhenInvalidHyperlinksNoyesyes, noWhen set to yes, an hyperlink target that cannot be found will set the publication output to Draft (not Release Candidate).

Input expected in the context.Items collection: None

Plugin Outcome

Changes made to the file system:
  • If the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, exported files having link, image, hyperlink and conref, conrefend targets with the legacy syntax will be loaded and the targets will be corrected to the DITA syntax
Values set in the context as a result: The ReportItems collection of the context is changed like this:
  • The TargetValid property of the ReportItem is set:
    • When the target refers to an existing exported object, the property set to Found
    • When the target refers to an un-existing object, the property is set to NotFound
    • When the target refers to an external object, like an http location, the property is set to Unknown
  • If the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, the ref property in the Links, Hyperlinks, etc. properties of the ReportItem are also corrected to the DITA syntax.

When one of the link, image, conref or conrefend targets is not found or when one of the hyperlink targets is not found and the DraftWhenInvalidHyperlink is set to yes, the RejectReleaseCandidate method is called and the resulting publication output will no longer be a Release Candidate.

plugin name="ISHCHECKREFERENCES" example


 <plugin name='ISHCHECKREFERENCES' handler='IshCheckReferences'>
	<description>
            Checks that the links, hyperlinks, conref, conrefend, keyrefs targets exist and updates the report items with the found status.
	</description>
	<initialize>
		<parameters>
			<!-- When the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, hyperlink reference values of the form LOGICALID#ELEMENTID will be corrected to the DITA -->
			<!-- syntactically correct LOGICALID#LOGICALID/ELEMENTID. -->   
			<parameter name='CorrectLegacyHyperlinkSyntaxToDITA'>no</parameter>
			<parameter name='DraftWhenInvalidHyperlinks'>yes</parameter>              
		</parameters>
	</initialize>
</plugin>

Plugin flow

IshCheckReferences does the following:
  • Goes through all the report items of the context and for every item:
    • If the CorrectLegacyHyperlinkSyntaxToDITA is set to yes, the plugins checks the Hyperlinks property of the report item, which contains all hyperlink information extracted during the publish export, and uses that to determine whether some hyperlinks need to be corrected from the legacy syntax to the proper DITA syntax. If there are hyperlinks that need to be corrected the relevant file is loaded from the file system, the reference attribute values are corrected and the file is saved again. At the same time the reference is also updated in the Hyperlinks property.
    • A list of all key definitions is build using the KeyDefinitions property of the report item that contains the values of the DITA keys attributes encountered when exporting the files during the publish.
    • A list is build with all logical ids and their potential target ids (all topic or element ids are considered to be potential targets).
    • The reference and keyref values of the Links, ImageLinks, Hyperlinks, Conrefs properties are analyzed. If a keyref is found, the keyref is looked up in the key definitions list and if the key exists the href value of it is used. (This plugin does not support key definitions that in turn use a keyref again (so double indirection)). Otherwise the ref value of the attribute is compared with the list of logical ids - potential targets to see whether the used value exist.
    • The TargetValid property of the report item is set depending whether the target is found or not. For external references, like an http location, no check is performed.
    • When the TargetValid is set to NotFound for one entry in the Links, ImageLinks or Conrefs property, this plugin will call the RejectReleaseCandidate method to indicate that the output should be considered as a Draft.
    • When the TargetValid is set to NotFound for one entry in the Hyperlinks and the DraftWhenInvalidHyperlinks is set to yes, this plugin will call the RejectReleaseCandidate method to indicate that the output should be considered as a Draft.