.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-aspp" "1" "2021-04-16" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-aspp - Applicability statement preprocessor
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-aspp [options] [<object> ...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-aspp\f[R] tool has two main functions:
.IP \[bu] 2
Generates display text for applicability statements.
The text is derived from the logic described by the \f[C]assert\f[R] and
\f[C]evaluate\f[R] elements.
.IP \[bu] 2
Preprocesses \[dq]semantic\[dq] applicability statements in a data
module to produce \[dq]presentation\[dq] applicability statements which
are simpler to parse in an XSLT stylesheet.
.PP
\[dq]Semantic\[dq] applicability statements are those entered by the
author to encode the applicability of elements within a data module.
\[dq]Presentation\[dq] applicability statements are those that are
actually displayed in page-oriented output, also referred to as the
\[dq]human-readable\[dq] statements.
.PP
The applicability in the resulting XML is longer semantically correct,
but an XSLT stylesheet can simply place a statement on any element with
attribute \f[C]applicRefId\f[R] without needing to consider inherited
applicability statements on elements without the attribute.
.SH OPTIONS
.TP
-., --dump-disptext
Dump the built-in .disptext file.
.TP
-,, --dump-xsl
Dump the built-in XSLT used to generate display text for applicability
statements.
.TP
-A, --act <ACT>
Add an ACT to use when generating display text for product attributes.
Multiple ACT data modules can be used by specifying this option multiple
times.
.TP
-a, --id <ID>
The ID to use for the inline applicability annotation representing the
whole data module\[aq]s applicability.
Default is \[dq]app-0000\[dq].
.TP
-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.
.TP
-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.
.TP
-D, --delete
Remove the display text from all applicability annotations, except those
that consist of only display text (and no computer processing part).
.TP
-d, --dir <dir>
Directory to start searching for ACT/CCT data modules in.
By default, the current directory is used.
.TP
-F, --format <fmt>
Use a custom format string to generate display text.
.TP
-f, --overwrite
Overwrite input data module(s) rather than outputting to stdout.
.TP
-G, --disptext <disptext>
Specify a custom .disptext file.
.TP
-g, --generate
Generate display text for applicability statements.
.TP
-h, -?, --help
Show help/usage message.
.TP
-k, --keep
When generating display text, do not overwrite existing display text on
statements, only generate display text for statements which have none.
.TP
-l, --list
Treat input (stdin or arguments) as lists of filenames of objects,
rather than objects themselves.
.TP
-N, --omit-issue
Assume that the filenames for the ACT and CCT do not include issue info,
i.e.
they were created using the -N option of the s1kd-newdm tool.
.TP
-p, --presentation
Preprocess applicability statements to produce \[dq]presentation\[dq]
applicability statements which are simpler to parse in an XSLT
stylesheet.
The applicability in the resulting XML is no longer semantically
correct.
.TP
-r, --recursive
Search for ACT/CCT data modules recursively.
.TP
-t, --tags <mode>
Add tags before elements containing the display text of the
applicability annotation they reference, simulating the typical
presentation of applicability annotations within the XML.
.RS
.PP
If <mode> is \[dq]pi\[dq], the tags are inserted as processing
instructions, named \[dq]s1kd-aspp\[dq].
This allows existing tags to be removed automatically before adding new
ones.
.PP
If <mode> is \[dq]comment\[dq], the tags are inserted as XML comments.
Existing comments will not be removed automatically.
.PP
If <mode> is \[dq]remove\[dq], tags will be removed without adding new
ones.
This only applies to the processing instruction tags.
.RE
.TP
-v, --verbose
Verbose output.
.TP
-x, --xsl <XSLT>
Use custom XSLT to generate display text for applicability statements.
.TP
--version
Show version information.
.TP
<object> ...
The object(s) to preprocess.
This can include both individual objects and combined files such as
those produced by s1kd-flatten(1).
.PP
In addition, the following options allow configuration of the XML
parser:
.TP
--dtdload
Load the external DTD.
.TP
--huge
Remove any internal arbitrary parser limits.
.TP
--net
Allow network access to load external DTD and entities.
.TP
--noent
Resolve entities.
.TP
--parser-errors
Emit errors from parser.
.TP
--parser-warnings
Emit warnings from parser.
.TP
--xinclude
Do XInclude processing.
.TP
--xml-catalog <file>
Use an XML catalog when resolving entities.
Multiple catalogs may be loaded by specifying this option multiple
times.
.SS \f[C].disptext\f[R] file
.PP
This file specifies rules for generating display text.
It consists of:
.IP \[bu] 2
operator rules
.IP \[bu] 2
property rules
.PP
The \f[C]<operators>\f[R] element specifies the format of operators used
in display text:
.TP
and
Text to use for the \f[C]and\f[R] operator between assertions.
Default is \[dq] and \[dq].
.TP
or
Text to use for the \f[C]or\f[R] operator between assertions.
Default is \[dq] or \[dq].
.TP
openGroup
Text to use to open a group of assertions.
Default is \[dq](\[dq].
.TP
closeGroup
Text to use to close a group of assertions.
Default is \[dq])\[dq].
.TP
set
Text to use between items in a set (a|b|c).
.TP
range
Text to use between the start and end of a range (a\[ti]c).
.PP
Each \f[C]<property>\f[R] element specifies the format used for an
individual property.
The \f[C]<productAttributes>\f[R] and \f[C]<conditions>\f[R] elements
specify the default format for product attributes and conditions that
are not listed.
Alternatively, the \f[C]<default>\f[R] element specifies the default
format for both product attributes and conditions together.
.PP
The format is specified using a combination of the following elements:
.TP
<name>
Replaced by the name of the property.
.TP
<text>
Text that is included as-is.
.TP
<values>
Replaced by the values specified for the property in the applicability
assertion.
.PP
Optionally, \f[C]<values>\f[R] may contain a list of custom labels for
individual values.
Any values not included in this list will use their normal label.
.PP
By default, the program will search for a file named \f[C].disptext\f[R]
in the current directory and parent directories, but any file can be
specified using the -G (--disptext) option.
.PP
Example of a \f[C].disptext\f[R] file:
.IP
.nf
\f[C]
<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=\[dq]model\[dq] type=\[dq]prodattr\[dq]>
<values>
<value match=\[dq]BRKTRKR\[dq]>Brook trekker</value>
<value match=\[dq]MNTSTRM\[dq]>Mountain storm</value>
</values>
<text> </text>
<name/>
</property>
</disptext>
\f[R]
.fi
.PP
Given the above example, the following display would be generated for
each annotation:
.PP
Assert annotation:
.IP
.nf
\f[C]
<assert
applicPropertyIdent=\[dq]model\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]BRKTRKR\[dq]/>
\f[R]
.fi
.PP
Human-readable format:
.IP
.nf
\f[C]
\[dq]Brook trekker Model\[dq]
\f[R]
.fi
.PP
Evaluate annotation:
.IP
.nf
\f[C]
<evaluate andOr=\[dq]or\[dq]>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]model\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]BRKTRKR\[dq]/>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]Mk1\[dq]/>
</evaluate>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]model\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]MNTSTRM\[dq]/>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]Mk9\[dq]/>
</evaluate>
</evaluate>
\f[R]
.fi
.PP
Human-readable format:
.IP
.nf
\f[C]
\[dq][Brook trekker Model + Version: Mk9],
[Mountain storm Model + Version: Mk1]\[dq]
\f[R]
.fi
.PP
Evaluate annotation:
.IP
.nf
\f[C]
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]model\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]BRKTRKR|MNTSTRM\[dq]/>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]Mk1\[ti]Mk9\[dq]/>
</evaluate>
\f[R]
.fi
.PP
Human-readable format:
.IP
.nf
\f[C]
\[dq]Brook trekker or Mountain storm Model + Version: Mk1 thru Mk9\[dq]
\f[R]
.fi
.SH EXAMPLES
.SS Generating display text
.PP
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 following:
.IP
.nf
\f[C]
<applic>
<assert applicPropertyIdent=\[dq]prodversion\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</applic>
\f[R]
.fi
.PP
The resulting XML would contain:
.IP
.nf
\f[C]
<applic>
<displayText>
<simplePara>prodversion: A</simplePara>
</displayText>
<assert applicPropertyIdent=\[dq]prodversion\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</applic>
\f[R]
.fi
.PP
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
\[dq]\f[C]prodversion\f[R]\[dq] product attribute:
.IP
.nf
\f[C]
<productAttribute id=\[dq]prodversion\[dq]>
<name>Product version</name>
<displayName>Version</displayName>
<descr>The version of the product.</descr>
<enumeration applicPropertyValues=\[dq]A|B|C\[dq]/>
</productAttribute>
\f[R]
.fi
.PP
When supplied with the -A option:
.IP
.nf
\f[C]
$ s1kd-aspp -g -A <ACT> <DM>
\f[R]
.fi
.PP
The resulting XML would instead contain:
.IP
.nf
\f[C]
<applic>
<displayText>
<simplePara>Version: A</simplePara>
<assert applicPropertyIdent=\[dq]prodversion\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</displayText>
</applic>
\f[R]
.fi
.PP
The methods for generating display text can be changed either via the
\f[C].disptext\f[R] file, or by supplying a custom XSLT script with the
-x option.
The -, option can be used to dump the built-in XSLT as a starting point
for a custom script.
.SS Display text format string (-F)
.PP
The -F option allows for very simple customizations to generated display
text without needing to create a custom \f[C].disptext\f[R] file or XSLT
script (-x).
The string determines the format of the display text of each
\f[C]<assert>\f[R] element in the annotation.
.PP
The following variables can be used within the format string:
.TP
%name%
The name of the property.
.TP
%values%
The applicable value(s) of the property.
.PP
For example:
.IP
.nf
\f[C]
$ s1kd-aspp -g <DM>
\&...
<applic>
<displayText>
<simplePara>Version: A</simplePara>
</displayText>
<assert applicPropertyIdent=\[dq]version\[dq] applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
\&...

$ s1kd-aspp -F \[aq]%name% = %values%\[aq] -g <DM>
\&...
<applic>
<displayText>
<simplePara>Version = A</simplePara>
</displayText>
<assert applicPropertyIdent=\[dq]version\[dq] applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
\&...
\f[R]
.fi
.SS Creating presentation applicability statements
.PP
Given the following:
.IP
.nf
\f[C]
<dmodule>
<identAndStatusSection>
<dmAddress>...</dmAddress>
<dmStatus>
\&...
<applic>
<displayText>
<simplePara>A or B</simplePara>
</displayText>
</applic>
\&...
</dmStatus>
</identAndStatusSection>
<content>
<referencedApplicGroup>
<applic id=\[dq]app-B\[dq]>
<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=\[dq]app-B\[dq]>
<para>This step is applicable to B only.</para>
</proceduralStep>
<proceduralStep applicRefId=\[dq]app-B\[dq]>
<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>
\f[R]
.fi
.PP
Applicability statements should be displayed whenever applicability
changes:
.IP "1." 3
This step is applicable to A or B.
.IP "2." 3
\f[I]Applicable to: B\f[R]
.RS 4
.PP
This step is applicable to B only.
.RE
.IP "3." 3
This step is also applicable to B only.
.IP "4." 3
\f[I]Applicable to: A or B\f[R]
.RS 4
.PP
This step is also applicable to A or B.
.RE
.PP
There are two parts which are difficult to do in an XSLT stylesheet:
.IP \[bu] 2
No statement is shown on Step 3 despite having attribute
\f[C]applicRefId\f[R] because the applicability has not changed since
the last statement on Step 2.
.IP \[bu] 2
A statement is shown on Step 4 despite not having attribute
\f[C]applicRefId\f[R] because the applicability has changed back to that
of the whole data module.
.PP
Using the s1kd-aspp tool, the above XML would produce the following
output:
.IP
.nf
\f[C]
<dmodule>
<identAndStatusSection>
<dmAddress>...</dmAddress>
<dmStatus>
\&...
<applic>
<displayText>
<simplePara>A or B</simplePara>
</displayText>
</applic>
\&...
</dmStatus>
</identAndStatusSection>
<content>
<referencedApplicGroup>
<applic id=\[dq]app-B\[dq]>
<displayText>
<simplePara>B</simplePara>
</displayText>
</applic>
<applic id=\[dq]app-0000\[dq]>
<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=\[dq]app-B\[dq]>
<para>This step is applicable to B only.</para>
</proceduralStep>
<proceduralStep>
<para>This step is also applicable to B only.</para>
</proceduralStep>
<proceduralStep applicRefId=\[dq]app-0000\[dq]>
<para>This step is also applicable to A or B.</para>
</proceduralStep>
</mainProcedure>
</procedure>
</content>
</dmodule>
\f[R]
.fi
.PP
With attribute \f[C]applicRefId\f[R] only on those elements where a
statement should be shown, and an additional inline applicability to
represent the whole data module\[aq]s applicability.
This XML is semantically incorrect but easier for a stylesheet to
transform for page-oriented output.
.SH DISPTEXT FILE SCHEMA
.SS Display text rules
.PP
The element \f[C]<disptext>\f[R] contains all the rules for the
formatting of generated display text in applicability annotations.
.PP
\f[I]Markup element:\f[R] \f[C]<disptext>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<operators>\f[R]
.IP \[bu] 2
\f[C]<default>\f[R]
.IP \[bu] 2
\f[C]<productAttributes>\f[R]
.IP \[bu] 2
\f[C]<conditions>\f[R]
.IP \[bu] 2
\f[C]<conditionType>\f[R]
.IP \[bu] 2
\f[C]<property>\f[R]
.SS Operator rules
.PP
The element \f[C]<operators>\f[R] defines the format of operators used
in applicability display text.
.PP
\f[I]Markup element:\f[R] \f[C]<operators>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<and>\f[R], text used for the \f[C]and\f[R] operator between
assertions in an evaluation.
.IP \[bu] 2
\f[C]<or>\f[R], text used for the \f[C]or\f[R] operator between
assertions in an evaluation.
.IP \[bu] 2
\f[C]<openGroup>\f[R], text used to open a group of assertions.
.IP \[bu] 2
\f[C]<closeGroup>\f[R], text used to close a group of assertions.
.IP \[bu] 2
\f[C]<set>\f[R], text used between items in a set.
.IP \[bu] 2
\f[C]<range>\f[R], text used between the start and end of a range.
.SS Default property format
.PP
The element \f[C]<default>\f[R] defines the default format for all
properties which are not matched by a more specific rule.
.PP
\f[I]Markup element:\f[R] \f[C]<default>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<name>\f[R], replaced by the name of the property.
.IP \[bu] 2
\f[C]<text>\f[R], text that is included as-is.
.IP \[bu] 2
\f[C]<values>\f[R], replaced by the values specified for the property in
the applicability assertion.
.SS Product attributes format
.PP
The element \f[C]<productAttributes>\f[R] defines the default format for
all product attributes which are not matched by a more specific rule.
.PP
\f[I]Markup element:\f[R] \f[C]<productAttributes>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<name>\f[R], replaced by the name of the product attribute.
.IP \[bu] 2
\f[C]<text>\f[R], text that is included as-is.
.IP \[bu] 2
\f[C]<values>\f[R], replaced by the values specified for the product
attribute in the applicability assertion.
.SS Conditions format
.PP
The element \f[C]<conditions>\f[R] defines the default format for all
conditions which are not matched by a more specific rule.
.PP
\f[I]Markup element:\f[R] \f[C]<conditions>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<name>\f[R], replaced by the name of the condition.
.IP \[bu] 2
\f[C]<text>\f[R], text that is included as-is.
.IP \[bu] 2
\f[C]<values>\f[R], replaced by the values specified for the condition
in the applicability assertion.
.SS Condition type format
.PP
The element \f[C]<conditionType>\f[R] defines the format for all
conditions of a given type which are not matched by a more specific
rule.
.PP
\f[I]Markup element:\f[R] \f[C]<conditionType>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]ident\f[R] (M), the ID of the condition type in the CCT.
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<name>\f[R], replaced by the name of the condition.
.IP \[bu] 2
\f[C]<text>\f[R], text that is included as-is.
.IP \[bu] 2
\f[C]<values>\f[R], replaced by the values specified for the condition
in the applicability assertion.
.SS Property format
.PP
The element \f[C]<property>\f[R] defines the format for a specific
property.
.PP
\f[I]Markup element:\f[R] \f[C]<property>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]ident\f[R] (M), the ID of the property in the ACT or CCT.
.IP \[bu] 2
\f[C]type\f[R] (M), the type of the property, either
\[dq]\f[C]condition\f[R]\[dq] or \[dq]\f[C]prodattr\f[R]\[dq].
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<name>\f[R], replaced by the name of the property.
.IP \[bu] 2
\f[C]<text>\f[R], text that is included as-is.
.IP \[bu] 2
\f[C]<values>\f[R], replaced by the values specified for the property in
the applicability assertion.
.SS Values
.PP
The element \f[C]<values>\f[R] is replaced by the values specified for a
property in an applicability assertion, and may specify custom labels
for certain values.
.PP
\f[I]Markup element:\f[R] \f[C]<values>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<value>\f[R]
.SS Custom value label
.PP
The element \f[C]<value>\f[R] specifies a custom label for an individual
value of a property.
.PP
\f[I]Markup element:\f[R] \f[C]<value>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]match\f[R] (M), the value to apply the custom label for.
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
None
.SH AUTHORS
khzae.net.