s1kd-ref(1)                       s1kd-tools                       s1kd-ref(1)

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 informa‐
       tion 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 oc‐
              cur.

       -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 ta‐
              ble 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 us‐
              ing the -r option.

       -T, --transform <opts>
              Transform  textual  references  into  the appropriate XML within
              text nodes in the XML document(s) specified.  The textual refer‐
              ences 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 trans‐
              form 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 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.

   .externalpubs file
       The .externalpubs file contains  definitions  of  external  publication
       references.   This can be used to generate the XML for an external pub‐
       lication 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>

AUTHORS
       khzae.net.

                                  2021-04-16                       s1kd-ref(1)