s1kd-repcheck(1)                  s1kd-tools                  s1kd-repcheck(1)

NAME
       s1kd-repcheck - Validate CIR references in S1000D CSDB objects

SYNOPSIS
              s1kd-repcheck [options] [<objects>...]

DESCRIPTION
       The  s1kd-repcheck  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.

OPTIONS
       -A, --all-refs
              Validate indirect tool/supply/part CIR references using the ele‐
              ment  <identNumber>.   Normally,  only the direct reference ele‐
              ments <toolRef>, <supplyRef> and <partRef> are validated.

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

       -D, --dump-xsl
              Dump the built-in XSLT used to extract CIR references.

       -d, --dir <dir>
              The  directory  to  start searching for CIR data modules in.  By
              default, the current directory is used.

       -F, --valid-filenames
              Print the filenames of valid objects.

       -f, --filenames
              Print the filenames of invalid objects.

       -h, -?, --help
              Show help/usage message.

       -L, --list-refs
              List CIR references found in objects instead of validating them.

       -l, --list
              Treat input as a list of CSDB objects to check.

       -N, --omit-issue
              Assume that the issue/inwork numbers  are  omitted  from  object
              filenames (they were created with the -N option).

       -o, --output-valid
              Output valid CSDB objects to stdout.

       -p, --progress
              Display a progress bar.

       -q, --quiet
              Quiet mode.  Error messages will not be printed.

       -R, --cir <CIR>
              A  CIR  to resolve references in CSDB objects against.  Multiple
              CIRs can be specified by using this option multiple times.

              If "*" is given for <CIR>, the tool will  search  for  CIR  data
              modules automatically.

       -r, --recursive
              Search for CIR data modules recursively.

       -T, --summary
              Print  a summary of the check after it completes, including sta‐
              tistics on the number of objects that passed/failed the check.

       -t, --type <type>
              Validate or list only CIR references of the specified type.  The
              built-in types are:

              · acp (Access point)

              · app (Applicability annotation)

              · caut (Caution)

              · cbr (Circuit breaker)

              · cin (Control/Indicator)

              · ent (Enterprise)

              · fin (Functional item)

              · part

              · supply

              · tool

              · warn (Warning)

              · zone

       -v, --verbose
              Verbose output.  Specify multiple times to increase the verbosi‐
              ty.

       -X, --xsl <file>
              Use custom XSLT to extract CIR references.

       -x, --xml
              Print an XML report of the check.

       -^, --remove-deleted
              Validate with elements that have a change type of  "delete"  re‐
              moved.   CIR  data  modules with an issue type of "deleted" will
              also be ignored in the automatic  search  when  this  option  is
              specified.

       --version
              Show version information.

       --zenity-progress
              Print progress information in the zenity --progress format.

       <object>...
              Object(s) to check CIR references in.

       In addition, the following options allow configuration of the XML pars‐
       er:

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

   Custom XSLT (-X)
       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.

       The  custom XSLT script should add the following attributes to elements
       which will be validated as CIR references:

       type   A name for the type of CIR reference.

       name   A descriptive name for the CIR reference that can be used in re‐
              ports.

       test   An  XPath expression used to match the corresponding CIR identi‐
              fication element.

       The  namespace  for  these  attributes  must  be:  urn:s1kd-tools:s1kd-
       repcheck

       Example XSLT template to extract functional item references:

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

       A custom script also allows validating non-standard types of "CIR" ref‐
       erences.  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:

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

       As there is no standard "acronym" CIR type, the object  containing  the
       repository would need to be specified explicitly with -R.

       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.

EXIT STATUS
       0      The  check  completed  successfully, and all CIR references were
              resolved.

       1      The check completed successfully, but some CIR references  could
              not be resolved.

       2      The number of CSDB objects specified exceeded the available mem‐
              ory.

EXAMPLE
       Part repository:

              <partRepository>
              <partSpec>
              <partIdent manufacturerCodeValue="12345" partNumberValue="ABC"/>
              <itemIdentData>
              <descrForPart>ABC part</descrForPart>
              </itemIdentData>
              </partSpec>
              </partRepository>

       Part references in a procedure:

              <spareDescrGroup>
              <spareDescr>
              <partRef manufacturerCodeValue="12345" partNumberValue="ABC"/>
              <reqQuantity>1</reqQuantity>
              </spareDescr>
              <spareDescr>
              <partRef manufacturerCodeValue="12345" partNumberValue="DEF"/>
              <reqQuantity>1</reqQuantity>
              </spareDescr>
              </spareDescrGroup>

       Command and results:

              $ s1kd-repcheck -R <CIR> ... <DM>
              s1kd-repcheck: ERROR: <DM> (<line>): Part 12345/DEF not found.

AUTHORS
       khzae.net.

                                  2024-03-21                  s1kd-repcheck(1)