<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dmodule>
<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="02" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
        <language languageIsoCode="en" countryIsoCode="CA"/>
        <issueInfo issueNumber="027" inWork="00"/>
      </dmIdent>
      <dmAddressItems>
        <issueDate year="2021" month="04" day="16"/>
        <dmTitle>
          <techName>s1kd-validate(1) | s1kd-tools</techName>
        </dmTitle>
      </dmAddressItems>
    </dmAddress>
    <dmStatus issueType="status">
      <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="S1000D" systemDiffCode="G" systemCode="04" subSystemCode="1" subSubSystemCode="0" assyCode="0301" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
          </dmRefIdent>
        </dmRef>
      </brexDmRef>
      <qualityAssurance>
        <unverified/>
      </qualityAssurance>
      <reasonForUpdate>
        <simplePara>Upissued</simplePara>
      </reasonForUpdate>
    </dmStatus>
  </identAndStatusSection>
  <content>
    <description>
      <levelledPara>
        <title>NAME</title>
        <para>s1kd-validate - Validate S1000D CSDB objects against their schemas</para>
      </levelledPara>
      <levelledPara>
        <title>SYNOPSIS</title>
        <para>
          <verbatimText verbatimStyle="vs24"><![CDATA[s1kd-validate [-s <path>] [-x <URI>] [-F|-f] [-eloqv^h?]
              [<object>...]]]></verbatimText>
        </para>
      </levelledPara>
      <levelledPara>
        <title>DESCRIPTION</title>
        <para>The <emphasis>s1kd-validate</emphasis> tool validates S1000D CSDB objects, checking whether they are valid XML files and if they are valid against their own S1000D schemas.</para>
      </levelledPara>
      <levelledPara>
        <title>OPTIONS</title>
        <para>
          <definitionList>
            <definitionListItem>
              <listItemTerm>-e, --ignore-empty</listItemTerm>
              <listItemDefinition>
                <para>Ignore validation for empty or non-XML documents.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-F, --valid-filenames</listItemTerm>
              <listItemDefinition>
                <para>List valid files.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-f, --filenames</listItemTerm>
              <listItemDefinition>
                <para>List invalid files.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-h, -?, --help</listItemTerm>
              <listItemDefinition>
                <para>Show help/usage message.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-l, --list</listItemTerm>
              <listItemDefinition>
                <para>Treat input as a list of object names to validate, rather than an object itself.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-o, --output-valid</listItemTerm>
              <listItemDefinition>
                <para>Output valid CSDB objects to stdout.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-q, --quiet</listItemTerm>
              <listItemDefinition>
                <para>Quiet mode. The tool will not output anything to stdout or stderr. Success/failure will only be indicated through the exit status.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-s, --schema <path></listItemTerm>
              <listItemDefinition>
                <para>Validate the objects against the specified schema, rather than the one that they reference.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-v, --verbose</listItemTerm>
              <listItemDefinition>
                <para>Verbose mode. Success/failure will be explicitly reported on top of any errors.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-x, --exclude <URI></listItemTerm>
              <listItemDefinition>
                <para>Exclude an XML namespace from the validation. Elements in the namespace specified by <URI> are ignored.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-^, --remove-deleted</listItemTerm>
              <listItemDefinition>
                <para>Validate 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>Any number of CSDB objects to validate. If none are specified, input is read from stdin.</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>
              <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>
          <title>XML catalogs</title>
          <para>XML catalogs allow redirecting the canonical URIs of XML schemas and other external resources to local files, so as to avoid the unnecessary overhead of downloading those static resources over the Internet.</para>
          <para>Below is an example of a catalog file which maps the S1000D schemas to a local directory:</para>
          <para>
            <verbatimText verbatimStyle="vs11"><catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI
uriStartString="http://www.s1000d.org"
rewritePrefix="/usr/share/s1kd/schemas"/>
</catalog></verbatimText>
          </para>
          <para>This can be placed in a catalog file automatically loaded by libxml2 (e.g., <verbatimText verbatimStyle="vs02">/etc/xml/catalog</verbatimText>) or saved to a file which is then specified in an environment variable used by libxml2 (e.g., <verbatimText>XML_CATALOG_FILES</verbatimText>):</para>
          <para>
            <verbatimText verbatimStyle="vs24">$ XML_CATALOG_FILES=catalog.xml s1kd-validate <DMs...></verbatimText>
          </para>
          <para>
            Alternatively, the --xml-catalog option may be used:
            <verbatimText verbatimStyle="vs24">$ s1kd-validate --xml-catalog=catalog.xml <DMs>...</verbatimText>
          </para>
        </levelledPara>
      </levelledPara>
      <levelledPara>
        <title>EXIT STATUS</title>
        <para>
          <definitionList>
            <definitionListItem>
              <listItemTerm>0</listItemTerm>
              <listItemDefinition>
                <para>No errors.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>1</listItemTerm>
              <listItemDefinition>
                <para>Some CSDB objects are not well-formed or valid.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>2</listItemTerm>
              <listItemDefinition>
                <para>The number of schemas cached exceeded the available memory.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>3</listItemTerm>
              <listItemDefinition>
                <para>A specified schema could not be read.</para>
              </listItemDefinition>
            </definitionListItem>
          </definitionList>
        </para>
      </levelledPara>
      <levelledPara>
        <title>EXAMPLE</title>
        <para>
          <verbatimText verbatimStyle="vs24">$ s1kd-validate DMC-EX-A-00-00-00-00A-040A-D_000-01_EN-CA.XML</verbatimText>
        </para>
      </levelledPara>
    </description>
  </content>
</dmodule>