# NAME

s1kd-instance - Create instances of S1000D CSDB objects

# SYNOPSIS

    s1kd-instance [options] [<object>...]

# DESCRIPTION

The *s1kd-instance* tool produces "instances" of S1000D CSDB objects,
derived from "master" (or "source") objects. The tool supports multiple
methods of instantiating objects:

  - Filtering on user-supplied applicability definitions, so that
    non-applicable elements and (optionally) unused applicability
    annotations are removed in the instance. The definitions can be
    supplied directly or read from a Product Cross-reference Table
    (PCT).

  - Filtering on skill levels and security classifications to remove
    sensitive data.

  - Using a Common Information Repository (CIR) to produce a standalone
    instance from a CIR-dependent master.

Any combination of these methods can be used when producing an instance.

The applications for this tool include:

  - Delivering customized data modules or publications to different
    customers.

  - Creating customized instances of CSDB objects which are maintained
    within the CSDB.

  - As a backend to filter content or resolve CIR dependencies at
    runtime in an electronic viewer application.

# OPTIONS

  - \-A, --simplify  
    Simplify inline applicability annotations, and remove annotations
    which are unambiguously valid or invalid.

  - \-a, --reduce  
    Remove applicability annotations which are unambiguously valid or
    invalid.

  - \-C, --comment \<comment\>  
    Add an XML comment to an instance. Useful as another way of
    identifying an object as an instance aside from the source address
    or extended code, or giving additional information about a
    particular instance. By default, the comment is inserted at the top
    of the document, but this can be customized with the -X option.

  - \-c, --code \<code\>  
    Specify a new data module code (DMC) or publication module code
    (PMC) for the instance.

  - \-D, --dump \<CIR\>  
    Dumps the built-in XSLT used to resolve dependencies for \<CIR\> CIR
    type to stdout. This can be used as a starting point for a custom
    XSLT script to be specified with the -x option.
    
    The following types currently have built-in XSLT and can therefore
    be used as values for \<CIR\>:
    
      - accessPointRepository
    
      - applicRepository
    
      - cautionRepository
    
      - circuitBreakerRepository
    
      - controlIndicatorRepository
    
      - enterpriseRepository
    
      - functionalItemRepository
    
      - illustratedPartsCatalog
    
      - partRepository
    
      - supplyRepository
    
      - toolRepository
    
      - warningRepository
    
      - zoneRepository

  - \-d, --dir \<dir\>  
    Directory to start searching for referenced objects in. By default,
    the current directory will be searched. This applies for the ACT and
    PCT data modules when a product is specified (-p) without specifying
    the PCT explicitly (-P), or when searching for source objects (-@).

  - \-E, --no-extension  
    Remove the extension from an instance produced from an already
    extended object.

  - \-e, --extension \<ext\>  
    Specify an extension on the data module code (DME) or publication
    module code (PME) for the instance.

  - \-F, --flatten-alts  
    After filtering, "alts" elements containing only one child element
    will be "flattened" by replacing them with the applicable child
    element. Alts elements with multiple child elements are left
    untouched.

  - \-f, --overwrite  
    Force overwriting of files.
    
    By itself, this will cause the source object(s) to be overwritten
    instead of being printed to stdout.
    
    When used with the -o or -O options, if a file exists with the same
    name as the one specified (-o) or automatically generated by the
    tool (-O), this will force it to be overwritten. Otherwise, a
    warning will be printed and the existing file will not be
    overwritten.

  - \-G, --custom-orig \<CODE\>/\<NAME\>  
    Similar to the -g option, but instead of the default enterprise code
    and name, use the values \<CODE\> and \<NAME\>, which are separated
    by a slash (/). To only include a code, specify \<CODE\> with no
    slash. To only include a name, specify \<NAME\> prefixed by a slash.

  - \-g, --set-orig  
    Set the originator of the instance. When this option is specified,
    the code "`S1KDI`" and the name "`s1kd-instance tool`" are used by
    default to identify that the instance was produced by this tool. A
    different code and name can be specified with the -G option.

  - \-H, --list-properties \<method\>  
    Create an XML report of all the applicability properties used in,
    and product instances relevant to, the specified CSDB objects.
    \<method\> determines how to include values and products in the
    report:
    
      - "standalone" - Only include the values that are explicitly used
        in the object.
    
      - "all" - Include all values and products as defined in the ACT,
        CCT and PCT.
    
      - "applic" - Only include the values and products, as defined in
        the ACT, CCT and PCT, that are within the applicability of the
        object.

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

  - \-I, --date \<date\>  
    Set the issue date of the instance. By default, the issue date is
    taken from the source. If - is given for \<date\>, the current date
    will be used.

  - \-i, --infoname \<infoName\>  
    Give the data module instance a different infoName.

  - \-J, --clean-display-text  
    Remove display text from annotations which are simplified in -A or
    -9 mode.

  - \-j, --clean-ents  
    After filtering, remove external entities (such as ICNs) which are
    no longer used from the resulting instances.

  - \-K, --skill-levels \<levels\>  
    Filter the object on the specified skill levels. Elements which are
    marked with skill levels not contained in the string \<levels\> are
    removed in the resulting instance.

  - \-k, --skill \<level\>  
    Set the skill level of the instance.

  - \-L, --list  
    Source is a list of object filenames to create instances of, rather
    than an object itself.

  - \-l, --language \<lang\>  
    Set the language and country of the instance. For example, to create
    an instance for US English, lang would be "en-US".

  - \-M, --fix-acronyms  
    Ensure acronyms are still valid after filtering.

  - \-m, --remarks \<remarks\>  
    Set the remarks for the instance.

  - \-N, --omit-issue  
    Omit issue/inwork numbers from automatically generated filenames.

  - \-n, --issue \<iss\>  
    Set the issue and inwork numbers of the instance. By default, the
    issue and inwork number are taken from the source.
    
    When updating an instance (-@), if + is given for \<iss\>, the
    updated instance will have the same issue number with an inwork
    number incremented by one.
    
    Setting the issue of the instance will also set a default issue
    type:
    
      - If the issue is 000-01 thru 001-00, the default issue type will
        be "new".
    
      - If the issue is 001-01 and up and the master is not "new", the
        default issue type will be that of the master.
    
      - If the issue is 001-01 and up but the master is "new", the
        default issue type will be "status".
    
    A different issue type than the default can be set with the -z
    (--issue-type) option.

  - \-O, --outdir \<dir\>  
    Output instance(s) in \<dir\>, automatically naming them based on:
    
      - the extension specified with -e
    
      - the code specified with -c
    
      - The issue info specified with -n
    
      - the language and country specified with -L
    
    If any of the above are not specified, the information is copied
    from the source object.
    
    If \<dir\> does not exist, it will be created.
    
    If a file exists with the same name in the specified directory, a
    warning will be display and the file will not be overwritten, unless
    the -f option is specified.
    
    When using this option, non-XML files, such as external
    publications, may be specified as objects. They will be copied to
    \<dir\>.

  - \-o, --out \<file\>  
    Output instance to file instead of stdout.

  - \-P, --pct \<PCT\>  
    PCT file to read product definitions from (-p). If a product is
    specified but no PCT is given, the tool will attempt to use the ACT
    reference of each source data module to find the ACT and PCT data
    modules in the current directory.

  - \-p, --product \<product\>  
    The ID or primary key of a product in the specified PCT data module
    (-P), the PCT referenced by the ACT data module specified with -1,
    or the PCT data module referenced by the source data module itself.
    A primary key is given in the same form as the -s option and should
    match a unique assign of a product instance, e.g.,
    "`serialno:prodattr=12345`". If the key matches multiple products
    within the PCT, then the objects will be filtered on the combination
    of all matching products.

  - \-Q, --resolve-containers  
    Resolve references to container data modules, selecting the
    appropriate reference for the specified applicability. If zero or
    more than one references are applicable, the reference to the
    container will be left untouched.
    
    Additionally, if the object being filtered is itself a container
    data module, the applicability of the referenced data modules will
    be copied in to it as inline annotations prior to filtering.

  - \-q, --quiet  
    Quiet mode. Errors are not printed.

  - \-R, --cir \<CIR\> ...  
    Use a CIR to resolve external dependencies in the master object,
    making the instance object standalone. Additional CIRs can be used
    by specifying the -R option multiple times.
    
    The following CIRs have some built-in support:
    
      - Access points
    
      - Applicability
    
      - Cautions
    
      - Circuit breakers
    
      - Controls/indicators
    
      - Enterprises
    
      - Functional items
    
      - Illustrated parts data
    
      - Parts
    
      - Supplies
    
      - Tools
    
      - Warnings
    
      - Zones
    
    The methods of resolving the dependencies for a CIR can be changed
    by specifying a custom XSLT script with the -x option. The built-in
    XSLT used for the above CIR data modules can be dumped with the -D
    option.
    
    If "\*" is given for \<CIR\>, the tool will search for CIR data
    modules automatically.

  - \-r, --recursive  
    Search for referenced objects recursively. This applies for the ACT
    and PCT data modules when a product is specified (-p) without
    specifying the PCT explicitly (-P), when searching for source
    objects (-@), or when searching for CIR data modules (-R).

  - \-S, --no-source-ident  
    Do not include \<sourceDmIdent\>/\<sourcePmIdent\> in the instance.

  - \-s, --assign \<applic\>  
    An applicability definition in the form of
    "`<ident>:<type>=<value>`". Any number of values can be defined by
    specifying this option multiple times.

  - \-T, --tag  
    Tag non-applicable elements with the processing instruction
    \<?notApplicable?\> instead of removing them.

  - \-t, --techname \<techName\>  
    Give the instance a different techName/pmTitle.

  - \-U, --security-classes \<classes\>  
    Filter the object on the specified security classes. Elements marked
    with security classes not contained in the string \<classes\> are
    removed in the resulting instance.

  - \-u, --security \<sec\>  
    Set the security classification of the instance. An instance may
    have a lower security classification than the source if classified
    information is removed for a particular customer.

  - \-V, --infoname-variant \<variant\>  
    Give the instance a different info name variant.

  - \-v, --verbose  
    Verbose output.

  - \-W, --set-applic  
    Set the applicability for the whole object, overwriting the current
    applicability with the user-defined applicability values.

  - \-w, --whole-objects  
    Check the applicability, skill level, and security classification of
    the whole object against the user-defined applicability, skill
    levels, and security classifications. If the whole object is not
    applicable, then no instance is created.

  - \-X, --comment-xpath \<path\>  
    The XPath expression indicating where the comment specified with -C
    will be inserted. This should be the path to an element where the
    comment will be inserted as the first child node. By default, this
    is the top of the document.

  - \-x, --xsl \<XSL\>  
    Use a custom XSLT script to resolve CIR dependencies. If this option
    follows -R, the specified XSLT script will only be used for the last
    specified CIR. If it precedes any -R, the specified XSLT script will
    be used for all CIRs that do not override it with a following -x.

  - \-Y, --applic \<text\>  
    Update the applicability for the whole object using the user-defined
    applicability values, and using \<text\> as the new display text.

  - \-y, --update-applic  
    Update the applicability for the whole object using the user-defined
    applicability values.

  - \-Z, --add-required  
    Fix certain elements automatically after filtering. For example, if
    all support equipment is removed due to filtering, a
    `<noSupportEquips>` element will be inserted automatically.

  - \-z, --issue-type \<type\>  
    Set the issue type of the instance.

  - \-1, --act  
    Specify the ACT to use to find the CCT and/or PCT.

  - \-2, --cct  
    Specify the CCT to read dependency tests from (-\~).

  - \-3, --no-repository-ident  
    Do not include a \<repositorySourceDmIdent\> in the instance for
    each CIR.

  - \-4, --flatten-alts-refs  
    Same as the -F option, but in addition to flattening alts elements,
    the `internalRefTargetType` of cross-references to them will be
    changed to the appropriate type (e.g., `"irtt01"` for a `<figure>`
    in a `<figureAlts>`). This is specifically useful for S1000D Issue
    4.1, where the Default BREX does not allow the standard
    `internalRefTargetType` values to be used with the alts elements.

  - \-5, --print  
    When -O is used, print the automatically generated file name of the
    instance.

  - \-6, --clean-annotations  
    Remove unused applicability annotations.

  - \-7, --dry-run  
    Do not actually create or update any instances. This can be combined
    with options like -5 (--print) or -0 (--print-non-applic) to print
    information about what objects would/would not be created or
    updated, but nothing will actually be written out.

  - \-8, --reapply  
    Automatically reapply the applicability of the source object when
    filtering.

  - \-9, --prune  
    Remove only invalid parts of applicability annotations.

  - \-0, --print-non-applic  
    Print the file names of objects which are not applicable, and
    therefore no instance for them will be created. Since this would
    only have an effect in the -w (--whole-objects) mode, that option is
    implied.

  - \-@, --update-instances  
    Rather than source objects, the objects specified are existing
    instances that will be updated.

  - \-%, --read-only  
    Make instance objects read-only.

  - \-\!, --no-infoname  
    Do not include an infoName in the instance.

  - \-\~, --dependencies  
    Add dependency tests from the CCT to assertions that use the
    dependant values.

  - \-^, --remove-deleted  
    Remove elements with change type of "delete" in the resulting
    instance. If -w (--whole-objects) is specified, then no instance
    will be created for objects with an issue type of "deleted".

  - \--version  
    Show version information.

  - \<object\>...  
    Source CSDB objects to instantiate.

In addition, the following options allow configuration of the XML
parser:

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

## Identifying the source of an instance

If the identification information (extension, code, issue or language)
of an instance differs from that of the source, the resulting data
module instance will contain the element `<sourceDmIdent>`, which will
contain the identification elements of the source data module used to
instantiate it. Publication module instances will contain the element
`<sourcePmIdent>` instead.

Additionally, the data module instance will contain an element
`<repositorySourceDmIdent>` for each CIR specified with the -R option.

If the -S (--no-source-ident) option is used, neither the
`<sourceDmIdent>` or `<sourcePmIdent>` elements are added. If the -3
(--no-repository-ident) option is used, no `<repositorySourceDmIdent>`
elements will be added. These options can be useful when this tool is
not used to make an "instance" per se, but more generally to make a
module based on an existing module.

## Removing/simplifying/pruning applicability annotations

By default, filtering on applicability will remove invalid elements from
the resulting instance. In some cases, though, it may be desirable to
remove redundant applicability annotations on valid elements. The -a
(--reduce), -A (--simplify) and -9 (--prune) options provide different
methods of doing this.

The -a (--reduce) option will remove applicability annotations
(`applicRefId`) from elements which are deemed to be unambiguously valid
or invalid (their validity does not rely on applicability values left
undefined by the user). The unused occurrences of the corresponding
`<applic>` elements are removed as well.

The -A (--simplify) option will do the same as the -a option, but will
also attempt to simplify unused parts of applicability annotations. It
simplifies an annotation by removing `<assert>` elements determined to
be either unambiguously valid or invalid given the user-defined values,
and removing unneeded `<evaluate>` elements when they contain only one
remaining `<assert>`.

The -9 (--prune) option works similarly to the -A option, except that
only invalid parts of applicability annotations are removed.

For example, given the following input:

    <referencedApplicGroup>
    <applic id="app-0001">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="app-0002">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    <applic id="app-0003">
    <evaluate andOr="or">
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="normal"/>
    </evaluate>
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="icy"/>
    </evaluate>
    </evaluate>
    </applic>
    </referencedApplicGroup>
    <!-- snip -->
    <para applicRefId="app-0001">This applies to version A.</para>
    <para applicRefId="app-0002">This applies to version B.</para>
    <para applicRefId="app-0003">
    This applies to version A if the weather is normal, or version B if
    the weather is icy.
    </para>

If this data is filtered for version A, without specifying a value for
the weather, and the -a, -A or -9 options are not used, the following
will be the result:

    <referencedApplicGroup>
    <applic id="app-0001">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="app-0002">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    <applic id="app-0003">
    <evaluate andOr="or">
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="normal"/>
    </evaluate>
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="icy"/>
    </evaluate>
    </evaluate>
    </applic>
    </referencedApplicGroup>
    <!-- snip -->
    <para applicRefId="app-0001">This applies to version A.</para>
    <para applicRefId="app-0003">
    This applies to version A if the weather is normal, or version B if
    the weather is icy.
    </para>

The second paragraph is removed, because it only applies to version B.

If the -a option is used, the following would be the result:

    <referencedApplicGroup>
    <applic id="app-0003">
    <evaluate andOr="or">
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="normal"/>
    </evaluate>
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="icy"/>
    </evaluate>
    </evaluate>
    </applic>
    </referencedApplicGroup>
    <!-- snip -->
    <para>This applies to version A.</para>
    <para applicRefId="app-0003">
    This applies to version A if the weather is normal, or version B if
    the weather is icy.
    </para>

The applicability annotation reference for the first paragraph is
removed because, given that the version is A, it must be true. The
corresponding applicability annotations, which are no longer referenced,
are also removed. The applicability on the third paragraph remains,
however, because it is only true if the version is A *and* the weather
is normal, and no value has been given for the weather.

If the -A option is used, the following would be the result:

    <referencedApplicGroup>
    <applic id="app-0003">
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="normal"/>
    </applic>
    </referencedApplicGroup>
    <!-- snip -->
    <para>This applies to version A.</para>
    <para applicRefId="app-0003">
    This applies to version A if the weather is normal, or version B if
    the weather is icy.
    </para>

The annotation is now simplified to remove resolved assertions. Because
the version must be A, any assertions restating this can be removed as
redundant, and any portions of the annotation in which the version is
*not* A can be removed as invalid. This leaves only the assertion about
the weather.

If the -9 option is used, the following would be the result:

    <referencedApplicGroup>
    <applic id="app-0001">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="app-0003">
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="normal"/>
    </evaluate>
    </applic>
    </referencedApplicGroup>
    <!-- snip -->
    <para applicRefId="app-0001">This applies to version A.</para>
    <para applicRefId="app-0003">
    This applies to version A if the weather is normal, or version B if
    the weather is icy.
    </para>

The first annotation is kept because it is entirely valid. The third
annotation is simplified by removing the invalid assertions, but the
valid assertions are preserved.

<div class="note">

The -A and -9 options may change the *meaning* of certain applicability
annotations without changing the *display text*. Display text is always
left untouched, so using this option may cause display text to be
technically incorrect.

These options are best used when display text will be automatically
generated after filtering, such as with the s1kd-aspp tool. The -J
option of this tool can be combined with the -k option of the s1kd-aspp
tool to only generate display text for annotations which are modified.

</div>

## Applicability of an instance (-W, -Y, -y)

The applicability of an instance may change as a result of filtering.
For example, a source data module which is applicable to two versions of
a product may produce two instances which are each only applicable to
one version. There are three options which control how the applicability
of the whole instance object is updated.

The -W option will create an applicability annotation for the instance
using only the user-defined applicability values. This means, for
example, that given the following command:

    $ s1kd-instance -s version:prodattr=A -W ...

The instance would contain the following annotation:

    <dmStatus>
    <!-- snip -->
    <applic>
    <assert applicPropertyIdent="version"
    applicPropertyType="prodattr" applicPropertyValues="A"/>
    </applic>
    <!-- snip -->
    </dmStatus>

regardless of what the applicability of the source object was.

The -y option will create an applicability annotation for the instance
by combining the user-defined applicability with the applicability of
the source object. For example, given the following annotation in the
source object:

    <dmStatus>
    <!-- snip -->
    <applic>
    <assert applicPropertyIdent="version"
    applicPropertyType="prodattr" applicPropertyValues="A"/>
    </applic>
    <!-- snip -->
    </dmStatus>

and the following command:

    $ s1kd-instance -s weather:condition=icy -y ...

The annotation for the instance would be as follows:

    <dmStatus>
    <!-- snip -->
    <applic>
    <evaluate andOr="and">
    <assert applicPropertyIdent="version"
    applicPropertyType="prodattr" applicPropertyValues="A"/>
    <assert applicPropertyIdent="weather"
    applicPropertyType="condition" applicPropertyValues="icy"/>
    </evaluate>
    </applic>
    <!-- snip -->
    </dmStatus>

The -Y option by itself works the same as the -y option, but allows
custom display text to be set for the annotation. It can also be
combined with the -W option to add custom display text to the
overwriting annotation:

    $ s1kd-instance -s version:prodattr=A -WY "Version A" ...

    <dmStatus>
    <!-- snip -->
    <applic>
    <displayText>
    <simplePara>Version A</simplePara>
    </displayText>
    <assert applicPropertyIdent="version"
    applicPropertyType="prodattr" applicPropertyValues="A"/>
    </applic>
    <!-- snip -->
    </dmStatus>

## Filtering for multiple values of a single property

Though not usually the case, it is possible to create an instance which
is filtered on multiple values of the same applicabilty property. Given
the following:

    <referencedApplicGroup>
    <applic id="apA">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="apB">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    <applic id="apC">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="C"/>
    </applic>
    </referencedApplicGroup>
    <!-- ... -->
    <para applicRefId="apA">Applies to A</para>
    <para applicRefId="apB">Applies to B</para>
    <para applicRefId="apC">Applies to C</para>

filtering can be applied such that the instance will be applicable to
both A and C, but not B. This is done by specifying a property multiple
times in the applicability definition arguments. For example:

    $ s1kd-instance -A -Y "A or C" -s attr:prodattr=A -s attr:prodattr=C ...

This would produce the following in the instance:

    <dmStatus>
    <!-- ... -->
    <applic>
    <displayText>
    <simplePara>A or C</simplePara>
    </displayText>
    <evaluate andOr="or">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="C"/>
    </evaluate>
    </applic>
    <!-- ... ->
    </dmStatus>
    <!-- ... -->
    <referencedApplicGroup>
    <applic id="apA">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="apC">
    <assert applicPropertyIdent="attr"
    applicPropertyType="prodattr"
    applicPropertyValues="C"/>
    </applic>
    </referencedApplicGroup>
    <!-- ... -->
    <para applicRefId="apA">Applies to A</para>
    <para applicRefId="apC">Applies to C</para>

## Resolving CIR dependencies with a custom XSLT script (-x)

A CIR contains more information about an item than can be captured in a
data module's reference to it. If this additional information is
required, there are two methods to include it:

  - Distribute the CIR with the data module so the extra information can
    be linked to

  - "Flatten" the information to fit in the data module's schema.

A custom XSLT script can be supplied with the -x option, which is then
used to resolve the CIR dependencies of the last CIR specified with -R.
For example:

    <xsl:stylesheet
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    version="1.0">
    <xsl:template match="functionalItemRef">
    <xsl:variable name="fin" select"@functionalItemNumber"/>
    <xsl:variable name="spec" select="//functionalItemSpec[
    functionalItemIdent/@functionalItemNumber = $fin]"/>
    <xsl:value-of select="$spec/name"/>
    </xsl:template>
    </xsl:stylesheet>

This script would resolve a `functionalItemRef` by "flattening" it to
the value of the `name` element obtained from the CIR.

The example CIR would contain a specification like:

    <functionalItemSpec>
    <functionalItemIdent functionalItemNumber="ABC"
    functionalItemType="fit01"/>
    <name>Hydraulic pump</name>
    <functionalItemAlts>
    <functionalItem/>
    </functionalItemAlts>
    </functionalItemSpec>

The source data module would contain a reference:

    <para>
    The
    <functionalItemRef functionalItemNumber="ABC"/>
    is an item in the system.
    </para>

The command would resemble:

    $ s1kd-instance -R <CIR> -x <custom XSLT> <src>

And the resulting XML would be:

    <para>The Hydraulic pump is an item in the system.</para>

The source data module and CIR are combined in to a single XML document
which is used as the input to the XSLT script. The root element `mux`
contains two `dmodule` elements. The first is the source data module,
and the second is the CIR data module specified with the corresponding
-R option. The CIR data module is first filtered on the defined
applicability.

The set of built-in XSLT scripts used to resolve dependencies can be
dumped using the -D option.

## Updating instances (-@)

The -@ option is used to automatically update instance objects from
their source objects.

The tool will use the `<sourceDmIdent>`/`<sourcePmIdent>` in each
instance to find the source object they were derived from, and filter it
based on the instance's metadata in order to produce an updated version
of the instance. CIRs identified by `<repositorySourceDmIdent>` elements
in the instance will also be used to update it.

Only objects which identify a source object will be processed in this
mode. All other non-instance objects specified are ignored. The elements
`<sourceDmIdent>`, `<sourcePmIdent>` and `<repositorySourceDmIdent>`
identify a specific issue of an object that the instance was last
updated from, but this is ignored and the latest issue found of a source
object will be used instead.

This feature is primarily useful when instances of objects are stored in
the CSDB, rather than only being generated during publication or
dynamically in a viewer. For example, imagine you have a descriptive
data module:

    DMC-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML

and you deliver to two customers, C1 and C2. The data module contains
information for both:

    <description>
    <para>This text applies to all customers.</para>
    <para applicRefId="app-C1">This only applies to Customer 1.</para>
    <para applicRefId="app-C2">This only applies to Customer 2.</para>
    </description>

Neither customer wants to see information that applies only to the
other, so you can create two customized instances of this data module,
identified with the extended code:

    DMC-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML
    DME-12345-C1-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML
    DME-12345-C2-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML

Each instance data module identifies the original data module as its
source:

    <sourceDmIdent>
    <dmCode modelIdentCode="EX" systemDiffCode="A" systemCode="00"
    subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00"
    disassyCodeVariant="A" infoCode="040" infoCodeVariant="A"
    itemLocationCode="D"/>
    <language languageIsoCode="en" countryIsoCode="CA"/>
    <issueInfo issueNumber="001" inWork="00"/>
    </sourceDmIdent>

and is set to apply only to the correct customer:

    <dmStatus>
    ...
    <applic>
    <assert applicPropertyIdent="customer" applicPropertyType="prodattr"
    applicPropertyValues="1"/>
    </applic>
    ...
    </dmStatus>

<div class="note">

The assertions in the applicability of an instance must use single
values in order to work in this mode. Ranges (\~) and sets (|) are not
supported.

</div>

Now, when a change is made to the master data module, this tool can be
used to update these instances automatically:

    $ s1kd-instance -@ -f DME-*.XML

## Reapplying source applicability (-8)

Normally, filtering is based only on the assertions specified by the
user with the -s or -p options. However, in some cases it may be
desirable to take the applicability of the source object itself in to
account, particularly when inline applicability annotations contain
redundant assertions. For example:

    ...
    <dmStatus ...>
    ...
    <applic>
    <displayText>
    <simplePara>Version: A</simplePara>
    </displayText>
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    ...
    </dmStatus>
    ...
    <referencedApplicGroup>
    <applic id="app-0001">
    <displayText>
    <simplePara>Version: A and Weather: Icy</simplePara>
    </displayText>
    <evaluate andOr="and">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    <assert
    applicPropertyIdent="weather"
    applicPropertyType="condition"
    applicPropertyValues="Icy"/>
    </evaluate>
    </applic>
    ...
    <para applicRefId="app-0001">
    Applies to version A when the weather is icy.
    </para>

If this data module is filtered with `-a -s weather:condition=Icy`, the
annotation shown will not be removed, because the tool cannot fully
resolve it, as it is only has a value for the weather condition.

The -8 (--reapply) option will reapply the applicability of each
individual object when filtering it. In the example above, the whole
data module is applicable to version A, and therefore, when the -8
option is specified, this is added to the user-defined assertions
automatically for the given data module. Now the annotation is fully
resolved, and can be removed in accordance with the -a option.

## Ensuring acronyms remain valid after filtering (-M)

The -M (--fix-acronyms) option will ensure that acronyms remain valid
after filtering. Consider the following example:

    ...
    <referencedApplicGroup>
    <applic id="app-A">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="A"/>
    </applic>
    <applic id="app-B">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    </referencedApplicGroup>
    ...
    <para applicRefId="app-A">
    This document discusses
    <acronym>
    <acronymTerm>XML</acronymTerm>
    <acronymDefinition id="acr-XML">
    Extensible Markup Language
    </acronymDefinition>
    </acronym>
    as it is used in Version A of the product.
    </para>
    <para applicRefId="app-B">
    This document discusses
    <acronymTerm internalRefId="acr-XML">XML</acronymTerm>
    as it is used in Version B of the product.
    </para>
    <para>
    Users must have a basic understanding of
    <acronymTerm internalRefId="acr-XML">XML</acronymTerm>
    in order to make full use of the product.
    </para>
    ...

If the data module is filtered for Version B, this will cause the
resulting instance to be invalid, because the acronymTerm in the
paragraph applicable to Version B references the acronym definition in
the paragraph applicable to Version A:

    ...
    <referencedApplicGroup>
    <applic id="app-B">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    </referencedApplicGroup>
    ...
    <para applicRefId="app-B">
    This document discusses
    <acronymTerm internalRefId="acr-XML">XML</acronymTerm>
    as it is used in Version B of the product.
    </para>
    <para>
    Users must have a basic understanding of
    <acronymTerm internalRefId="acr-XML">XML</acronymTerm>
    in order to make full use of the product.
    </para>
    ...

However, if the -M (--fix-acronyms) option is used, the tool will
automatically correct this issue by transforming the first orphaned
acronymTerm into a full acronym element:

    ...
    <referencedApplicGroup>
    <applic id="app-B">
    <assert
    applicPropertyIdent="version"
    applicPropertyType="prodattr"
    applicPropertyValues="B"/>
    </applic>
    </referencedApplicGroup>
    ...
    <para applicRefId="app-B">
    This document discusses
    <acronym>
    <acronymTerm>XML</acronymTerm>
    <acronymDefinition id="acr-XML">
    Extensible Markup Language
    </acronymDefinition>
    </acronym>
    as it is used in Version B of the product.
    </para>
    <para>
    Users must have a basic understanding of
    <acronymTerm internalRefId="acr-XML">XML</acronymTerm>
    in order to make full use of the product.
    </para>
    ...

There are generally two ways a project may point an acronymTerm to the
definition of the acronym: pointing to the `<acronymDefinition>`
element, or pointing to the `<acronym>` element. S1000D does not
explicitly state which is the "correct" option, and has included
examples of both options between different issues of the specification;
however, the later issues after 4.0 use the former option where the
`<acronymTerm>` references the `<acronymDefinition>` element. The -M
option will work with either option, but may not function correctly if
both styles are mixed within the same data module. It is recommended
that projects pick one of the two options and use it consistently.

# EXIT STATUS

  - 0  
    No errors.

  - 1  
    Missing or incomplete argument.

  - 2  
    Specified file does not exist.

  - 3  
    Source object for an instance could not be found.

  - 4  
    Malformed applicability definition.

  - 6  
    XML was invalid or does not conform to S1000D.

  - 7  
    Value given for an argument was malformed.

  - 8  
    Issue date specified with -I is invalid.

  - 9  
    The number of CIR data modules found when searching exceeded the
    available memory.

# EXAMPLES

Filtering a data module on specified applicability and writing to
stdout:

    $ s1kd-instance -s version:prodattr=A <DM>

Filtering a data module on a specified product instance and writing to
stdout:

    $ s1kd-instance -P <PCT> -p versionA <DM>

Filtering a data module on specified skill levels and writing to stdout:

    $ s1kd-instance -k sk01/sk02 <DMs>

Filtering data modules for a particular customer and outputting with
extended identification:

    $ s1kd-instance -s version:prodattr=A -e 12345-54321 -O . <DMs>

Writing out a data module from stdin to a directory with automatic
naming:

    $ xml-transform -s <xsl> <DM> | s1kd-instance -SO <dir>