..
/
download
<?xml version="1.0"?>
<dmodule xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.s1000d.org/S1000D_5-0/xml_schema_flat/descript.xsd">
<identAndStatusSection>
<dmAddress>
<dmIdent>
<dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="11" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
<language languageIsoCode="en" countryIsoCode="CA"/>
<issueInfo issueNumber="009" inWork="00"/>
</dmIdent>
<dmAddressItems>
<issueDate year="2020" month="09" day="01"/>
<dmTitle>
<techName>s1kd-appcheck</techName>
<infoName>Description</infoName>
</dmTitle>
</dmAddressItems>
</dmAddress>
<dmStatus issueType="changed">
<security securityClassification="01"/>
<responsiblePartnerCompany>
<enterpriseName>khzae.net</enterpriseName>
</responsiblePartnerCompany>
<originator>
<enterpriseName>khzae.net</enterpriseName>
</originator>
<applic>
<displayText>
<simplePara>All</simplePara>
</displayText>
</applic>
<brexDmRef>
<dmRef>
<dmRefIdent>
<dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
</dmRefIdent>
</dmRef>
</brexDmRef>
<qualityAssurance>
<unverified/>
</qualityAssurance>
<reasonForUpdate id="rfu-xml-catalog" updateHighlight="1" updateReasonType="urt02">
<simplePara>Add --xml-catalog parser option.</simplePara>
</reasonForUpdate>
<reasonForUpdate id="rfu-0001" updateHighlight="1" updateReasonType="urt02">
<simplePara>Add -D (--duplicate) option.</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
<content>
<description>
<levelledPara>
<title>General</title>
<para>The <emphasis>s1kd-appcheck</emphasis> tool validates the applicability of S1000D CSDB objects, detecting potential errors that could occur when the object is filtered.</para>
<para>By default, the tool validates an object against only the product attribute and condition values which are explicitly used within the object. The products check (-t) and full check (-a) modes allow objects to be checked for issues with implicit applicability, that is, product attribute or condition values which are not explicitly used within an object, but may still affect it.</para>
<para>The s1kd-instance and s1kd-validate tools are used by default to perform the actual validation.</para>
</levelledPara>
<levelledPara>
<title>Usage</title>
<para>
<verbatimText verbatimStyle="vs24">s1kd-appcheck [options] [<object>...]</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Options</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>-A, --act <file></listItemTerm>
<listItemDefinition>
<para>Specify the ACT to read product attributes from, and to use to find the CCT or PCT. This will override the ACT reference within the individual objects being validated.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-a, --all</listItemTerm>
<listItemDefinition>
<para>Validate objects against all possible combinations of relevant product attribute and condition values as defined in the ACT and CCT. Relevant product attributes and conditions are those that are used by an object with any value.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-b, --brexcheck</listItemTerm>
<listItemDefinition>
<para>Validate objects with a BREX check (using the s1kd-brexcheck tool) in addition to the schema check.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-C, --cct <file></listItemTerm>
<listItemDefinition>
<para>Specify the CCT to read conditions from. This will override the CCT reference within the ACT.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-c, --custom</listItemTerm>
<listItemDefinition>
<para>Perform a customized check. The default standalone applicability check is disabled. This can then be combined with the -s option, to only check that all product attributes and conditions are defined in the ACT and CCT respectively, and/or the -n option, to only check nested applicability annotations. If neither of these options are specified, no checks will be performed.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<listItemTerm>-D, --duplicate</listItemTerm>
<listItemDefinition>
<para>Check for duplicate annotations.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-d, --dir <dir></listItemTerm>
<listItemDefinition>
<para>The directory to start searching for ACT/CCT/PCT data modules in. By default, the current directory is used.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-e, --exec <cmd></listItemTerm>
<listItemDefinition>
<para>The commands used to validate objects. Multiple commands can be used by specifying this option multiple times. The objects will be passed to each command on stdin, and the exit status of the command will be used to determine if the object is valid (with a non-zero exit status indicating it is invalid). This overrides the default commands (s1kd-validate, and s1kd-brexcheck if -b is specified).</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-F, --valid-filenames</listItemTerm>
<listItemDefinition>
<para>Print the filenames of valid objects.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-f, --filenames</listItemTerm>
<listItemDefinition>
<para>Print the filenames of invalid objects.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-h, -?, --help</listItemTerm>
<listItemDefinition>
<para>Show help/usage message.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-K, --filter <cmd></listItemTerm>
<listItemDefinition>
<para>The command used to filter objects prior to validation. The objects will be passed to the command on stdin, and the filters will be supplied as arguments in the form of "<verbatimText>-s <ident>:<type>=<value></verbatimText>". This overrides the default command (s1kd-instance).</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-k, --args <args></listItemTerm>
<listItemDefinition>
<para>The arguments to the filter command when filtering objects prior to validation.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-l, --list</listItemTerm>
<listItemDefinition>
<para>Treat input as a list of CSDB objects to validate.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-N, --omit-issue</listItemTerm>
<listItemDefinition>
<para>Assume that the issue/inwork numbers are omitted from object filenames (they were created with the -N option).</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-n, --nested</listItemTerm>
<listItemDefinition>
<para>Check that all product attribute and condition values used in nested applicability annotations are subsets of the values used in their parents.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-o, --output-valid</listItemTerm>
<listItemDefinition>
<para>Output valid CSDB objects to stdout.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-P, --pct <file></listItemTerm>
<listItemDefinition>
<para>Specify the PCT to read product instances from. This will override the PCT reference in the ACT.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-p, --progress</listItemTerm>
<listItemDefinition>
<para>Display a progress bar.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-q, --quiet</listItemTerm>
<listItemDefinition>
<para>Quiet mode. Error messages will not be printed.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-R, --redundant</listItemTerm>
<listItemDefinition>
<para>Check for redundant annotations.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-r, --recursive</listItemTerm>
<listItemDefinition>
<para>Search for the ACT/CCT/PCT recursively.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-s, --strict</listItemTerm>
<listItemDefinition>
<para>Check whether product attributes and conditions used by an object are declared in the ACT and CCT respectively.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-T, --summary</listItemTerm>
<listItemDefinition>
<para>Print a summary of the check after it completes, including statistics on the number of objects that passed/failed the check.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-t, --products</listItemTerm>
<listItemDefinition>
<para>Validate objects against the defined product instances within the PCT.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-v, --verbose</listItemTerm>
<listItemDefinition>
<para>Verbose output. Specify multiple times to increase the verbosity.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-x, --xml</listItemTerm>
<listItemDefinition>
<para>Print an XML report of the check.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-~, --dependencies</listItemTerm>
<listItemDefinition>
<para>Check with CCT dependency tests added to assertions which use the dependant values.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-^, --remove-deleted</listItemTerm>
<listItemDefinition>
<para>Validate objects with elements that have a change type of "delete" removed.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>--version</listItemTerm>
<listItemDefinition>
<para>Show version information.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm><object>...</listItemTerm>
<listItemDefinition>
<para>Object(s) to validate.</para>
</listItemDefinition>
</definitionListItem>
</definitionList>
</para>
<para>
In addition, the following options allow configuration of the XML parser:
<definitionList><definitionListItem><listItemTerm>--dtdload</listItemTerm><listItemDefinition><para>Load the external DTD.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--huge</listItemTerm><listItemDefinition><para>Remove any internal arbitrary parser limits.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--net</listItemTerm><listItemDefinition><para>Allow network access to load external DTD and entities.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--noent</listItemTerm><listItemDefinition><para>Resolve entities.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--parser-errors</listItemTerm><listItemDefinition><para>Emit errors from parser.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--parser-warnings</listItemTerm><listItemDefinition><para>Emit warnings from parser.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--xinclude</listItemTerm><listItemDefinition><para>Do XInclude processing.</para></listItemDefinition></definitionListItem><definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-xml-catalog"><listItemTerm>--xml-catalog <file></listItemTerm><listItemDefinition><para>Use an XML catalog when resolving entities. Multiple catalogs may be loaded by specifying this option multiple times.</para></listItemDefinition></definitionListItem></definitionList>
</para>
</levelledPara>
<levelledPara>
<title>Exit status</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>0</listItemTerm>
<listItemDefinition>
<para>The check completed successfully, and all CSDB objects were valid.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>1</listItemTerm>
<listItemDefinition>
<para>The check completed successfully, but some CSDB objects were invalid.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>2</listItemTerm>
<listItemDefinition>
<para>One or more CSDB objects could not be read.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>3</listItemTerm>
<listItemDefinition>
<para>The number of CSDB objects specified exceeded the available memory.</para>
</listItemDefinition>
</definitionListItem>
</definitionList>
</para>
</levelledPara>
<levelledPara>
<title>Examples</title>
<levelledPara>
<title>Standalone validation</title>
<para>Consider the following data module snippet:</para>
<para>
<verbatimText verbatimStyle="vs11"><dmodule>
...
<applic>
<displayText>
<simplePara>Version: A or Version: B</simplePara>
</displayText>
<evaluate andOr="or">
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="A"/>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="B"/>
</evaluate>
</applic>
...
<referencedApplicGroup>
<applic id="app-VersionB">
<assert applicPropertyIdent="version" applicPropertyType="prodattr"
applicPropertyValues="B"/>
</applic>
</referencedApplicGroup>
...
<levelledPara id="par-0001" applicRefId="app-VersionB">
<title>Features of version B</title>
<para>...</para>
</levelledPara>
...
<levelledPara>
<title>More information</title>
<para>...</para>
<para>Refer to <internalRef internalRefId="par-0001"/>.</para>
</levelledPara>
...
</dmodule></verbatimText>
</para>
<para>There are two versions of the product, A and B, and the data module is meant to apply to both.</para>
<para>By itself, the data module is valid:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-validate -v <DM>
s1kd-validate: SUCCESS: <DM> validates against schema <url></verbatimText>
</para>
<para>Checking it with this tool, however, reveals an issue: </para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck <DM>
s1kd-appcheck: ERROR: <DM> is invalid when:
s1kd-appcheck: ERROR: prodattr version = A</verbatimText>
</para>
<para>When the data module is filtered for version A, the first levelled paragraph will be removed, which causes the reference to it in the second levelled paragraph to become broken.</para>
</levelledPara>
<levelledPara>
<title>Full validation</title>
<para>Consider the following data module snippet:</para>
<para>
<verbatimText verbatimStyle="vs11"><dmodule>
...
<applic>
<displayText>
<simplePara>All</simplePara>
</displayText>
</applic>
...
<referencedApplicGroup>
<applic id="app-IcyOrHot">
<evaluate andOr="or">
<assert
applicPropertyIdent="weather"
applicPropertyType="condition"
applicPropertyValues="Icy"/>
<assert
applicPropertyIdent="weather"
applicPropertyType="condition"
applicPropertyValues="Hot"/>
</applic>
</referencedApplicGroup>
...
<proceduralStep>
<para>Locate the handle.</para>
</proceduralStep>
<proceduralStep id="stp-0001" applicRefId="app-IcyOrHot">
<para>Put on gloves prior to touching the handle.</para>
</proceduralStep>
<proceduralStep>
<para>Grab the handle and turn it clockwise.</para>
</proceduralStep>
...
<proceduralStep>
<para>Remove the gloves you put on in <internalRef internalRefId="stp-0001"/>.</para>
</proceduralStep>
...
</dmodule></verbatimText>
</para>
<para>Once again, this data module is valid by itself:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-validate -v <DM>
s1kd-validate: SUCCESS: <DM> validates against schema <url></verbatimText>
</para>
<para>This time, however, it also initially appears valid when this tool is used:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -v <DM>
s1kd-appcheck: SUCCESS: <DM> passed the applicability check.</verbatimText>
</para>
<para>However, now consider this snippet from the CCT:</para>
<para>
<verbatimText verbatimStyle="vs11"><condCrossRefTable>
...
<condType id="weatherType">
<name>Weather type</name>
<descr>Possible types of weather conditions.</descr>
<enumeration applicPropertyValues="Normal"/>
<enumeration applicPropertyValues="Icy"/>
<enumeration applicPropertyValues="Hot"/>
</condType>
...
<cond id="weather" condTypeRefId="weatherType">
<name>Weather</name>
<descr>The current weather conditions.</descr>
</cond>
...
</condCrossRefTable></verbatimText>
</para>
<para>There is a third value for the <verbatimText verbatimStyle="vs14">weather</verbatimText> condition which is not explicitly used within the data module, and therefore will not be validated against in the default standalone check. When <verbatimText verbatimStyle="vs14">weather</verbatimText> has a value of <verbatimText verbatimStyle="vs14">Normal</verbatimText>, the cross-reference in the last step in the example above becomes broken.</para>
<para>To catch errors with implicit applicability, the full check (-a) can be used instead, which reads the values to check not from the data module itself, but from the ACT and CCT referenced by the data module:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -a <DM>
s1kd-appcheck: ERROR: <DM> is invalid when:
s1kd-appcheck: ERROR: condition weather = Normal</verbatimText>
</para>
<para>This can also be fixed by making the applicability of the data module explicit:</para>
<para>
<verbatimText verbatimStyle="vs11"><applic>
<displayText>
<simplePara>Weather: Normal or Weather: Icy or
Weather: Hot</simplePara>
</displayText>
<evaluate andOr="or">
<assert
applicPropertyIdent="weather"
applicPropertyType="condition"
applicPropertyValues="Normal"/>
<assert
applicPropertyIdent="weather"
applicPropertyType="condition"
applicPropertyValues="Icy"/>
<assert
applicPropertyIdent="weather"
applicPropertyType="condition"
applicPropertyValues="Hot"/>
</evaluate>
</applic></verbatimText>
</para>
<para>In which case, the standalone check will now also detect the error:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck <DM>
s1kd-appcheck: ERROR: <DM> is invalid when:
s1kd-appcheck: ERROR: condition weather = Normal</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Nested applicability annotations</title>
<para>Consider the following data module snippet:</para>
<para>
<verbatimText verbatimStyle="vs11"><dmodule>
...
<applic>
<displayText>
<simplePara>Version: A, B</simplePara>
</displayText>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="A"/>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="B"/>
</applic>
...
<referencedApplicGroup>
<applic id="app-C">
<displayText>
<simplePara>Version: C</simplePara>
</displayText>
<assert
applicPropertyIdent="version"
applicPropertyType="prodattr"
applicPropertyValues="C"/>
</applic>
</referencedApplicGroup>
...
<proceduralStep>
<para>Step A</para>
</proceduralStep>
<proceduralStep applicRefId="app-C">
<para>Step B</para>
</proceduralStep>
<proceduralStep>
<para>Step C</para>
</proceduralStep>
...
</dmodule></verbatimText>
</para>
<para>Here, the whole data module is applicable to versions A and B, but an individual step has been made applicable to version C. Normally, this is not reported as an error, since the removal of this step would not cause the data module to become invalid:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -v <DM>
s1kd-appcheck: SUCCESS: <DM> passed the applicability check</verbatimText>
</para>
<para>However, the content is essentially useless, since it will never appear. The -n option will report when the applicability of an element is incompatible with the applicability of any parent elements or the whole object:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -n <DM>
s1kd-appcheck: ERROR: <DM>: proceduralStep on line 62 is applicable
when prodattr version = C, which is not a subset of the applicability
of the whole object.</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Redundant applicability annotations</title>
<para>
Consider the following data module snippet:
<verbatimText verbatimStyle="vs11"><proceduralStep applicRefId="app-A">
<para>Step A</para>
<figure applicRefId="app-A">
...
</figure>
</proceduralStep></verbatimText>
</para>
<para>This is technically correct, but the annotation on the figure can be considered redundant, since it has the same applicability as its ancestor, and the applicability of an element is already inherited by all its descendants automatically.</para>
<para>
The -R (--redundant) option will report when the applicability of a nested element is redundant:
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -R <DM>
s1kd-appcheck: ERROR: <DM>: figure on line 85 has the same
applicability as its parent proceduralStep on line 83 (app-A)</verbatimText>
</para>
<note>
<notePara>Currently, this check only detects when the exact same annotation (with the same ID) is nested within itself. In the future, this should also detect redundant logic between different nested annotations.</notePara>
</note>
</levelledPara>
<levelledPara changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<title>Duplicate applicability annotations</title>
<para>
Consider the following data module snippet:
<verbatimText verbatimStyle="vs11"><referencedApplicGroup>
<applic id="app-0001">
<assert applicPropertyIdent="version" applicPropertyType="prodattr" applicPropertyValues="A"/>
</applic>
<applic id="app-0002">
<assert applicPropertyIdent="version" applicPropertyType="prodattr" applicPropertyValues="A"/>
</referencedApplicGroup></verbatimText>
</para>
<para>
These annotations have duplicate logic, meaning only one is necessary. The -D (--duplicate) option will report when an applicability annotation is a duplicate of another annotation:
<verbatimText verbatimStyle="vs24">$ s1kd-appcheck -D <DM>
s1kd-appcheck: ERROR: <DM>: Annotation on line 47 is a duplicate of annotation on line 24.</verbatimText>
</para>
</levelledPara>
</levelledPara>
</description>
</content>
</dmodule>
gopher://khzae.net/0/s1kd/s1kd-tools/sample/csdb/DMC-S1KDTOOLS-A-11-00-00-00A-040A-D_EN-CA.XML