Applicability in Publishing
Overview
XML topics can contain logical expressions to determine whether to include content at the element level. The markup that defines the options and choices that apply to some content is called inline applicability. The decision to include or exclude content is determined by evaluating this logical expression against the choices selected by the applicability filter at the time of publishing (or by the rootApplicabilityExpression parameter, if it is set in a publishing rule).
An applicability expression represents a subset of a product’s options and choices, which is used to annotate the content. The expression associates the content with a specific product or products, and it can then be used to filter it. Simple expressions can be combined using logical operators.
In the service structure user interface, you can set filtering for both the service structure and inline applicability for dynamic documents using the Filter action set on the toolbar of the Structure tab. Publishing applies the Option Filter to the publication structure and to its dynamic documents. If the publishing rule parameter rootApplicabilityExpression is set, it will overwrite the filtering expression defined using the Filter action set.
Inline applicability filtering is supported only for PDF and using XSL output types. In the case of bundle output, no filtering is applied during publishing as filtering is applied by a Servigistics InService user.
Applicability expressions need a parser that can decipher the options and choices expressions specified with intersecting and disjunctive operators such as AND, OR, and NOT.
Setting Up Stylesheets
If you want inline applicability expressions in the root service structure document Identfier.xml sent in the payload, you need to modify your pubstructXsl stylesheet so it copies applicability expressions from the Identfier.xml to the correct location in your output DITA map (such as topicref and topic elements).
Setting Up Publishing Rules
When creating publishing rules for PDF and XSL output, you should consider which publishing rule parameters to apply during publishing on the Arbortext PE server. You can use the basic applicability publishing rule parameters to apply to both structures and inline content in dynamic documents. The following are preceded by com.ptc.arbortext.pe/:
• applicabilitySyntax
Specify the name of applicability syntax used for applicability expressions in the payload. Specify the name that was registered on the Arbortext PE server using the applic::registerSyntax() ACL method. There is no default.
If a bundle is being published for use with Servigistics InService, and both the structures and their topics use ATO and the same source syntax, applicabilitySyntax is the only parameter needed for publishing bundles.
• rootApplicabilityExpression
Specify an applicability expression to apply to the entire service structure and its content during publishing. The expression syntax must match the syntax found in both the service structure and its XML textual content.
Applicability for inline dynamic documents is enabled or disabled using disableInlineApplicFiltering. Specify true (the default) to disable inline applicability, or specify false to enable it.
For more information on publishing rule parameters, see
Service Worker Parameters.
Implementing a Syntax Parser
Applicability syntax can take a basic form using labels from the Option Set, assuming the labels are unique choice names. Applicability expressions use operators to combine or discard choices. A parser is needed to evaluate the expression using a registered syntax.
To implement a new syntax parser, you need to use the following Java packages found on the Arbortext PE server in lib\classes\applicability.jar:
• com.ptc.arbortext.applicability.expression
A Java package that contains interfaces to support applicability expression objects for filtering content with Options and Choices data. Options elements have a Name, Description, and a set of Choice elements. The Option and the Choice elements have a label attribute which is used in the user interface and in applicability expressions. The labels are expected to be unique within each Option Set.
• com.ptc.arbortext.applicability.representation
A Java package that contains interfaces to support applicability markup for elements, attributes, content, and processing instructions.
In the payload, the options and choices are included in the OptionsDefinition.xml file.
Registering the Applicability Syntax
You need to register your applicability syntax on the Arbortext PE serverusing an ACL function before it can be used during publishing. Use the following registration function:
applic::registerSyntax(NAME, TEST_XPATH, EXPR_XPATH, PARSER_CLASS)
• NAME is the name of the applicability syntax.
• TEST_XPATH is an XPath boolean expression to check if there is an applicability expression for an element.
• EXPR_XPATH is an XPath expression that retrieves the applicability for a particular element.
• PARSER_CLASS is the class name of the parser for the applicability syntax.
An ATO parser is available on the server by default, registered as follows (ignore the line breaks):
applic::registerSyntax("ATO", "boolean(@*[namespace-uri() =
'http://arbortext.ptc.com/namespace/ATO'
and local-name() = 'applic'])",
"@*[namespace-uri() = 'http://arbortext.ptc.com/namespace/ATO'
and local-name() = 'applic']",
"com.ptc.arbortext.applicability.representation.ATOParser")
Applicability Expressions in Bundles
Applicability filtering is not performed during bundle publishing. Instead applicability expressions are converted into a format that can be applied in Servigistics InService.
Publication structure applicability is in the LogicalExpressionmetadata property. Applicability from topics is copied into the {http://arbortext.ptc.com/namespace/ATO}applic attribute and then converted.
The following inline applicability parameters apply to structures published to bundles:
• com.ptc.arbortext.pe.service/structureSourceApplicSyntax
Specify the name of the applicability syntax used for applicability expressions in the service structure. Specify the name registered by applic::registerSyntax on the Arbortext PE server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• com.ptc.arbortext.pe.service/structureTargetApplicSyntax
Specify the name of the applicability syntax used for applicability expressions after the service subsystem is finished processing. Specify the name registered by applic::registerSyntax on the Arbortext PE server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• disableStructureApplicabilityConverter
Specify whether to find and convert applicability expressions in a structure. Specify false, the default for bundles, to enable it. Specify true to disable. By default, it is disabled for PDF.
The following inline applicability parameters apply to topics published in bundles:
• com.ptc.arbortext.pe.service/topicCcfParam.sourceApplicabilitySyntax
Specify the name of the applicability syntax used for applicability expressions inside topics in the bundle. Specify the name registered on the Arbortext PE server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is ATO.
• com.ptc.arbortext.pe.service/topicCcfParam.targetApplicabilitySyntax
Specify the name of the applicability syntax used for applicability expressions inside topics after the service subsystem has finished processing. Specify the name registered on the Arbortext PE server. If not specified, the value of applicabilitySyntax is used. If applicabilitySyntax is not specified, the default is APEX.
• com.ptc.arbortext.pe.service/topicCcfParam.disableApplicabilityConverter
Specify whether to find and convert applicability expressions in a topic. Specify false, the default, to enable it. Specify true to disable it.
Profiling Applicability Expressions
Information elements can have profiling that was applied when being authored. The profiling markup can be converted to an applicability expression using an applicability syntax. The profiling conversion is controlled by the boolean publishing parameter com.ptc.arbortext.pe.service/topicCcfParam.disableProfilingConverter.
For example, the following markup could be found in an XML document, where os and userlevel specify profiling:
<chapter os="Windows Vista;Unix" userlevel="Novice">
A publishing request that specified the APEX syntax as the applicability expression would convert the profiling information to the following markup:
<book xmlns:prf=http://arbortext.ptc.com/namespace/
applicability/profiling prf:syntax="APEX"
prf:optionSet="axdocbook">
<chapter prf:applic="(AND (IS 'os' 'Windows Vista' 'Unix')
(IS 'userlevel' 'Novice'))">
</chapter>
</book>
The namespace URI for prf at the top level specifies a profiling configuration. The namespace profiling attribute is specified by the com.ptc.arbortext.pe.service/topicCcfParam.profilingAttribute publishing parameter.
The prf:syntax attribute specifies the syntax of the expression. The prf:optionSet attribute specifies the document type for the profiling configuration file being used.
The prf:applic attribute is placed on the element containing the profiling markup and assigned the converted expression.
The original profiling attributes can be removed from information elements when publishing to a bundle using the com.ptc.arbortext.pe.service/topicCcfParam.removeProfilingMarkup publishing parameter.
In the publishing payload, the OptionsDefinition.xml file contains the list of profiling configuration option sets. For the previous example, the option set might look like the following:
<OptionSet container="axdocbook.pcf" token="_oset_axdocbook_pcf"
label="Operating System, User Level, Output Type, Security Level Options">
<Option label="os" token="_opt_axdocbook_os"><Name>Operating System</Name>
<Choice label="Windows XP" token="_ch_axdocbook_pcf_os_windows_xp">
<Name>Windows XP</Name></Choice>
<Choice label="Windows Vista" token="_ch_axdocbook_pcf_os_windows_vista">
<Name>Windows Vista</Name></Choice>
<Choice label="Windows 7" token="_ch_axdocbook__pcf_os_windows_7">
<Name>Windows 7</Name></Choice>
<Choice label="Unix" token="_ch_axdocbook_pcf_os_unix">
<Name>Unix</Name></Choice>
</Option>
<Option label="userlevel" token="_opt_axdocbook_pcf_userlevel">
<Name>User Level</Name>
<Choice label="Novice" token="_ch_axdocbook_pcf_userlevel_novice">
<Name>Novice</Name></Choice>
<Choice label="Typical" token="_ch_axdocbook_pcf_userlevel_typical">
<Name>Typical</Name></Choice>
<Choice label="Expert" token="_ch_axdocbook_pcf_userlevel_expert">
<Name>Expert</Name></Choice>
</Option>
</OptionSet>
For more information on the profiling publishing parameters, see
Service Worker Parameters.