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| Parameter | Required | Default value | Allowed values | Description |
|---|---|---|---|---|
| CorrectLegacyHyperlinkSyntaxToDITA | No | no | yes, no | When set to yes, the plugin will also correct legacy hyperlink syntax to valid DITA syntax. |
| DraftWhenInvalidHyperlinks | No | yes | yes, no | When set to yes, an hyperlink target that cannot be found will set the publication output to Draft (not Release Candidate). |
| SkipHyperlinkSyntaxCorrectionForImages | No | yes | yes, no | If CorrectLegacyHyperlinkSyntaxToDITA is set to yes and if the hyperlink to an image contains an anchor, this parameter determines what happens to the anchor:
|
| SkipHyperlinkSyntaxCorrectionForTemplates | No | yes | yes, no | If CorrectLegacyHyperlinkSyntaxToDITA is set to yes and if the hyperlink to a template or other object contains an anchor, this parameter determines what happens to the anchor:
|
| SkipValidationForAnchorRegEx | No | A string containing a regular expression. | While correcting legacy hyperlinks (CorrectLegacyHyperlinkSyntaxToDITA=yes), the anchor is checked against the regular expression. For example, a regular expression
If the anchor matches the regular expression:
|
Plugin Outcome
- If the
CorrectLegacyHyperlinkSyntaxToDITAis 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 unless...- The anchor part of the hyperlink matches the regular expression configured in
SkipValidationForAnchorRegEx. - The hyperlink references an image and
SkipHyperlinkSyntaxCorrectionForImagesis set to yes. - The hyperlink references a template or other object and
SkipHyperlinkSyntaxCorrectionForTemplatesis set to yes.
- The anchor part of the hyperlink matches the regular expression configured in
context as a result: The ReportItems collection of the context is changed like this:
- The
TargetValidproperty of theReportItemis set:- When the target refers to an existing exported object, the property set to
Found - When the target refers to an unexisting 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
- When the target refers to an existing exported object, the property set to
- If the
CorrectLegacyHyperlinkSyntaxToDITAis set to yes, therefproperty in theLinks,Hyperlinks, etc. properties of theReportItemare 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>
<parameter name="SkipValidationForAnchorRegEx">^(line-range|line|token)</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
CorrectLegacyHyperlinkSyntaxToDITAis set toyes, the plugins checks theHyperlinksproperty 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 theHyperlinksproperty. - A list of all key definitions is build using the
KeyDefinitionsproperty 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
referenceandkeyrefvalues of theLinks,ImageLinks,Hyperlinks,Conrefsproperties are analyzed. If akeyrefis found, thekeyrefis looked up in the key definitions list and if thekeyexists thehrefvalue of it is used. (This plugin does not support key definitions that in turn use akeyrefagain (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
TargetValidproperty of the report item is set depending whether the target is found or not. For external references, like anhttplocation, no check is performed. - When the
TargetValidis set toNotFoundfor one entry in theLinks,ImageLinksorConrefsproperty, this plugin will call theRejectReleaseCandidatemethod to indicate that the output should be considered as aDraft. - When the
TargetValidis set toNotFoundfor one entry in theHyperlinksand theDraftWhenInvalidHyperlinksis set toyes, this plugin will call theRejectReleaseCandidatemethod to indicate that the output should be considered as aDraft.
- If the