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