# 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
    derived 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.
"Presentation" applicability statements are those that are actually
displayed in page-oriented output, also referred to as the
"human-readable" statements.

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
applicability 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
    applicability statements.

  - \-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.

  - \-a, --id \<ID\>  
    The ID to use for the inline applicability annotation representing
    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, except
    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 objects,
    rather than objects themselves.

  - \-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.

  - \-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
    applicability annotation they reference, simulating the typical
    presentation of applicability annotations within the XML.
    
    If \<mode\> is "pi", the tags are inserted as processing
    instructions, named "s1kd-aspp". This allows existing tags to be
    removed 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-flatten(1).

In addition, the following options allow configuration of the XML
parser:

  - \--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
display 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
    applicability assertion.

Optionally, `<values>` may contain a list of custom labels for
individual values. Any values not included in this list will use their
normal label.

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
following:

    <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
option. The -, option can be used to dump the built-in XSLT as a
starting point for a custom script.

## Display text format string (-F)

The -F option allows for very simple customizations to generated display
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
    `applicRefId` 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 incorrect
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
applicability display text.

*Markup element:* `<operators>`

*Attributes:*

  - None

*Child elements:*

  - `<and>`, text used for the `and` operator between assertions in an
    evaluation.

  - `<or>`, text used for the `or` operator between assertions in an
    evaluation.

  - `<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 certain 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