..
/
download
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)
gopher://khzae.net/0/s1kd/s1kd-tools/docs/publishing/s1kd-instance.txt