..
/
download
# 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>
gopher://khzae.net/0/s1000d/s1kd-tools/src/tools/s1kd-instance/README.md