..
/
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="18" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
<language languageIsoCode="en" countryIsoCode="CA"/>
<issueInfo issueNumber="007" inWork="00"/>
</dmIdent>
<dmAddressItems>
<issueDate year="2020" month="09" day="01"/>
<dmTitle>
<techName>s1kd-repcheck</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 (--dump-xsl), -t (--type) and -X (--xsl) options.</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
<content>
<description>
<levelledPara>
<title>General</title>
<para>The <emphasis>s1kd-repcheck</emphasis> tool validates references to <acronym><acronymTerm>CIR</acronymTerm><acronymDefinition>Common Information Repository</acronymDefinition></acronym> items within S1000D CSDB objects. Any CIR references which cannot be resolved to a specification within a CIR data module will cause the tool to report an error.</para>
</levelledPara>
<levelledPara>
<title>Usage</title>
<para>
<verbatimText verbatimStyle="vs24">s1kd-repcheck [options] [<objects>...]</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Options</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>-A, --all-refs</listItemTerm>
<listItemDefinition>
<para>Validate indirect tool/supply/part CIR references using the element <verbatimText verbatimStyle="vs12"><identNumber></verbatimText>. Normally, only the direct reference elements <verbatimText verbatimStyle="vs12"><toolRef></verbatimText>, <verbatimText verbatimStyle="vs12"><supplyRef></verbatimText> and <verbatimText verbatimStyle="vs12"><partRef></verbatimText> are validated.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-a, --all</listItemTerm>
<listItemDefinition>
<para>In addition to CIR data modules specified with -R or explicitly linked in CIR references, allow CIR references to be resolved against any CIR data modules that were specified as objects to check.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<listItemTerm>-D, --dump-xsl</listItemTerm>
<listItemDefinition>
<para>Dump the built-in XSLT used to extract CIR references.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-d, --dir <dir></listItemTerm>
<listItemDefinition>
<para>The directory to start searching for CIR data modules in. By default, the current directory is used.</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>-L, --list-refs</listItemTerm>
<listItemDefinition>
<para>List CIR references found in objects instead of validating them.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-l, --list</listItemTerm>
<listItemDefinition>
<para>Treat input as a list of CSDB objects to check.</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>-o, --output-valid</listItemTerm>
<listItemDefinition>
<para>Output valid CSDB objects to stdout.</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, --cir <CIR></listItemTerm>
<listItemDefinition>
<para>A CIR to resolve references in CSDB objects against. Multiple CIRs can be specified by using this option multiple times.</para>
<para>If "*" is given for <CIR>, the tool will search for CIR data modules automatically.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-r, --recursive</listItemTerm>
<listItemDefinition>
<para>Search for CIR data modules recursively.</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 changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<listItemTerm>-t, --type <type></listItemTerm>
<listItemDefinition>
<para>
Validate or list only CIR references of the specified type. The built-in types are:
<randomList><listItem><para>acp (Access point)</para></listItem><listItem><para>app (Applicability annotation)</para></listItem><listItem><para>caut (Caution)</para></listItem><listItem><para>cbr (Circuit breaker)</para></listItem><listItem><para>cin (Control/Indicator)</para></listItem><listItem><para>ent (Enterprise)</para></listItem><listItem><para>fin (Functional item)</para></listItem><listItem><para>part</para></listItem><listItem><para>supply</para></listItem><listItem><para>tool</para></listItem><listItem><para>warn (Warning)</para></listItem><listItem><para>zone</para></listItem></randomList>
</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-v, --verbose</listItemTerm>
<listItemDefinition>
<para>Verbose output. Specify multiple times to increase the verbosity.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<listItemTerm>-X, --xsl <file></listItemTerm>
<listItemDefinition>
<para>Use custom XSLT to extract CIR references.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-x, --xml</listItemTerm>
<listItemDefinition>
<para>Print an XML report of the check.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-^, --remove-deleted</listItemTerm>
<listItemDefinition>
<para>Validate with elements that have a change type of "delete" removed. CIR data modules with an issue type of "deleted" will also be ignored in the automatic search when this option is specified.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>--version</listItemTerm>
<listItemDefinition>
<para>Show version information.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm><object>...</listItemTerm>
<listItemDefinition>
<para>Object(s) to check CIR references in.</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 changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-0001">
<title>Custom XSLT (-X)</title>
<para>What elements are extracted as CIR references for validating, and how they are validated, can be configured through a custom XSLT script specified with the -X (--xsl) option.</para>
<para>
The custom XSLT script should add the following attributes to elements which will be validated as CIR references:
<definitionList><definitionListItem><listItemTerm><verbatimText verbatimStyle="vs13">type</verbatimText></listItemTerm><listItemDefinition><para>A name for the type of CIR reference.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm><verbatimText verbatimStyle="vs13">name</verbatimText></listItemTerm><listItemDefinition><para>A descriptive name for the CIR reference that can be used in reports.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm><verbatimText verbatimStyle="vs13">test</verbatimText></listItemTerm><listItemDefinition><para>An XPath expression used to match the corresponding CIR identification element.</para></listItemDefinition></definitionListItem></definitionList>
The namespace for these attributes must be: <verbatimText>urn:s1kd-tools:s1kd-repcheck</verbatimText>
</para>
<para>
Example XSLT template to extract functional item references:
<verbatimText verbatimStyle="vs11"><xsl:template match="functionalItemRef">
<xsl:variable name="fin" select="@functionalItemNumber"/>
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsl:attribute name="s1kd-repcheck:type">fin</xsl:attribute>
<xsl:attribute name="s1kd-repcheck:name">
<xsl:text>Functional item </xsl:text>
<xsl:value-of select="$fin"/>
</xsl:attribute>
<xsl:attribute name="s1kd-repcheck:test">
<xsl:text>//functionalItemIdent[@functionalItemNumber='</xsl:text>
<xsl:value-of select="$fin"/>
<xsl:text>']</xsl:text>
</xsl:attribute>
<xsl:apply-templates select="node()"/>
</xsl:copy>
</xsl:template></verbatimText>
</para>
<para>
A custom script also allows validating non-standard types of "CIR" references.
For example, if a project wants to validate acronyms used in data modules against a central repository of acronyms, this could be done like so:
<verbatimText verbatimStyle="vs11"><xsl:template match="acronym">
<xsl:variable name="term" select="acronymTerm"/>
<xsl:copy>
<xsl:apply-templates select="@*"/>
<xsl:attribute name="s1kd-repcheck:type">acr</xsl:attribute>
<xsl:attribute name="s1kd-repcheck:name">
<xsl:text>Acronym </xsl:text>
<xsl:value-of select="$term"/>
</xsl:attribute>
<xsl:attribute name="s1kd-repcheck:test">
<xsl:text>//acronym[acronymTerm = '</xsl:text>
<xsl:value-of select="$term"/>
<xsl:text>']</xsl:text>
</xsl:attribute>
<xsl:apply-templates select="node()"/>
</xsl:copy>
</xsl:template></verbatimText>
As there is no standard "acronym" CIR type, the object containing the repository would need to be specified explicitly with -R.
</para>
<para>The built-in XSLT for extracting CIR references can be dumped as a starting point for a custom script by specifying the -D (--dump-xsl) option.</para>
</levelledPara>
</levelledPara>
<levelledPara>
<title>Exit status</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>0</listItemTerm>
<listItemDefinition>
<para>The check completed successfully, and all CIR references were resolved.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>1</listItemTerm>
<listItemDefinition>
<para>The check completed successfully, but some CIR references could not be resolved.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>2</listItemTerm>
<listItemDefinition>
<para>The number of CSDB objects specified exceeded the available memory.</para>
</listItemDefinition>
</definitionListItem>
</definitionList>
</para>
</levelledPara>
<levelledPara>
<title>Example</title>
<para>
Part repository:
<verbatimText verbatimStyle="vs11"><partRepository>
<partSpec>
<partIdent manufacturerCodeValue="12345" partNumberValue="ABC"/>
<itemIdentData>
<descrForPart>ABC part</descrForPart>
</itemIdentData>
</partSpec>
</partRepository></verbatimText>
Part references in a procedure:
<verbatimText verbatimStyle="vs11"><spareDescrGroup>
<spareDescr>
<partRef manufacturerCodeValue="12345" partNumberValue="ABC"/>
<reqQuantity>1</reqQuantity>
</spareDescr>
<spareDescr>
<partRef manufacturerCodeValue="12345" partNumberValue="DEF"/>
<reqQuantity>1</reqQuantity>
</spareDescr>
</spareDescrGroup></verbatimText>
Command and results:
<verbatimText verbatimStyle="vs24">$ s1kd-repcheck -R <CIR> ... <DM>
s1kd-repcheck: ERROR: <DM> (<line>): Part 12345/DEF not found.</verbatimText>
</para>
</levelledPara>
</description>
</content>
</dmodule>
gopher://khzae.net/0/s1kd/s1kd-tools/sample/csdb/DMC-S1KDTOOLS-A-18-00-00-00A-040A-D_EN-CA.XML