.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-repcheck" "1" "2024-03-21" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-repcheck - Validate CIR references in S1000D CSDB objects
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-repcheck [options] [<objects>...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-repcheck\f[R] tool validates references to Common
Information Repository (CIR) 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.
.SH OPTIONS
.TP
-A, --all-refs
Validate indirect tool/supply/part CIR references using the element
\f[C]<identNumber>\f[R].
Normally, only the direct reference elements \f[C]<toolRef>\f[R],
\f[C]<supplyRef>\f[R] and \f[C]<partRef>\f[R] are validated.
.TP
-a, --all
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.
.TP
-D, --dump-xsl
Dump the built-in XSLT used to extract CIR references.
.TP
-d, --dir <dir>
The directory to start searching for CIR data modules in.
By default, the current directory is used.
.TP
-F, --valid-filenames
Print the filenames of valid objects.
.TP
-f, --filenames
Print the filenames of invalid objects.
.TP
-h, -?, --help
Show help/usage message.
.TP
-L, --list-refs
List CIR references found in objects instead of validating them.
.TP
-l, --list
Treat input as a list of CSDB objects to check.
.TP
-N, --omit-issue
Assume that the issue/inwork numbers are omitted from object filenames
(they were created with the -N option).
.TP
-o, --output-valid
Output valid CSDB objects to stdout.
.TP
-p, --progress
Display a progress bar.
.TP
-q, --quiet
Quiet mode.
Error messages will not be printed.
.TP
-R, --cir <CIR>
A CIR to resolve references in CSDB objects against.
Multiple CIRs can be specified by using this option multiple times.
.RS
.PP
If \[dq]*\[dq] is given for <CIR>, the tool will search for CIR data
modules automatically.
.RE
.TP
-r, --recursive
Search for CIR data modules recursively.
.TP
-T, --summary
Print a summary of the check after it completes, including statistics on
the number of objects that passed/failed the check.
.TP
-t, --type <type>
Validate or list only CIR references of the specified type.
The built-in types are:
.RS
.IP \[bu] 2
acp (Access point)
.IP \[bu] 2
app (Applicability annotation)
.IP \[bu] 2
caut (Caution)
.IP \[bu] 2
cbr (Circuit breaker)
.IP \[bu] 2
cin (Control/Indicator)
.IP \[bu] 2
ent (Enterprise)
.IP \[bu] 2
fin (Functional item)
.IP \[bu] 2
part
.IP \[bu] 2
supply
.IP \[bu] 2
tool
.IP \[bu] 2
warn (Warning)
.IP \[bu] 2
zone
.RE
.TP
-v, --verbose
Verbose output.
Specify multiple times to increase the verbosity.
.TP
-X, --xsl <file>
Use custom XSLT to extract CIR references.
.TP
-x, --xml
Print an XML report of the check.
.TP
-\[ha], --remove-deleted
Validate with elements that have a change type of \[dq]delete\[dq]
removed.
CIR data modules with an issue type of \[dq]deleted\[dq] will also be
ignored in the automatic search when this option is specified.
.TP
--version
Show version information.
.TP
--zenity-progress
Print progress information in the zenity --progress format.
.TP
<object>...
Object(s) to check CIR references in.
.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 Custom XSLT (-X)
.PP
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.
.PP
The custom XSLT script should add the following attributes to elements
which will be validated as CIR references:
.TP
\f[B]\f[CB]type\f[B]\f[R]
A name for the type of CIR reference.
.TP
\f[B]\f[CB]name\f[B]\f[R]
A descriptive name for the CIR reference that can be used in reports.
.TP
\f[B]\f[CB]test\f[B]\f[R]
An XPath expression used to match the corresponding CIR identification
element.
.PP
The namespace for these attributes must be:
\f[C]urn:s1kd-tools:s1kd-repcheck\f[R]
.PP
Example XSLT template to extract functional item references:
.IP
.nf
\f[C]
<xsl:template match=\[dq]functionalItemRef\[dq]>
<xsl:variable name=\[dq]fin\[dq] select=\[dq]\[at]functionalItemNumber\[dq]/>
<xsl:copy>
<xsl:apply-templates select=\[dq]\[at]*\[dq]/>
<xsl:attribute name=\[dq]s1kd-repcheck:type\[dq]>fin</xsl:attribute>
<xsl:attribute name=\[dq]s1kd-repcheck:name\[dq]>
<xsl:text>Functional item </xsl:text>
<xsl:value-of select=\[dq]$fin\[dq]/>
</xsl:attribute>
<xsl:attribute name=\[dq]s1kd-repcheck:test\[dq]>
<xsl:text>//functionalItemIdent[\[at]functionalItemNumber=\[aq]</xsl:text>
<xsl:value-of select=\[dq]$fin\[dq]/>
<xsl:text>\[aq]]</xsl:text>
</xsl:attribute>
<xsl:apply-templates select=\[dq]node()\[dq]/>
</xsl:copy>
</xsl:template>
\f[R]
.fi
.PP
A custom script also allows validating non-standard types of
\[dq]CIR\[dq] 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:
.IP
.nf
\f[C]
<xsl:template match=\[dq]acronym\[dq]>
<xsl:variable name=\[dq]term\[dq] select=\[dq]acronymTerm\[dq]/>
<xsl:copy>
<xsl:apply-templates select=\[dq]\[at]*\[dq]/>
<xsl:attribute name=\[dq]s1kd-repcheck:type\[dq]>acr</xsl:attribute>
<xsl:attribute name=\[dq]s1kd-repcheck:name\[dq]>
<xsl:text>Acronym </xsl:text>
<xsl:value-of select=\[dq]$term\[dq]/>
</xsl:attribute>
<xsl:attribute name=\[dq]s1kd-repcheck:test\[dq]>
<xsl:text>//acronym[acronymTerm = \[aq]</xsl:text>
<xsl:value-of select=\[dq]$term\[dq]/>
<xsl:text>\[aq]]</xsl:text>
</xsl:attribute>
<xsl:apply-templates select=\[dq]node()\[dq]/>
</xsl:copy>
</xsl:template>
\f[R]
.fi
.PP
As there is no standard \[dq]acronym\[dq] CIR type, the object
containing the repository would need to be specified explicitly with -R.
.PP
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.
.SH EXIT STATUS
.TP
0
The check completed successfully, and all CIR references were resolved.
.TP
1
The check completed successfully, but some CIR references could not be
resolved.
.TP
2
The number of CSDB objects specified exceeded the available memory.
.SH EXAMPLE
.PP
Part repository:
.IP
.nf
\f[C]
<partRepository>
<partSpec>
<partIdent manufacturerCodeValue=\[dq]12345\[dq] partNumberValue=\[dq]ABC\[dq]/>
<itemIdentData>
<descrForPart>ABC part</descrForPart>
</itemIdentData>
</partSpec>
</partRepository>
\f[R]
.fi
.PP
Part references in a procedure:
.IP
.nf
\f[C]
<spareDescrGroup>
<spareDescr>
<partRef manufacturerCodeValue=\[dq]12345\[dq] partNumberValue=\[dq]ABC\[dq]/>
<reqQuantity>1</reqQuantity>
</spareDescr>
<spareDescr>
<partRef manufacturerCodeValue=\[dq]12345\[dq] partNumberValue=\[dq]DEF\[dq]/>
<reqQuantity>1</reqQuantity>
</spareDescr>
</spareDescrGroup>
\f[R]
.fi
.PP
Command and results:
.IP
.nf
\f[C]
$ s1kd-repcheck -R <CIR> ... <DM>
s1kd-repcheck: ERROR: <DM> (<line>): Part 12345/DEF not found.
\f[R]
.fi
.SH AUTHORS
khzae.net.