..
/
download
<?xml version="1.0"?>
<dmodule xmlns:dc="http://www.purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.s1000d.org/S1000D_5-0/xml_schema_flat/descript.xsd">
<identAndStatusSection>
<dmAddress>
<dmIdent>
<dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="08" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
<language languageIsoCode="en" countryIsoCode="CA"/>
<issueInfo issueNumber="027" inWork="00"/>
</dmIdent>
<dmAddressItems>
<issueDate year="2020" month="09" day="01"/>
<dmTitle>
<techName>s1kd-ref</techName>
<infoName>Description</infoName>
</dmTitle>
</dmAddressItems>
</dmAddress>
<dmStatus issueType="changed">
<security securityClassification="01"/>
<responsiblePartnerCompany>
<enterpriseName>khzae.net</enterpriseName>
</responsiblePartnerCompany>
<originator>
<enterpriseName>khzae.net</enterpriseName>
</originator>
<applic>
<displayText>
<simplePara>All</simplePara>
</displayText>
</applic>
<brexDmRef>
<dmRef>
<dmRefIdent>
<dmCode modelIdentCode="S1KDTOOLS" systemDiffCode="A" systemCode="00" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
</dmRefIdent>
</dmRef>
</brexDmRef>
<qualityAssurance>
<unverified/>
</qualityAssurance>
<reasonForUpdate id="rfu-xml-catalog" updateHighlight="1" updateReasonType="urt02">
<simplePara>Add --xml-catalog parser option.</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
<content>
<description>
<levelledPara>
<title>General</title>
<para>The <emphasis>s1kd-ref</emphasis> 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.</para>
</levelledPara>
<levelledPara>
<title>Usage</title>
<para>
<verbatimText verbatimStyle="vs24">s1kd-ref [-cdfgiLlqRrStuvh?] [-$ <issue>] [-s <src>] [-T <opts>]
[-x <xpath>] [-3 <file>] [-o <dst>] [<code>|<file> ...]</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Options</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>-$, --issue <issue></listItemTerm>
<listItemDefinition>
<para>Output XML for the specified issue of S1000D.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-c, --content</listItemTerm>
<listItemDefinition>
<para>When using the -T option, only transform textual references found in the content section of CSDB objects.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-d, --include-date</listItemTerm>
<listItemDefinition>
<para>Include the issue date in the reference (target must be a file)</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-f, --overwrite</listItemTerm>
<listItemDefinition>
<para>Overwrite source data module instead of writing to stdout.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-g, --guess-prefix</listItemTerm>
<listItemDefinition>
<para>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.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-h, -?, --help</listItemTerm>
<listItemDefinition>
<para>Show the usage message.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-i, --include-issue</listItemTerm>
<listItemDefinition>
<para>Include the issue information in the reference (target must be a file)</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-L, --list</listItemTerm>
<listItemDefinition>
<para>Treat input as a list of CSDB objects.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-l, --include-lang</listItemTerm>
<listItemDefinition>
<para>Include the language information in the reference (target must be a file)</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-o, --out <dst></listItemTerm>
<listItemDefinition>
<para>Output to <dst> instead of stdout.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-q, --quiet</listItemTerm>
<listItemDefinition>
<para>Quiet mode. Do not print errors.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-R, --repository-id</listItemTerm>
<listItemDefinition>
<para>Generate a <verbatimText verbatimStyle="vs12"><repositorySourceDmIdent></verbatimText> for a data module.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-r, --add</listItemTerm>
<listItemDefinition>
<para>Add the generated reference to the source data module's <verbatimText verbatimStyle="vs12">refs</verbatimText> table and output the modified data module to stdout.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-S, --source-id</listItemTerm>
<listItemDefinition>
<para>Generate a <verbatimText verbatimStyle="vs12"><sourceDmIdent></verbatimText> (for data modules) or <verbatimText verbatimStyle="vs12"><sourcePmIdent></verbatimText> (for publication modules).</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-s, --source <src></listItemTerm>
<listItemDefinition>
<para>Specify a source data module <src> to add references to when using the -r option.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-T, --transform <opts></listItemTerm>
<listItemDefinition>
<para>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.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-t, --include-title</listItemTerm>
<listItemDefinition>
<para>Include the title in the reference (target must be a file).</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-u, --include-url</listItemTerm>
<listItemDefinition>
<para>Include the full URL/filename of the reference with the <verbatimText verbatimStyle="vs13">xlink:href</verbatimText> attribute.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-v, --verbose</listItemTerm>
<listItemDefinition>
<para>Verbose output.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-x, --xpath <xpath></listItemTerm>
<listItemDefinition>
<para>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.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-3, --externalpubs <file></listItemTerm>
<listItemDefinition>
<para>Use a custom <verbatimText verbatimStyle="vs02">.externalpubs</verbatimText> file.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>--version</listItemTerm>
<listItemDefinition>
<para>Show version information.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm><code>|<file></listItemTerm>
<listItemDefinition>
<para>Either a code, including the prefix (DMC, PMC, etc.), or the filename of a CSDB object.</para>
</listItemDefinition>
</definitionListItem>
</definitionList>
</para>
<para>
In addition, the following options allow configuration of the XML parser:
<definitionList><definitionListItem><listItemTerm>--dtdload</listItemTerm><listItemDefinition><para>Load the external DTD.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--huge</listItemTerm><listItemDefinition><para>Remove any internal arbitrary parser limits.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--net</listItemTerm><listItemDefinition><para>Allow network access to load external DTD and entities.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--noent</listItemTerm><listItemDefinition><para>Resolve entities.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--parser-errors</listItemTerm><listItemDefinition><para>Emit errors from parser.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--parser-warnings</listItemTerm><listItemDefinition><para>Emit warnings from parser.</para></listItemDefinition></definitionListItem><definitionListItem><listItemTerm>--xinclude</listItemTerm><listItemDefinition><para>Do XInclude processing.</para></listItemDefinition></definitionListItem><definitionListItem changeMark="1" changeType="add" reasonForUpdateRefIds="rfu-xml-catalog"><listItemTerm>--xml-catalog <file></listItemTerm><listItemDefinition><para>Use an XML catalog when resolving entities. Multiple catalogs may be loaded by specifying this option multiple times.</para></listItemDefinition></definitionListItem></definitionList>
</para>
<levelledPara>
<title><verbatimText verbatimStyle="vs02">.externalpubs</verbatimText> file</title>
<para>The <verbatimText verbatimStyle="vs02">.externalpubs</verbatimText> 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.</para>
<para>Example of a <verbatimText verbatimStyle="vs02">.externalpubs</verbatimText> file:
<verbatimText verbatimStyle="vs11"><externalPubs>
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
<externalPubTitle>ABC Manual</externalPubTitle>
</externalPubRefIdent>
</externalPubRef>
</externalPubs></verbatimText>
</para>
</levelledPara>
</levelledPara>
<levelledPara>
<title>Examples</title>
<para>Reference to data module with data module code:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Reference to data module with data module code and issue/language:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Reference to data module with all information, from a file:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Reference to a catalog sequence number:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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"/></verbatimText>
</para>
<para>Reference to a comment:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref COM-EX-12345-2018-00001-Q
<commentRef>
<commentRefIdent>
<commentCode modelIdentCode="EX" senderIdent="12345"
yearOfDataIssue="2018" seqNumber="00001" commentType="q"/>
</commentRefIdent>
</commentRef></verbatimText>
</para>
<para>Reference to a data management list:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref DML-EX-12345-C-2018-00001
<dmlRef>
<dmlRefIdent>
<dmlCode modelIdentCode="EX" senderIdent="12345" dmlType="c"
yearOfDataIssue="2018" seqNumber="00001"/>
</dmlRefIdent>
</dmlRef></verbatimText>
</para>
<para>Reference to an information control number:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref ICN-EX-A-000000-A-00001-A-001-01
<infoEntityRef infoEntityRefIdent="ICN-EX-A-000000-A-00001-A-001-01"/></verbatimText>
</para>
<para>Reference to a publication module:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref PMC-EX-12345-00001-00
<pmRef>
<pmRefIdent>
<pmCode modelIdentCode="EX" pmIssuer="12345" pmNumber="00001"
pmVolume="00"/>
</pmRefIdent>
</pmRef></verbatimText>
</para>
<para>Reference to a SCORM content package:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref SMC-EX-12345-00001-00
<scormContentPackageRef>
<scormContentPackageRefIdent>
<scormContentPackageCode
modelIdentCode="EX"
scormContentPackageIssuer="12345"
scormContentPackageNumber="00001"
scormContentPackageVolume="00"/>
</scormContentPackageRefIdent>
</scormContentPackageRef></verbatimText>
</para>
<para>Source identification for a data module:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Source identification for a publication module:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Source identification for a SCORM content package:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Repository source identification for a CIR data module:</para>
<para>
<verbatimText verbatimStyle="vs23">$ 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></verbatimText>
</para>
<para>Reference to an external publication:</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref ABC
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
</externalPubRefIdent>
</externalPubRef></verbatimText>
</para>
<para>Reference to an external publication (from the <verbatimText verbatimStyle="vs02">.externalpubs</verbatimText> file):</para>
<para>
<verbatimText verbatimStyle="vs23">$ s1kd-ref ABC
<externalPubRef>
<externalPubRefIdent>
<externalPubCode>ABC</externalPubCode>
<externalPubTitle>ABC Manual</externalPubTitle>
</externalPubRefIdent>
</externalPubRef></verbatimText>
</para>
</levelledPara>
</description>
</content>
</dmodule>
gopher://khzae.net/0/s1000d/s1kd-tools/sample/csdb/DMC-S1KDTOOLS-A-08-00-00-00A-040A-D_EN-CA.XML