.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-ref" "1" "2021-04-16" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-ref - Generate XML to reference CSDB objects
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-ref [-cdfgiLlqRrStuvh?] [-$ <issue>] [-s <src>] [-T <opts>]
         [-x <xpath>] [-3 <file>] [-o <dst>] [<code>|<file> ...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-ref\f[R] tool generates the XML for S1000D reference
elements using the specified code or filename.
When using a filename, it can parse the CSDB object to include the
issue, language, and/or title information in the reference.
.SH OPTIONS
.TP
-$, --issue <issue>
Output XML for the specified issue of S1000D.
.TP
-c, --content
When using the -T option, only transform textual references found in the
content section of CSDB objects.
.TP
-d, --include-date
Include the issue date in the reference (target must be a file)
.TP
-f, --overwrite
Overwrite source data module instead of writing to stdout.
.TP
-g, --guess-prefix
Accept references which do not include a standard prefix (e.g.,
\[dq]DMC-\[dq], \[dq]PMC-\[dq]) and guess what they are based on their
format and, when using the -T option, the XML context in which they
occur.
.TP
-h, -?, --help
Show the usage message.
.TP
-i, --include-issue
Include the issue information in the reference (target must be a file)
.TP
-L, --list
Treat input as a list of CSDB objects.
.TP
-l, --include-lang
Include the language information in the reference (target must be a
file)
.TP
-o, --out <dst>
Output to <dst> instead of stdout.
.TP
-q, --quiet
Quiet mode.
Do not print errors.
.TP
-R, --repository-id
Generate a \f[C]<repositorySourceDmIdent>\f[R] for a data module.
.TP
-r, --add
Add the generated reference to the source data module\[aq]s
\f[C]refs\f[R] table and output the modified data module to stdout.
.TP
-S, --source-id
Generate a \f[C]<sourceDmIdent>\f[R] (for data modules) or
\f[C]<sourcePmIdent>\f[R] (for publication modules).
.TP
-s, --source <src>
Specify a source data module <src> to add references to when using the
-r option.
.TP
-T, --transform <opts>
Transform textual references into the appropriate XML within text nodes
in the XML document(s) specified.
The textual references must include the standard prefixes (e.g.,
\[dq]DMC-\[dq], \[dq]PMC-\[aq]), unless the -p option is specified.
<opts> is a sequence of characters from \[dq]CDEGLPSY\[dq], for comment,
data module, external publication, ICN, DML, publication module, SCORM
content package and CSN references respectively.
If \[dq]all\[dq] is given, then all types of references will be
transformed.
.TP
-t, --include-title
Include the title in the reference (target must be a file).
.TP
-u, --include-url
Include the full URL/filename of the reference with the
\f[C]xlink:href\f[R] attribute.
.TP
-v, --verbose
Verbose output.
.TP
-x, --xpath <xpath>
When using the -T option, this specifies which nodes to transform
textual references in.
By default, only the elements which can contain each type of reference
are considered.
.TP
-3, --externalpubs <file>
Use a custom \f[C].externalpubs\f[R] file.
.TP
--version
Show version information.
.TP
<code>|<file>
Either a code, including the prefix (DMC, PMC, etc.), or the filename of
a CSDB object.
.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 \f[C].externalpubs\f[R] file
.PP
The \f[C].externalpubs\f[R] file contains definitions of external
publication references.
This can be used to generate the XML for an external publication
reference by specifying the external publication code.
.PP
Example of a \f[C].externalpubs\f[R] file:
.IP
.nf
\f[C]
<externalPubs>
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
<externalPubTitle>ABC Manual</externalPubTitle>
</externalPubRefIdent>
</externalPubRef>
</externalPubs>
\f[R]
.fi
.SH EXAMPLES
.PP
Reference to data module with data module code:
.IP
.nf
\f[C]
$ s1kd-ref DMC-EX-A-00-00-00-00A-040A-D
<dmRef>
<dmRefIdent>
<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]/>
</dmRefIdent>
</dmRef>
\f[R]
.fi
.PP
Reference to data module with data module code and issue/language:
.IP
.nf
\f[C]
$ s1kd-ref -il DMC-EX-A-00-00-00-00A-040A-D_001-03_EN-CA
<dmRef>
<dmRefIdent>
<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]/>
<issueInfo issueNumber=\[dq]001\[dq] inWork=\[dq]03\[dq]/>
<language languageIsoCode=\[dq]en\[dq] countryIsoCode=\[dq]CA\[dq]/>
</dmRefIdent>
</dmRef>
\f[R]
.fi
.PP
Reference to data module with all information, from a file:
.IP
.nf
\f[C]
$ s1kd-ref -dilt DMC-EX-A-00-00-00-00A-040A-D_001-03_EN-CA.XML
<dmRef>
<dmRefIdent>
<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]/>
<issueInfo issueNumber=\[dq]001\[dq] inWork=\[dq]03\[dq]/>
<language languageIsoCode=\[dq]en\[dq] countryIsoCode=\[dq]CA\[dq]/>
</dmRefIdent>
<dmRefAddressItems>
<dmTitle>
<techName>Example</techName>
<infoName>Description</infoName>
</dmTitle>
<issueDate year=\[dq]2018\[dq] month=\[dq]06\[dq] day=\[dq]25\[dq]/>
</dmRefAddressItems>
</dmRef>
\f[R]
.fi
.PP
Reference to a catalog sequence number:
.IP
.nf
\f[C]
$ s1kd-ref CSN-EX-A-00-00-00-01A-004A-D
<catalogSeqNumberRef modelIdentCode=\[dq]EX\[dq] systemDiffCode=\[dq]A\[dq]
systemCode=\[dq]00\[dq] subSystemCode=\[dq]0\[dq] subSubSystemCode=\[dq]0\[dq] assyCode=\[dq]00\[dq]
figureNumber=\[dq]01\[dq] figureNumberVariant=\[dq]A\[dq] item=\[dq]004\[dq] itemVariant=\[dq]A\[dq]
itemLocationCode=\[dq]D\[dq]/>
\f[R]
.fi
.PP
Reference to a comment:
.IP
.nf
\f[C]
$ s1kd-ref COM-EX-12345-2018-00001-Q
<commentRef>
<commentRefIdent>
<commentCode modelIdentCode=\[dq]EX\[dq] senderIdent=\[dq]12345\[dq]
yearOfDataIssue=\[dq]2018\[dq] seqNumber=\[dq]00001\[dq] commentType=\[dq]q\[dq]/>
</commentRefIdent>
</commentRef>
\f[R]
.fi
.PP
Reference to a data management list:
.IP
.nf
\f[C]
$ s1kd-ref DML-EX-12345-C-2018-00001
<dmlRef>
<dmlRefIdent>
<dmlCode modelIdentCode=\[dq]EX\[dq] senderIdent=\[dq]12345\[dq] dmlType=\[dq]c\[dq]
yearOfDataIssue=\[dq]2018\[dq] seqNumber=\[dq]00001\[dq]/>
</dmlRefIdent>
</dmlRef>
\f[R]
.fi
.PP
Reference to an information control number:
.IP
.nf
\f[C]
$ s1kd-ref ICN-EX-A-000000-A-00001-A-001-01
<infoEntityRef infoEntityRefIdent=\[dq]ICN-EX-A-000000-A-00001-A-001-01\[dq]/>
\f[R]
.fi
.PP
Reference to a publication module:
.IP
.nf
\f[C]
$ s1kd-ref PMC-EX-12345-00001-00
<pmRef>
<pmRefIdent>
<pmCode modelIdentCode=\[dq]EX\[dq] pmIssuer=\[dq]12345\[dq] pmNumber=\[dq]00001\[dq]
pmVolume=\[dq]00\[dq]/>
</pmRefIdent>
</pmRef>
\f[R]
.fi
.PP
Reference to a SCORM content package:
.IP
.nf
\f[C]
$ s1kd-ref SMC-EX-12345-00001-00
<scormContentPackageRef>
<scormContentPackageRefIdent>
<scormContentPackageCode
modelIdentCode=\[dq]EX\[dq]
scormContentPackageIssuer=\[dq]12345\[dq]
scormContentPackageNumber=\[dq]00001\[dq]
scormContentPackageVolume=\[dq]00\[dq]/>
</scormContentPackageRefIdent>
</scormContentPackageRef>
\f[R]
.fi
.PP
Source identification for a data module:
.IP
.nf
\f[C]
$ s1kd-ref -S DMC-EX-A-00-00-00-00A-040A-D_001-00_EN-CA.XML
<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
Source identification for a publication module:
.IP
.nf
\f[C]
$ s1kd-ref -S PMC-EX-12345-00001-00_001-00_EN-CA.XML
<sourcePmIdent>
<pmCode modelIdentCode=\[dq]EX\[dq] pmIssuer=\[dq]12345\[dq] pmNumber=\[dq]00001\[dq]
pmVolume=\[dq]00\[dq]/>
<language languageIsoCode=\[dq]en\[dq] countryIsoCode=\[dq]CA\[dq]/>
<issueInfo issueNumber=\[dq]001\[dq] inWork=\[dq]00\[dq]/>
</sourcePmIdent>
\f[R]
.fi
.PP
Source identification for a SCORM content package:
.IP
.nf
\f[C]
$ s1kd-ref -S SMC-EX-12345-00001-00_001-00_EN-CA.XML
<sourceScormContentPackageIdent>
<scormContentPackageCode
modelIdentCode=\[dq]EX\[dq]
scormContentPackageIssuer=\[dq]12345\[dq]
scormContentPackageNumber=\[dq]00001\[dq]
scormContentPackageVolume=\[dq]00\[dq]/>
<language languageIsoCode=\[dq]en\[dq] countryIsoCode=\[dq]CA\[dq]/>
<issueInfo issueNumber=\[dq]000\[dq] inWork=\[dq]01\[dq]/>
</sourceScormContentPackageIdent>
\f[R]
.fi
.PP
Repository source identification for a CIR data module:
.IP
.nf
\f[C]
$ s1kd-ref -R DMC-EX-A-00-00-00-00A-00GA-D_001-00_EN-CA.XML
<repositorySourceDmIdent>
<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]00G\[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]/>
</repositorySourceDmIdent>
\f[R]
.fi
.PP
Reference to an external publication:
.IP
.nf
\f[C]
$ s1kd-ref ABC
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
</externalPubRefIdent>
</externalPubRef>
\f[R]
.fi
.PP
Reference to an external publication (from the \f[C].externalpubs\f[R]
file):
.IP
.nf
\f[C]
$ s1kd-ref ABC
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
<externalPubTitle>ABC Manual</externalPubTitle>
</externalPubRefIdent>
</externalPubRef>
\f[R]
.fi
.SH AUTHORS
khzae.net.