..
/
download
s1kd-aspp(1) s1kd-tools s1kd-aspp(1)
NAME
s1kd-aspp - Applicability statement preprocessor
SYNOPSIS
s1kd-aspp [options] [<object> ...]
DESCRIPTION
The s1kd-aspp tool has two main functions:
· Generates display text for applicability statements. The text is de‐
rived from the logic described by the assert and evaluate elements.
· Preprocesses "semantic" applicability statements in a data module to
produce "presentation" applicability statements which are simpler to
parse in an XSLT stylesheet.
"Semantic" applicability statements are those entered by the author to
encode the applicability of elements within a data module. "Presenta‐
tion" applicability statements are those that are actually displayed in
page-oriented output, also referred to as the "human-readable" state‐
ments.
The applicability in the resulting XML is longer semantically correct,
but an XSLT stylesheet can simply place a statement on any element with
attribute applicRefId without needing to consider inherited applicabil‐
ity statements on elements without the attribute.
OPTIONS
-., --dump-disptext
Dump the built-in .disptext file.
-,, --dump-xsl
Dump the built-in XSLT used to generate display text for appli‐
cability statements.
-A, --act <ACT>
Add an ACT to use when generating display text for product at‐
tributes. Multiple ACT data modules can be used by specifying
this option multiple times.
-a, --id <ID>
The ID to use for the inline applicability annotation represent‐
ing the whole data module's applicability. Default is
"app-0000".
-C, --cct <CCT>
Add a CCT to use when generating display text for conditions.
Multiple CCT data modules can be used by specifying this option
multiple times.
-c, --search
Search for the ACT and CCT referenced by each data module, and
add them to the list of ACTs/CCTs to use when generating display
text for that data module.
-D, --delete
Remove the display text from all applicability annotations, ex‐
cept those that consist of only display text (and no computer
processing part).
-d, --dir <dir>
Directory to start searching for ACT/CCT data modules in. By
default, the current directory is used.
-F, --format <fmt>
Use a custom format string to generate display text.
-f, --overwrite
Overwrite input data module(s) rather than outputting to stdout.
-G, --disptext <disptext>
Specify a custom .disptext file.
-g, --generate
Generate display text for applicability statements.
-h, -?, --help
Show help/usage message.
-k, --keep
When generating display text, do not overwrite existing display
text on statements, only generate display text for statements
which have none.
-l, --list
Treat input (stdin or arguments) as lists of filenames of ob‐
jects, rather than objects themselves.
-N, --omit-issue
Assume that the filenames for the ACT and CCT do not include is‐
sue info, i.e. they were created using the -N option of the
s1kd-newdm tool.
-p, --presentation
Preprocess applicability statements to produce "presentation"
applicability statements which are simpler to parse in an XSLT
stylesheet. The applicability in the resulting XML is no longer
semantically correct.
-r, --recursive
Search for ACT/CCT data modules recursively.
-t, --tags <mode>
Add tags before elements containing the display text of the ap‐
plicability annotation they reference, simulating the typical
presentation of applicability annotations within the XML.
If <mode> is "pi", the tags are inserted as processing instruc‐
tions, named "s1kd-aspp". This allows existing tags to be re‐
moved automatically before adding new ones.
If <mode> is "comment", the tags are inserted as XML comments.
Existing comments will not be removed automatically.
If <mode> is "remove", tags will be removed without adding new
ones. This only applies to the processing instruction tags.
-v, --verbose
Verbose output.
-x, --xsl <XSLT>
Use custom XSLT to generate display text for applicability
statements.
--version
Show version information.
<object> ...
The object(s) to preprocess. This can include both individual
objects and combined files such as those produced by s1kd-flat‐
ten(1).
In addition, the following options allow configuration of the XML pars‐
er:
--dtdload
Load the external DTD.
--huge Remove any internal arbitrary parser limits.
--net Allow network access to load external DTD and entities.
--noent
Resolve entities.
--parser-errors
Emit errors from parser.
--parser-warnings
Emit warnings from parser.
--xinclude
Do XInclude processing.
--xml-catalog <file>
Use an XML catalog when resolving entities. Multiple catalogs
may be loaded by specifying this option multiple times.
.disptext file
This file specifies rules for generating display text. It consists of:
· operator rules
· property rules
The <operators> element specifies the format of operators used in dis‐
play text:
and Text to use for the and operator between assertions. Default is
" and ".
or Text to use for the or operator between assertions. Default is
" or ".
openGroup
Text to use to open a group of assertions. Default is "(".
closeGroup
Text to use to close a group of assertions. Default is ")".
set Text to use between items in a set (a|b|c).
range Text to use between the start and end of a range (a~c).
Each <property> element specifies the format used for an individual
property. The <productAttributes> and <conditions> elements specify
the default format for product attributes and conditions that are not
listed. Alternatively, the <default> element specifies the default
format for both product attributes and conditions together.
The format is specified using a combination of the following elements:
<name> Replaced by the name of the property.
<text> Text that is included as-is.
<values>
Replaced by the values specified for the property in the appli‐
cability assertion.
Optionally, <values> may contain a list of custom labels for individual
values. Any values not included in this list will use their normal la‐
bel.
By default, the program will search for a file named .disptext in the
current directory and parent directories, but any file can be specified
using the -G (--disptext) option.
Example of a .disptext file:
<disptext>
<operators>
<and> + </and>
<or>, </or>
<openGroup>[</openGroup>
<closeGroup>]</closeGroup>
<set> or </set>
<range> thru </range>
</operators>
<default>
<name/>
<text>: </text>
<values/>
</default>
<property ident="model" type="prodattr">
<values>
<value match="BRKTRKR">Brook trekker</value>
<value match="MNTSTRM">Mountain storm</value>
</values>
<text> </text>
<name/>
</property>
</disptext>
Given the above example, the following display would be generated for
each annotation:
Assert annotation:
<assert
applicPropertyIdent="model"
applicPropertyType="prodattr"
applicPropertyValues="BRKTRKR"/>
Human-readable format:
"Brook trekker Model"
Evaluate annotation:
<evaluate andOr="or">
<evaluate andOr="and">
<assert
applicPropertyIdent="model"
applicPropertyType="prodattr"
applicPropertyValues="BRKTRKR"/>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="Mk1"/>
</evaluate>
<evaluate andOr="and">
<assert
applicPropertyIdent="model"
applicPropertyType="prodattr"
applicPropertyValues="MNTSTRM"/>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="Mk9"/>
</evaluate>
</evaluate>
Human-readable format:
"[Brook trekker Model + Version: Mk9],
[Mountain storm Model + Version: Mk1]"
Evaluate annotation:
<evaluate andOr="and">
<assert
applicPropertyIdent="model"
applicPropertyType="prodattr"
applicPropertyValues="BRKTRKR|MNTSTRM"/>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="Mk1~Mk9"/>
</evaluate>
Human-readable format:
"Brook trekker or Mountain storm Model + Version: Mk1 thru Mk9"
EXAMPLES
Generating display text
The built-in XSLT for generating display text follows the guidance in
Chap 7.8 of the S1000D 5.0 specification. For example, given the fol‐
lowing:
<applic>
<assert applicPropertyIdent="prodversion"
applicPropertyType="prodattr" applicPropertyValues="A"/>
</applic>
The resulting XML would contain:
<applic>
<displayText>
<simplePara>prodversion: A</simplePara>
</displayText>
<assert applicPropertyIdent="prodversion"
applicPropertyType="prodattr" applicPropertyValues="A"/>
</applic>
If ACTs or CCTs are supplied which define display names for a property,
this will be used instead of the ident. For example, the ACT defines
the display name for the "prodversion" product attribute:
<productAttribute id="prodversion">
<name>Product version</name>
<displayName>Version</displayName>
<descr>The version of the product.</descr>
<enumeration applicPropertyValues="A|B|C"/>
</productAttribute>
When supplied with the -A option:
$ s1kd-aspp -g -A <ACT> <DM>
The resulting XML would instead contain:
<applic>
<displayText>
<simplePara>Version: A</simplePara>
<assert applicPropertyIdent="prodversion"
applicPropertyType="prodattr" applicPropertyValues="A"/>
</displayText>
</applic>
The methods for generating display text can be changed either via the
.disptext file, or by supplying a custom XSLT script with the -x op‐
tion. The -, option can be used to dump the built-in XSLT as a start‐
ing point for a custom script.
Display text format string (-F)
The -F option allows for very simple customizations to generated dis‐
play text without needing to create a custom .disptext file or XSLT
script (-x). The string determines the format of the display text of
each <assert> element in the annotation.
The following variables can be used within the format string:
%name% The name of the property.
%values%
The applicable value(s) of the property.
For example:
$ s1kd-aspp -g <DM>
...
<applic>
<displayText>
<simplePara>Version: A</simplePara>
</displayText>
<assert applicPropertyIdent="version" applicPropertyType="prodattr"
applicPropertyValues="A"/>
</applic>
...
$ s1kd-aspp -F '%name% = %values%' -g <DM>
...
<applic>
<displayText>
<simplePara>Version = A</simplePara>
</displayText>
<assert applicPropertyIdent="version" applicPropertyType="prodattr"
applicPropertyValues="A"/>
</applic>
...
Creating presentation applicability statements
Given the following:
<dmodule>
<identAndStatusSection>
<dmAddress>...</dmAddress>
<dmStatus>
...
<applic>
<displayText>
<simplePara>A or B</simplePara>
</displayText>
</applic>
...
</dmStatus>
</identAndStatusSection>
<content>
<referencedApplicGroup>
<applic id="app-B">
<displayText>
<simplePara>B</simplePara>
</displayText>
</applic>
</referencedApplicGroup>
<procedure>
<preliminaryRqmts>...</preliminaryRqmts>
<mainProcedure>
<proceduralStep>
<para>This step is applicable to A or B.</para>
</proceduralStep>
<proceduralStep applicRefId="app-B">
<para>This step is applicable to B only.</para>
</proceduralStep>
<proceduralStep applicRefId="app-B">
<para>This step is also applicable to B only.</para>
</proceduralStep>
<proceduralStep>
<para>This step is also applicable to A or B.</para>
</proceduralStep>
</mainProcedure>
<closeRqmts>...</closeRqmts>
</procedure>
</content>
</dmodule>
Applicability statements should be displayed whenever applicability
changes:
1. This step is applicable to A or B.
2. Applicable to: B
This step is applicable to B only.
3. This step is also applicable to B only.
4. Applicable to: A or B
This step is also applicable to A or B.
There are two parts which are difficult to do in an XSLT stylesheet:
· No statement is shown on Step 3 despite having attribute applicRefId
because the applicability has not changed since the last statement on
Step 2.
· A statement is shown on Step 4 despite not having attribute applicRe‐
fId because the applicability has changed back to that of the whole
data module.
Using the s1kd-aspp tool, the above XML would produce the following
output:
<dmodule>
<identAndStatusSection>
<dmAddress>...</dmAddress>
<dmStatus>
...
<applic>
<displayText>
<simplePara>A or B</simplePara>
</displayText>
</applic>
...
</dmStatus>
</identAndStatusSection>
<content>
<referencedApplicGroup>
<applic id="app-B">
<displayText>
<simplePara>B</simplePara>
</displayText>
</applic>
<applic id="app-0000">
<displayText>
<simplePara>A or B</simplePara>
</displayText>
</applic>
</referencedApplicGroup>
<procedure>
<preliminaryRqmts>...</preliminaryRqmts>
<mainProcedure>
<proceduralStep>
<para>This step is applicable to A or B.</para>
</proceduralStep>
<proceduralStep applicRefId="app-B">
<para>This step is applicable to B only.</para>
</proceduralStep>
<proceduralStep>
<para>This step is also applicable to B only.</para>
</proceduralStep>
<proceduralStep applicRefId="app-0000">
<para>This step is also applicable to A or B.</para>
</proceduralStep>
</mainProcedure>
</procedure>
</content>
</dmodule>
With attribute applicRefId only on those elements where a statement
should be shown, and an additional inline applicability to represent
the whole data module's applicability. This XML is semantically incor‐
rect but easier for a stylesheet to transform for page-oriented output.
DISPTEXT FILE SCHEMA
Display text rules
The element <disptext> contains all the rules for the formatting of
generated display text in applicability annotations.
Markup element: <disptext>
Attributes:
· None
Child elements:
· <operators>
· <default>
· <productAttributes>
· <conditions>
· <conditionType>
· <property>
Operator rules
The element <operators> defines the format of operators used in appli‐
cability display text.
Markup element: <operators>
Attributes:
· None
Child elements:
· <and>, text used for the and operator between assertions in an evalu‐
ation.
· <or>, text used for the or operator between assertions in an evalua‐
tion.
· <openGroup>, text used to open a group of assertions.
· <closeGroup>, text used to close a group of assertions.
· <set>, text used between items in a set.
· <range>, text used between the start and end of a range.
Default property format
The element <default> defines the default format for all properties
which are not matched by a more specific rule.
Markup element: <default>
Attributes:
· None
Child elements:
· <name>, replaced by the name of the property.
· <text>, text that is included as-is.
· <values>, replaced by the values specified for the property in the
applicability assertion.
Product attributes format
The element <productAttributes> defines the default format for all
product attributes which are not matched by a more specific rule.
Markup element: <productAttributes>
Attributes:
· None
Child elements:
· <name>, replaced by the name of the product attribute.
· <text>, text that is included as-is.
· <values>, replaced by the values specified for the product attribute
in the applicability assertion.
Conditions format
The element <conditions> defines the default format for all conditions
which are not matched by a more specific rule.
Markup element: <conditions>
Attributes:
· None
Child elements:
· <name>, replaced by the name of the condition.
· <text>, text that is included as-is.
· <values>, replaced by the values specified for the condition in the
applicability assertion.
Condition type format
The element <conditionType> defines the format for all conditions of a
given type which are not matched by a more specific rule.
Markup element: <conditionType>
Attributes:
· ident (M), the ID of the condition type in the CCT.
Child elements:
· <name>, replaced by the name of the condition.
· <text>, text that is included as-is.
· <values>, replaced by the values specified for the condition in the
applicability assertion.
Property format
The element <property> defines the format for a specific property.
Markup element: <property>
Attributes:
· ident (M), the ID of the property in the ACT or CCT.
· type (M), the type of the property, either "condition" or "prodattr".
Child elements:
· <name>, replaced by the name of the property.
· <text>, text that is included as-is.
· <values>, replaced by the values specified for the property in the
applicability assertion.
Values
The element <values> is replaced by the values specified for a property
in an applicability assertion, and may specify custom labels for cer‐
tain values.
Markup element: <values>
Attributes:
· None
Child elements:
· <value>
Custom value label
The element <value> specifies a custom label for an individual value of
a property.
Markup element: <value>
Attributes:
· match (M), the value to apply the custom label for.
Child elements:
· None
AUTHORS
khzae.net.
2021-04-16 s1kd-aspp(1)
gopher://khzae.net/0/s1000d/s1kd-tools/docs/publishing/s1kd-aspp.txt