s1kd-instance(1)                  s1kd-tools                  s1kd-instance(1)

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, de‐
       rived from "master" (or "source") objects.  The tool supports  multiple
       methods of instantiating objects:

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

       · Filtering on skill levels and security classifications to remove sen‐
         sitive 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  in‐
       stance.

       The applications for this tool include:

       · Delivering  customized data modules or publications to different cus‐
         tomers.

       · 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  annota‐
              tions 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 ad‐
              dress 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  op‐
              tion.

       -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  there‐
              fore 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 de‐
              fault, 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  publica‐
              tion module code (PME) for the instance.

       -F, --flatten-alts
              After  filtering, "alts" elements containing only one child ele‐
              ment 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  overwrit‐
              ten 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.  Other‐
              wise, 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 sepa‐
              rated  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 speci‐
              fied, 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  ob‐
              jects.   <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 <lev‐
              els> 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  file‐
              names.

       -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 up‐
              dated  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 de‐
                fault 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 publica‐
              tions,  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 in‐
              stance, e.g., "serialno:prodattr=12345".   If  the  key  matches
              multiple  products within the PCT, then the objects will be fil‐
              tered on the combination of all matching products.

       -Q, --resolve-containers
              Resolve references to container data modules, selecting the  ap‐
              propriate 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 filter‐
              ing.

       -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) with‐
              out 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>=<val‐
              ue>".   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 <class‐
              es> 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 cur‐
              rent applicability with the user-defined applicability values.

       -w, --whole-objects
              Check the applicability, skill level, and  security  classifica‐
              tion 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  speci‐
              fied  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-de‐
              fined  applicability values, and using <text> as the new display
              text.

       -y, --update-applic
              Update the applicability for the whole object using the user-de‐
              fined applicability values.

       -Z, --add-required
              Fix  certain  elements automatically after filtering.  For exam‐
              ple, 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  ele‐
              ments,  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-ap‐
              plic) 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 de‐
              pendant values.

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

       --version
              Show version information.

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

       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.

   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 mod‐
       ule  instance will contain the element <sourceDmIdent>, which will con‐
       tain the identification elements of the source data module used to  in‐
       stantiate  it.   Publication  module instances will contain the element
       <sourcePmIdent> instead.

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

       If  the  -S (--no-source-ident) option is used, neither the <sourceDmI‐
       dent> or <sourcePmIdent> elements are added.  If the -3 (--no-reposito‐
       ry-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 desir‐
       able 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  (appli‐
       cRefId) from elements which are deemed to be unambiguously valid or in‐
       valid (their validity does not rely on applicability values left  unde‐
       fined  by  the user).  The unused occurrences of the corresponding <ap‐
       plic> 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  re‐
       moved  because, given that the version is A, it must be true.  The cor‐
       responding 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.  Be‐
       cause the version must be A, any assertions restating this can  be  re‐
       moved  as  redundant,  and  any portions of the annotation in which the
       version is not A can be removed as invalid.  This leaves only  the  as‐
       sertion 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.

       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 tech‐
       nically incorrect.

       These options are best used when display  text  will  be  automatically
       generated after filtering, such as with the s1kd-aspp tool.  The -J op‐
       tion 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.

   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 applica‐
       bility 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  ex‐
       ample, 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 com‐
       bined 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.  Giv‐
       en 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  multi‐
       ple 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  re‐
       quired, 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 appli‐
       cability.

       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 ele‐
       ments <sourceDmIdent>,  <sourcePmIdent>  and  <repositorySourceDmIdent>
       identify  a  specific issue of an object that the instance was last up‐
       dated 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 dy‐
       namically in a viewer.  For example, imagine you have a descriptive da‐
       ta 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 oth‐
       er, 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>

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

       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  de‐
       sirable to take the applicability of the source object itself in to ac‐
       count, particularly when inline applicability annotations  contain  re‐
       dundant 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 re‐
       solve it, as it is only has a value for the weather condition.

       The  -8 (--reapply) option will reapply the applicability of each indi‐
       vidual 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 re‐
       sulting instance to be invalid, because the acronymTerm  in  the  para‐
       graph  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 auto‐
       matically  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 op‐
       tions between different issues of the specification; however, the later
       issues  after  4.0 use the former option where the <acronymTerm> refer‐
       ences 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  std‐
       out:

              $ 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  std‐
       out:

              $ 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 nam‐
       ing:

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

AUTHORS
       khzae.net.

                                  2024-04-01                  s1kd-instance(1)