<?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="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="018" infoCodeVariant="A" itemLocationCode="D"/>
        <language languageIsoCode="en" countryIsoCode="CA"/>
        <issueInfo issueNumber="024" inWork="00"/>
      </dmIdent>
      <dmAddressItems>
        <issueDate year="2020" month="05" day="01"/>
        <dmTitle>
          <techName>s1kd-tools</techName>
          <infoName>Introduction</infoName>
        </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="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>
        <simplePara>Upissue</simplePara>
      </reasonForUpdate>
    </dmStatus>
  </identAndStatusSection>
  <content>
    <description>
      <levelledPara>
        <title>General</title>
        <para>This document gives a basic overview of the relationship of the s1kd-tools to S1000D, and defines some common terms used throughout the s1kd-tools documentation.</para>
      </levelledPara>
      <levelledPara>
        <title>S1000D</title>
        <para><emphasis>S1000D</emphasis> is "an international specification for the procurement and production of technical publications", part of the S-Series of ILS specifications. The main focus of S1000D is the breakdown and classification of documents in to individual components, called "data modules", which can be re-used in multiple publications. These data modules are typically authored using a set of provided XML schemas, allowing them to be automatically managed in a <acronym acronymType="at01"><acronymTerm>CSDB</acronymTerm><acronymDefinition>Common Source Database</acronymDefinition></acronym> and validated against a defined set of project "business rules".</para>
      </levelledPara>
      <levelledPara>
        <title>s1kd-tools</title>
        <para>The <emphasis>s1kd-tools</emphasis> are a set of small tools for creating and manipulating S1000D data. They are designed to be used as a standalone method of maintaining a simple S1000D CSDB, in conjunction with a more typical version control system such as Git or SVN, as a backend to implement a more complex S1000D CSDB, or to support an existing S1000D CSDB already in use by a project.</para>
      </levelledPara>
      <levelledPara>
        <title>CSDB</title>
        <para>Common Source Databases can be implemented in any number of ways. For the purposes of the s1kd-tools, the CSDB is simply a directory within a filesystem. Use of the "File-based transfer" file naming conventions in Chap 7 of the S1000D specification are recommended, and most of the tools will use these conventions when creating or listing CSDB objects represented by files. In order to use these tools in conjuction with other implementations of CSDBs, a project can make use of "transfer packages" also described in Chap 7 to facilitate interchange between the two kinds of CSDB.</para>
      </levelledPara>
      <levelledPara>
        <title>Relationship to the S1000D process</title>
        <para>The s1kd-tools can support multiple parts of the basic S1000D process:</para>
        <para>
          <sequentialList>
            <listItem>
              <para><emphasis>Generation:</emphasis> The generation of new CSDB objects is supported by the <emphasis>s1kd-dmrl</emphasis> tool and the <emphasis>s1kd-new*</emphasis> set of tools. These provide two methods of creating objects, either using a data management requirements list (DMRL) or a more on-the-fly approach using the s1kd-new* tools directly.</para>
              <para>The <emphasis>s1kd-defaults</emphasis> tool is used to manage the files which contain default metadata for new CSDB objects.</para>
            </listItem>
            <listItem>
              <para><emphasis>Authoring:</emphasis> These tools support the authoring process.</para>
              <para>The <emphasis>s1kd-addicn</emphasis> tool creates the notation and entity elements to reference an ICN in a data module.</para>
              <para>The <emphasis>s1kd-ls</emphasis> tool lists data modules within a directory.</para>
              <para>The <emphasis>s1kd-metadata</emphasis> tool lists and edits S1000D metadata on CSDB objects.</para>
              <para>The <emphasis>s1kd-mvref</emphasis> tool changes references to one object into references to another.</para>
              <para>The <emphasis>s1kd-ref</emphasis> tool can be used to quickly insert references to other CSDB objects.</para>
              <para>The <emphasis>s1kd-sns</emphasis> tool can be used to organize the CSDB using a given SNS structure.</para>
              <para>The <emphasis>s1kd-upissue</emphasis> tool moves CSDB objects through the standard S1000D workflow, between "inwork" (draft) and "official" states.</para>
            </listItem>
            <listItem>
              <para><emphasis>Validation:</emphasis> These tools all validate different aspects of CSDB objects.</para>
              <para>The <emphasis>s1kd-appcheck</emphasis> tool validates the applicability of CSDB objects.</para>
              <para>The <emphasis>s1kd-brexcheck</emphasis> tool validates CSDB objects against a business rules exchange (BREX) data module, which contains the project-defined computable business rules.</para>
              <para>The <emphasis>s1kd-refs</emphasis> tool lists references in a CSDB object to generate a list of dependencies on other CSDB objects.</para>
              <para>The <emphasis>s1kd-repcheck</emphasis> tool validates CIR references in CSDB objects.</para>
              <para>The <emphasis>s1kd-validate</emphasis> tool validates CSDB objects according to their S1000D schema and general correctness as XML documents.</para>
            </listItem>
            <listItem>
              <para><emphasis>Publication:</emphasis> These tools support the production of publications from a CSDB.</para>
              <para>The <emphasis>s1kd-acronyms</emphasis> tool can automatically mark up acronyms within data modules, and can also generate lists of acronyms marked up within data modules.</para>
              <para>The <emphasis>s1kd-aspp</emphasis> tool preprocesses applicability statements in a data module, generating display text and "presentation" applicability statements.</para>
              <para>The <emphasis>s1kd-flatten</emphasis> tool flattens a publication module and referenced data modules in to a single "deliverable" file for a publishing system.</para>
              <para>The <emphasis>s1kd-fmgen</emphasis> tool generates front matter data module content from a publication module.</para>
              <para>The <emphasis>s1kd-icncatalog</emphasis> tool resolves ICN references in objects.</para>
              <para>The <emphasis>s1kd-index</emphasis> tool flags index keywords in a data module based on a user-defined list.</para>
              <para>The <emphasis>s1kd-instance</emphasis> tool produces "instances" of CSDB objects using applicability filtering and/or common information repositories (CIRs).</para>
              <para>The <emphasis>s1kd-neutralize</emphasis> tool generates IETP neutral metadata for CSDB objects.</para>
              <para>The <emphasis>s1kd-syncrefs</emphasis> tool generates the References table within data modules.</para>
              <para>The <emphasis>s1kd-uom</emphasis> tool converts units of measure used in data modules.</para>
            </listItem>
          </sequentialList>
        </para>
      </levelledPara>
    </description>
  </content>
</dmodule>