.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-instance" "1" "2024-04-01" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-instance - Create instances of S1000D CSDB objects
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-instance [options] [<object>...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-instance\f[R] tool produces \[dq]instances\[dq] of S1000D
CSDB objects, derived from \[dq]master\[dq] (or \[dq]source\[dq])
objects.
The tool supports multiple methods of instantiating objects:
.IP \[bu] 2
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).
.IP \[bu] 2
Filtering on skill levels and security classifications to remove
sensitive data.
.IP \[bu] 2
Using a Common Information Repository (CIR) to produce a standalone
instance from a CIR-dependent master.
.PP
Any combination of these methods can be used when producing an instance.
.PP
The applications for this tool include:
.IP \[bu] 2
Delivering customized data modules or publications to different
customers.
.IP \[bu] 2
Creating customized instances of CSDB objects which are maintained
within the CSDB.
.IP \[bu] 2
As a backend to filter content or resolve CIR dependencies at runtime in
an electronic viewer application.
.SH OPTIONS
.TP
-A, --simplify
Simplify inline applicability annotations, and remove annotations which
are unambiguously valid or invalid.
.TP
-a, --reduce
Remove applicability annotations which are unambiguously valid or
invalid.
.TP
-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.
.TP
-c, --code <code>
Specify a new data module code (DMC) or publication module code (PMC)
for the instance.
.TP
-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.
.RS
.PP
The following types currently have built-in XSLT and can therefore be
used as values for <CIR>:
.IP \[bu] 2
accessPointRepository
.IP \[bu] 2
applicRepository
.IP \[bu] 2
cautionRepository
.IP \[bu] 2
circuitBreakerRepository
.IP \[bu] 2
controlIndicatorRepository
.IP \[bu] 2
enterpriseRepository
.IP \[bu] 2
functionalItemRepository
.IP \[bu] 2
illustratedPartsCatalog
.IP \[bu] 2
partRepository
.IP \[bu] 2
supplyRepository
.IP \[bu] 2
toolRepository
.IP \[bu] 2
warningRepository
.IP \[bu] 2
zoneRepository
.RE
.TP
-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 (-\[at]).
.TP
-E, --no-extension
Remove the extension from an instance produced from an already extended
object.
.TP
-e, --extension <ext>
Specify an extension on the data module code (DME) or publication module
code (PME) for the instance.
.TP
-F, --flatten-alts
After filtering, \[dq]alts\[dq] elements containing only one child
element will be \[dq]flattened\[dq] by replacing them with the
applicable child element.
Alts elements with multiple child elements are left untouched.
.TP
-f, --overwrite
Force overwriting of files.
.RS
.PP
By itself, this will cause the source object(s) to be overwritten
instead of being printed to stdout.
.PP
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.
.RE
.TP
-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.
.TP
-g, --set-orig
Set the originator of the instance.
When this option is specified, the code \[dq]\f[C]S1KDI\f[R]\[dq] and
the name \[dq]\f[C]s1kd-instance tool\f[R]\[dq] 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.
.TP
-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:
.RS
.IP \[bu] 2
\[dq]standalone\[dq] - Only include the values that are explicitly used
in the object.
.IP \[bu] 2
\[dq]all\[dq] - Include all values and products as defined in the ACT,
CCT and PCT.
.IP \[bu] 2
\[dq]applic\[dq] - Only include the values and products, as defined in
the ACT, CCT and PCT, that are within the applicability of the object.
.RE
.TP
-h, -?, --help
Show help/usage message.
.TP
-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.
.TP
-i, --infoname <infoName>
Give the data module instance a different infoName.
.TP
-J, --clean-display-text
Remove display text from annotations which are simplified in -A or -9
mode.
.TP
-j, --clean-ents
After filtering, remove external entities (such as ICNs) which are no
longer used from the resulting instances.
.TP
-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.
.TP
-k, --skill <level>
Set the skill level of the instance.
.TP
-L, --list
Source is a list of object filenames to create instances of, rather than
an object itself.
.TP
-l, --language <lang>
Set the language and country of the instance.
For example, to create an instance for US English, lang would be
\[dq]en-US\[dq].
.TP
-M, --fix-acronyms
Ensure acronyms are still valid after filtering.
.TP
-m, --remarks <remarks>
Set the remarks for the instance.
.TP
-N, --omit-issue
Omit issue/inwork numbers from automatically generated filenames.
.TP
-n, --issue <iss>
Set the issue and inwork numbers of the instance.
By default, the issue and inwork number are taken from the source.
.RS
.PP
When updating an instance (-\[at]), if + is given for <iss>, the updated
instance will have the same issue number with an inwork number
incremented by one.
.PP
Setting the issue of the instance will also set a default issue type:
.IP \[bu] 2
If the issue is 000-01 thru 001-00, the default issue type will be
\[dq]new\[dq].
.IP \[bu] 2
If the issue is 001-01 and up and the master is not \[dq]new\[dq], the
default issue type will be that of the master.
.IP \[bu] 2
If the issue is 001-01 and up but the master is \[dq]new\[dq], the
default issue type will be \[dq]status\[dq].
.PP
A different issue type than the default can be set with the -z
(--issue-type) option.
.RE
.TP
-O, --outdir <dir>
Output instance(s) in <dir>, automatically naming them based on:
.RS
.IP \[bu] 2
the extension specified with -e
.IP \[bu] 2
the code specified with -c
.IP \[bu] 2
The issue info specified with -n
.IP \[bu] 2
the language and country specified with -L
.PP
If any of the above are not specified, the information is copied from
the source object.
.PP
If <dir> does not exist, it will be created.
.PP
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.
.PP
When using this option, non-XML files, such as external publications,
may be specified as objects.
They will be copied to <dir>.
.RE
.TP
-o, --out <file>
Output instance to file instead of stdout.
.TP
-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.
.TP
-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.,
\[dq]\f[C]serialno:prodattr=12345\f[R]\[dq].
If the key matches multiple products within the PCT, then the objects
will be filtered on the combination of all matching products.
.TP
-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.
.RS
.PP
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.
.RE
.TP
-q, --quiet
Quiet mode.
Errors are not printed.
.TP
-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.
.RS
.PP
The following CIRs have some built-in support:
.IP \[bu] 2
Access points
.IP \[bu] 2
Applicability
.IP \[bu] 2
Cautions
.IP \[bu] 2
Circuit breakers
.IP \[bu] 2
Controls/indicators
.IP \[bu] 2
Enterprises
.IP \[bu] 2
Functional items
.IP \[bu] 2
Illustrated parts data
.IP \[bu] 2
Parts
.IP \[bu] 2
Supplies
.IP \[bu] 2
Tools
.IP \[bu] 2
Warnings
.IP \[bu] 2
Zones
.PP
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.
.PP
If \[dq]*\[dq] is given for <CIR>, the tool will search for CIR data
modules automatically.
.RE
.TP
-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 (-\[at]), or when searching for CIR data
modules (-R).
.TP
-S, --no-source-ident
Do not include <sourceDmIdent>/<sourcePmIdent> in the instance.
.TP
-s, --assign <applic>
An applicability definition in the form of
\[dq]\f[C]<ident>:<type>=<value>\f[R]\[dq].
Any number of values can be defined by specifying this option multiple
times.
.TP
-T, --tag
Tag non-applicable elements with the processing instruction
<?notApplicable?> instead of removing them.
.TP
-t, --techname <techName>
Give the instance a different techName/pmTitle.
.TP
-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.
.TP
-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.
.TP
-V, --infoname-variant <variant>
Give the instance a different info name variant.
.TP
-v, --verbose
Verbose output.
.TP
-W, --set-applic
Set the applicability for the whole object, overwriting the current
applicability with the user-defined applicability values.
.TP
-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.
.TP
-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.
.TP
-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.
.TP
-Y, --applic <text>
Update the applicability for the whole object using the user-defined
applicability values, and using <text> as the new display text.
.TP
-y, --update-applic
Update the applicability for the whole object using the user-defined
applicability values.
.TP
-Z, --add-required
Fix certain elements automatically after filtering.
For example, if all support equipment is removed due to filtering, a
\f[C]<noSupportEquips>\f[R] element will be inserted automatically.
.TP
-z, --issue-type <type>
Set the issue type of the instance.
.TP
-1, --act
Specify the ACT to use to find the CCT and/or PCT.
.TP
-2, --cct
Specify the CCT to read dependency tests from (-\[ti]).
.TP
-3, --no-repository-ident
Do not include a <repositorySourceDmIdent> in the instance for each CIR.
.TP
-4, --flatten-alts-refs
Same as the -F option, but in addition to flattening alts elements, the
\f[C]internalRefTargetType\f[R] of cross-references to them will be
changed to the appropriate type (e.g., \f[C]\[dq]irtt01\[dq]\f[R] for a
\f[C]<figure>\f[R] in a \f[C]<figureAlts>\f[R]).
This is specifically useful for S1000D Issue 4.1, where the Default BREX
does not allow the standard \f[C]internalRefTargetType\f[R] values to be
used with the alts elements.
.TP
-5, --print
When -O is used, print the automatically generated file name of the
instance.
.TP
-6, --clean-annotations
Remove unused applicability annotations.
.TP
-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.
.TP
-8, --reapply
Automatically reapply the applicability of the source object when
filtering.
.TP
-9, --prune
Remove only invalid parts of applicability annotations.
.TP
-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.
.TP
-\[at], --update-instances
Rather than source objects, the objects specified are existing instances
that will be updated.
.TP
-%, --read-only
Make instance objects read-only.
.TP
-!, --no-infoname
Do not include an infoName in the instance.
.TP
-\[ti], --dependencies
Add dependency tests from the CCT to assertions that use the dependant
values.
.TP
-\[ha], --remove-deleted
Remove elements with change type of \[dq]delete\[dq] in the resulting
instance.
If -w (--whole-objects) is specified, then no instance will be created
for objects with an issue type of \[dq]deleted\[dq].
.TP
--version
Show version information.
.TP
<object>...
Source CSDB objects to instantiate.
.PP
In addition, the following options allow configuration of the XML
parser:
.TP
--dtdload
Load the external DTD.
.TP
--huge
Remove any internal arbitrary parser limits.
.TP
--net
Allow network access to load external DTD and entities.
.TP
--noent
Resolve entities.
.TP
--parser-errors
Emit errors from parser.
.TP
--parser-warnings
Emit warnings from parser.
.TP
--xinclude
Do XInclude processing.
.TP
--xml-catalog <file>
Use an XML catalog when resolving entities.
Multiple catalogs may be loaded by specifying this option multiple
times.
.SS Identifying the source of an instance
.PP
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 \f[C]<sourceDmIdent>\f[R],
which will contain the identification elements of the source data module
used to instantiate it.
Publication module instances will contain the element
\f[C]<sourcePmIdent>\f[R] instead.
.PP
Additionally, the data module instance will contain an element
\f[C]<repositorySourceDmIdent>\f[R] for each CIR specified with the -R
option.
.PP
If the -S (--no-source-ident) option is used, neither the
\f[C]<sourceDmIdent>\f[R] or \f[C]<sourcePmIdent>\f[R] elements are
added.
If the -3 (--no-repository-ident) option is used, no
\f[C]<repositorySourceDmIdent>\f[R] elements will be added.
These options can be useful when this tool is not used to make an
\[dq]instance\[dq] per se, but more generally to make a module based on
an existing module.
.SS Removing/simplifying/pruning applicability annotations
.PP
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.
.PP
The -a (--reduce) option will remove applicability annotations
(\f[C]applicRefId\f[R]) 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 \f[C]<applic>\f[R] elements
are removed as well.
.PP
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 \f[C]<assert>\f[R] elements
determined to be either unambiguously valid or invalid given the
user-defined values, and removing unneeded \f[C]<evaluate>\f[R] elements
when they contain only one remaining \f[C]<assert>\f[R].
.PP
The -9 (--prune) option works similarly to the -A option, except that
only invalid parts of applicability annotations are removed.
.PP
For example, given the following input:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]app-0001\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]app-0002\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
<applic id=\[dq]app-0003\[dq]>
<evaluate andOr=\[dq]or\[dq]>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]normal\[dq]/>
</evaluate>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]icy\[dq]/>
</evaluate>
</evaluate>
</applic>
</referencedApplicGroup>
<!-- snip -->
<para applicRefId=\[dq]app-0001\[dq]>This applies to version A.</para>
<para applicRefId=\[dq]app-0002\[dq]>This applies to version B.</para>
<para applicRefId=\[dq]app-0003\[dq]>
This applies to version A if the weather is normal, or version B if
the weather is icy.
</para>
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]app-0001\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]app-0002\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
<applic id=\[dq]app-0003\[dq]>
<evaluate andOr=\[dq]or\[dq]>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]normal\[dq]/>
</evaluate>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]icy\[dq]/>
</evaluate>
</evaluate>
</applic>
</referencedApplicGroup>
<!-- snip -->
<para applicRefId=\[dq]app-0001\[dq]>This applies to version A.</para>
<para applicRefId=\[dq]app-0003\[dq]>
This applies to version A if the weather is normal, or version B if
the weather is icy.
</para>
\f[R]
.fi
.PP
The second paragraph is removed, because it only applies to version B.
.PP
If the -a option is used, the following would be the result:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]app-0003\[dq]>
<evaluate andOr=\[dq]or\[dq]>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]normal\[dq]/>
</evaluate>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]icy\[dq]/>
</evaluate>
</evaluate>
</applic>
</referencedApplicGroup>
<!-- snip -->
<para>This applies to version A.</para>
<para applicRefId=\[dq]app-0003\[dq]>
This applies to version A if the weather is normal, or version B if
the weather is icy.
</para>
\f[R]
.fi
.PP
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 \f[I]and\f[R] the weather is normal, and
no value has been given for the weather.
.PP
If the -A option is used, the following would be the result:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]app-0003\[dq]>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]normal\[dq]/>
</applic>
</referencedApplicGroup>
<!-- snip -->
<para>This applies to version A.</para>
<para applicRefId=\[dq]app-0003\[dq]>
This applies to version A if the weather is normal, or version B if
the weather is icy.
</para>
\f[R]
.fi
.PP
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 \f[I]not\f[R] A can be removed as invalid.
This leaves only the assertion about the weather.
.PP
If the -9 option is used, the following would be the result:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]app-0001\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]app-0003\[dq]>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]normal\[dq]/>
</evaluate>
</applic>
</referencedApplicGroup>
<!-- snip -->
<para applicRefId=\[dq]app-0001\[dq]>This applies to version A.</para>
<para applicRefId=\[dq]app-0003\[dq]>
This applies to version A if the weather is normal, or version B if
the weather is icy.
</para>
\f[R]
.fi
.PP
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.
.PP
The -A and -9 options may change the \f[I]meaning\f[R] of certain
applicability annotations without changing the \f[I]display text\f[R].
Display text is always left untouched, so using this option may cause
display text to be technically incorrect.
.PP
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.
.SS Applicability of an instance (-W, -Y, -y)
.PP
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.
.PP
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:
.IP
.nf
\f[C]
$ s1kd-instance -s version:prodattr=A -W ...
\f[R]
.fi
.PP
The instance would contain the following annotation:
.IP
.nf
\f[C]
<dmStatus>
<!-- snip -->
<applic>
<assert applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</applic>
<!-- snip -->
</dmStatus>
\f[R]
.fi
.PP
regardless of what the applicability of the source object was.
.PP
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:
.IP
.nf
\f[C]
<dmStatus>
<!-- snip -->
<applic>
<assert applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</applic>
<!-- snip -->
</dmStatus>
\f[R]
.fi
.PP
and the following command:
.IP
.nf
\f[C]
$ s1kd-instance -s weather:condition=icy -y ...
\f[R]
.fi
.PP
The annotation for the instance would be as follows:
.IP
.nf
\f[C]
<dmStatus>
<!-- snip -->
<applic>
<evaluate andOr=\[dq]and\[dq]>
<assert applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
<assert applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq] applicPropertyValues=\[dq]icy\[dq]/>
</evaluate>
</applic>
<!-- snip -->
</dmStatus>
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
$ s1kd-instance -s version:prodattr=A -WY \[dq]Version A\[dq] ...
\f[R]
.fi
.IP
.nf
\f[C]
<dmStatus>
<!-- snip -->
<applic>
<displayText>
<simplePara>Version A</simplePara>
</displayText>
<assert applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq] applicPropertyValues=\[dq]A\[dq]/>
</applic>
<!-- snip -->
</dmStatus>
\f[R]
.fi
.SS Filtering for multiple values of a single property
.PP
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:
.IP
.nf
\f[C]
<referencedApplicGroup>
<applic id=\[dq]apA\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]apB\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
<applic id=\[dq]apC\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]C\[dq]/>
</applic>
</referencedApplicGroup>
<!-- ... -->
<para applicRefId=\[dq]apA\[dq]>Applies to A</para>
<para applicRefId=\[dq]apB\[dq]>Applies to B</para>
<para applicRefId=\[dq]apC\[dq]>Applies to C</para>
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
$ s1kd-instance -A -Y \[dq]A or C\[dq] -s attr:prodattr=A -s attr:prodattr=C ...
\f[R]
.fi
.PP
This would produce the following in the instance:
.IP
.nf
\f[C]
<dmStatus>
<!-- ... -->
<applic>
<displayText>
<simplePara>A or C</simplePara>
</displayText>
<evaluate andOr=\[dq]or\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]C\[dq]/>
</evaluate>
</applic>
<!-- ... ->
</dmStatus>
<!-- ... -->
<referencedApplicGroup>
<applic id=\[dq]apA\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]apC\[dq]>
<assert applicPropertyIdent=\[dq]attr\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]C\[dq]/>
</applic>
</referencedApplicGroup>
<!-- ... -->
<para applicRefId=\[dq]apA\[dq]>Applies to A</para>
<para applicRefId=\[dq]apC\[dq]>Applies to C</para>
\f[R]
.fi
.SS Resolving CIR dependencies with a custom XSLT script (-x)
.PP
A CIR contains more information about an item than can be captured in a
data module\[aq]s reference to it.
If this additional information is required, there are two methods to
include it:
.IP \[bu] 2
Distribute the CIR with the data module so the extra information can be
linked to
.IP \[bu] 2
\[dq]Flatten\[dq] the information to fit in the data module\[aq]s
schema.
.PP
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:
.IP
.nf
\f[C]
<xsl:stylesheet
xmlns:xsl=\[dq]http://www.w3.org/1999/XSL/Transform\[dq]
version=\[dq]1.0\[dq]>
<xsl:template match=\[dq]functionalItemRef\[dq]>
<xsl:variable name=\[dq]fin\[dq] select\[dq]\[at]functionalItemNumber\[dq]/>
<xsl:variable name=\[dq]spec\[dq] select=\[dq]//functionalItemSpec[
functionalItemIdent/\[at]functionalItemNumber = $fin]\[dq]/>
<xsl:value-of select=\[dq]$spec/name\[dq]/>
</xsl:template>
</xsl:stylesheet>
\f[R]
.fi
.PP
This script would resolve a \f[C]functionalItemRef\f[R] by
\[dq]flattening\[dq] it to the value of the \f[C]name\f[R] element
obtained from the CIR.
.PP
The example CIR would contain a specification like:
.IP
.nf
\f[C]
<functionalItemSpec>
<functionalItemIdent functionalItemNumber=\[dq]ABC\[dq]
functionalItemType=\[dq]fit01\[dq]/>
<name>Hydraulic pump</name>
<functionalItemAlts>
<functionalItem/>
</functionalItemAlts>
</functionalItemSpec>
\f[R]
.fi
.PP
The source data module would contain a reference:
.IP
.nf
\f[C]
<para>
The
<functionalItemRef functionalItemNumber=\[dq]ABC\[dq]/>
is an item in the system.
</para>
\f[R]
.fi
.PP
The command would resemble:
.IP
.nf
\f[C]
$ s1kd-instance -R <CIR> -x <custom XSLT> <src>
\f[R]
.fi
.PP
And the resulting XML would be:
.IP
.nf
\f[C]
<para>The Hydraulic pump is an item in the system.</para>
\f[R]
.fi
.PP
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 \f[C]mux\f[R] contains two \f[C]dmodule\f[R] 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.
.PP
The set of built-in XSLT scripts used to resolve dependencies can be
dumped using the -D option.
.SS Updating instances (-\[at])
.PP
The -\[at] option is used to automatically update instance objects from
their source objects.
.PP
The tool will use the
\f[C]<sourceDmIdent>\f[R]/\f[C]<sourcePmIdent>\f[R] in each instance to
find the source object they were derived from, and filter it based on
the instance\[aq]s metadata in order to produce an updated version of
the instance.
CIRs identified by \f[C]<repositorySourceDmIdent>\f[R] elements in the
instance will also be used to update it.
.PP
Only objects which identify a source object will be processed in this
mode.
All other non-instance objects specified are ignored.
The elements \f[C]<sourceDmIdent>\f[R], \f[C]<sourcePmIdent>\f[R] and
\f[C]<repositorySourceDmIdent>\f[R] 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.
.PP
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:
.IP
.nf
\f[C]
DMC-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML
\f[R]
.fi
.PP
and you deliver to two customers, C1 and C2.
The data module contains information for both:
.IP
.nf
\f[C]
<description>
<para>This text applies to all customers.</para>
<para applicRefId=\[dq]app-C1\[dq]>This only applies to Customer 1.</para>
<para applicRefId=\[dq]app-C2\[dq]>This only applies to Customer 2.</para>
</description>
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
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
\f[R]
.fi
.PP
Each instance data module identifies the original data module as its
source:
.IP
.nf
\f[C]
<sourceDmIdent>
<dmCode modelIdentCode=\[dq]EX\[dq] systemDiffCode=\[dq]A\[dq] systemCode=\[dq]00\[dq]
subSystemCode=\[dq]0\[dq] subSubSystemCode=\[dq]0\[dq] assyCode=\[dq]00\[dq] disassyCode=\[dq]00\[dq]
disassyCodeVariant=\[dq]A\[dq] infoCode=\[dq]040\[dq] infoCodeVariant=\[dq]A\[dq]
itemLocationCode=\[dq]D\[dq]/>
<language languageIsoCode=\[dq]en\[dq] countryIsoCode=\[dq]CA\[dq]/>
<issueInfo issueNumber=\[dq]001\[dq] inWork=\[dq]00\[dq]/>
</sourceDmIdent>
\f[R]
.fi
.PP
and is set to apply only to the correct customer:
.IP
.nf
\f[C]
<dmStatus>
\&...
<applic>
<assert applicPropertyIdent=\[dq]customer\[dq] applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]1\[dq]/>
</applic>
\&...
</dmStatus>
\f[R]
.fi
.PP
The assertions in the applicability of an instance must use single
values in order to work in this mode.
Ranges (\[ti]) and sets (|) are not supported.
.PP
Now, when a change is made to the master data module, this tool can be
used to update these instances automatically:
.IP
.nf
\f[C]
$ s1kd-instance -\[at] -f DME-*.XML
\f[R]
.fi
.SS Reapplying source applicability (-8)
.PP
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:
.IP
.nf
\f[C]
\&...
<dmStatus ...>
\&...
<applic>
<displayText>
<simplePara>Version: A</simplePara>
</displayText>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
\&...
</dmStatus>
\&...
<referencedApplicGroup>
<applic id=\[dq]app-0001\[dq]>
<displayText>
<simplePara>Version: A and Weather: Icy</simplePara>
</displayText>
<evaluate andOr=\[dq]and\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
<assert
applicPropertyIdent=\[dq]weather\[dq]
applicPropertyType=\[dq]condition\[dq]
applicPropertyValues=\[dq]Icy\[dq]/>
</evaluate>
</applic>
\&...
<para applicRefId=\[dq]app-0001\[dq]>
Applies to version A when the weather is icy.
</para>
\f[R]
.fi
.PP
If this data module is filtered with
\f[C]-a -s weather:condition=Icy\f[R], 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.
.PP
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.
.SS Ensuring acronyms remain valid after filtering (-M)
.PP
The -M (--fix-acronyms) option will ensure that acronyms remain valid
after filtering.
Consider the following example:
.IP
.nf
\f[C]
\&...
<referencedApplicGroup>
<applic id=\[dq]app-A\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]A\[dq]/>
</applic>
<applic id=\[dq]app-B\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
</referencedApplicGroup>
\&...
<para applicRefId=\[dq]app-A\[dq]>
This document discusses
<acronym>
<acronymTerm>XML</acronymTerm>
<acronymDefinition id=\[dq]acr-XML\[dq]>
Extensible Markup Language
</acronymDefinition>
</acronym>
as it is used in Version A of the product.
</para>
<para applicRefId=\[dq]app-B\[dq]>
This document discusses
<acronymTerm internalRefId=\[dq]acr-XML\[dq]>XML</acronymTerm>
as it is used in Version B of the product.
</para>
<para>
Users must have a basic understanding of
<acronymTerm internalRefId=\[dq]acr-XML\[dq]>XML</acronymTerm>
in order to make full use of the product.
</para>
\&...
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
\&...
<referencedApplicGroup>
<applic id=\[dq]app-B\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
</referencedApplicGroup>
\&...
<para applicRefId=\[dq]app-B\[dq]>
This document discusses
<acronymTerm internalRefId=\[dq]acr-XML\[dq]>XML</acronymTerm>
as it is used in Version B of the product.
</para>
<para>
Users must have a basic understanding of
<acronymTerm internalRefId=\[dq]acr-XML\[dq]>XML</acronymTerm>
in order to make full use of the product.
</para>
\&...
\f[R]
.fi
.PP
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:
.IP
.nf
\f[C]
\&...
<referencedApplicGroup>
<applic id=\[dq]app-B\[dq]>
<assert
applicPropertyIdent=\[dq]version\[dq]
applicPropertyType=\[dq]prodattr\[dq]
applicPropertyValues=\[dq]B\[dq]/>
</applic>
</referencedApplicGroup>
\&...
<para applicRefId=\[dq]app-B\[dq]>
This document discusses
<acronym>
<acronymTerm>XML</acronymTerm>
<acronymDefinition id=\[dq]acr-XML\[dq]>
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=\[dq]acr-XML\[dq]>XML</acronymTerm>
in order to make full use of the product.
</para>
\&...
\f[R]
.fi
.PP
There are generally two ways a project may point an acronymTerm to the
definition of the acronym: pointing to the \f[C]<acronymDefinition>\f[R]
element, or pointing to the \f[C]<acronym>\f[R] element.
S1000D does not explicitly state which is the \[dq]correct\[dq] 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 \f[C]<acronymTerm>\f[R] references the
\f[C]<acronymDefinition>\f[R] 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.
.SH EXIT STATUS
.TP
0
No errors.
.TP
1
Missing or incomplete argument.
.TP
2
Specified file does not exist.
.TP
3
Source object for an instance could not be found.
.TP
4
Malformed applicability definition.
.TP
6
XML was invalid or does not conform to S1000D.
.TP
7
Value given for an argument was malformed.
.TP
8
Issue date specified with -I is invalid.
.TP
9
The number of CIR data modules found when searching exceeded the
available memory.
.SH EXAMPLES
.PP
Filtering a data module on specified applicability and writing to
stdout:
.IP
.nf
\f[C]
$ s1kd-instance -s version:prodattr=A <DM>
\f[R]
.fi
.PP
Filtering a data module on a specified product instance and writing to
stdout:
.IP
.nf
\f[C]
$ s1kd-instance -P <PCT> -p versionA <DM>
\f[R]
.fi
.PP
Filtering a data module on specified skill levels and writing to stdout:
.IP
.nf
\f[C]
$ s1kd-instance -k sk01/sk02 <DMs>
\f[R]
.fi
.PP
Filtering data modules for a particular customer and outputting with
extended identification:
.IP
.nf
\f[C]
$ s1kd-instance -s version:prodattr=A -e 12345-54321 -O . <DMs>
\f[R]
.fi
.PP
Writing out a data module from stdin to a directory with automatic
naming:
.IP
.nf
\f[C]
$ xml-transform -s <xsl> <DM> | s1kd-instance -SO <dir>
\f[R]
.fi
.SH AUTHORS
khzae.net.