..
/
download
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dmodule>
<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="32" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
<language languageIsoCode="en" countryIsoCode="CA"/>
<issueInfo issueNumber="021" inWork="00"/>
</dmIdent>
<dmAddressItems>
<issueDate year="2021" month="04" day="16"/>
<dmTitle>
<techName>s1kd-icncatalog(1) | s1kd-tools</techName>
</dmTitle>
</dmAddressItems>
</dmAddress>
<dmStatus issueType="status">
<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="S1000D" systemDiffCode="G" systemCode="04" subSystemCode="1" subSubSystemCode="0" assyCode="0301" disassyCode="00" disassyCodeVariant="A" infoCode="022" infoCodeVariant="A" itemLocationCode="D"/>
</dmRefIdent>
</dmRef>
</brexDmRef>
<qualityAssurance>
<unverified/>
</qualityAssurance>
<reasonForUpdate>
<simplePara>Upissued</simplePara>
</reasonForUpdate>
</dmStatus>
</identAndStatusSection>
<content>
<description>
<levelledPara>
<title>NAME</title>
<para>s1kd-icncatalog - Manage the catalog used to resolve ICNs</para>
</levelledPara>
<levelledPara>
<title>SYNOPSIS</title>
<para>
<verbatimText verbatimStyle="vs24">s1kd-icncatalog [options] [<object>...]</verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>DESCRIPTION</title>
<para>The <emphasis>s1kd-icncatalog</emphasis> tool is used to manage a catalog of ICNs for a project, and to resolve ICNs using this catalog. Resolving an ICN means placing the actual filename of the ICN in to the SYSTEM ID of the ENTITY declaration within CSDB objects.</para>
</levelledPara>
<levelledPara>
<title>OPTIONS</title>
<para>
<definitionList>
<definitionListItem>
<listItemTerm>-a, --add <ICN></listItemTerm>
<listItemDefinition>
<para>Add an ICN to the catalog. Follow with the -u and -n options to specify the URI and notation to use for this ICN. The -m option specifies a media group to add the ICN to.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-C, --create</listItemTerm>
<listItemDefinition>
<para>Create a new empty catalog.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-c, --catalog <catalog></listItemTerm>
<listItemDefinition>
<para>Specify the catalog file to manage or resolve against. By default, the file <verbatimText verbatimStyle="vs02">.icncatalog</verbatimText> in the current directory is used. If the current directory does not contain this file, the parent directories will be searched.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-d, --del <ICN></listItemTerm>
<listItemDefinition>
<para>Delete an ICN from the catalog. The -m option specifies a media group to delete the ICN from.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-f, --overwrite</listItemTerm>
<listItemDefinition>
<para>Overwrite the input CSDB objects when resolving ICNs, or overwrite the catalog file when modifying it. Otherwise, output is written to stdout.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-h, -?, --help</listItemTerm>
<listItemDefinition>
<para>Show help/usage message.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-l, --list</listItemTerm>
<listItemDefinition>
<para>Treat input (stdin or arguments) as lists of filenames of CSDB objects, rather than CSDB objects themselves.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-m, --media <media></listItemTerm>
<listItemDefinition>
<para>Resolve ICNs for this intended output media. The catalog may contain alternative formats for the same ICN to be used for different output media.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-n, --ndata <notation></listItemTerm>
<listItemDefinition>
<para>Specify the notation to reference when adding an ICN with the -a option.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-q, --quiet</listItemTerm>
<listItemDefinition>
<para>Quiet mode. Errors are not printed.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-t, --type <type></listItemTerm>
<listItemDefinition>
<para>Specify the type of catalog entry when adding an ICN with the -a option.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-u, --uri <URI></listItemTerm>
<listItemDefinition>
<para>Specify the URI when adding an ICN with the -a option.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>-v, --verbose</listItemTerm>
<listItemDefinition>
<para>Verbose output.</para>
</listItemDefinition>
</definitionListItem>
<definitionListItem>
<listItemTerm>--version</listItemTerm>
<listItemDefinition>
<para>Show version information.</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>
<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>
<levelledPara>
<title>EXAMPLES</title>
<levelledPara>
<title>Resolving ICNs to filenames</title>
<para>A CSDB object may reference an ICN as follows:</para>
<para>
<verbatimText verbatimStyle="vs11"><!NOTATION png SYSTEM "png">
<!ENTITY ICN-12345-00001-001-01 SYSTEM "ICN-12345-00001-001-01.PNG"
NDATA png></verbatimText>
</para>
<para>The SYSTEM ID of this ENTITY indicates that the ICN file will be in the same directory relative to the CSDB object. However, the ICN files in this example are located in a separate folder called 'graphics'. Rather than manually updating every ENTITY declaration in every CSDB object, a catalog file can be used to map ICNs to actual filenames:</para>
<para>
<verbatimText verbatimStyle="vs11"><icnCatalog>
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="graphics/ICN-12345-00001-001-01.PNG"/>
</icnCatalog></verbatimText>
</para>
<para>Then, using this tool, the ICN can be resolved against the catalog:</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-icncatalog -c <catalog> <object></verbatimText>
</para>
<para>Producing the following output:</para>
<para>
<verbatimText verbatimStyle="vs11"><!NOTATION png SYSTEM "png">
<!ENTITY ICN-12345-00001-001-01 SYSTEM
"graphics/ICN-12345-00001-001-01.PNG" NDATA png></verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Alternative ICN formats</title>
<para>A catalog can also be used to provide alternative file formats for an ICN depending on the intended output media. For example:</para>
<para>
<verbatimText verbatimStyle="vs11"><icnCatalog>
<notation name="jpg" systemId="jpg"/>
<notation name="svg" systemId="svg"/>
<media name="pdf">
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="ICN-12345-00001-001-01.JPG" notation="jpg"/>
</media>
<media name="web">
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="ICN-12345-00001-001-01.SVG" notation="svg"/>
</media>
</icnCatalog></verbatimText>
</para>
<para>The -m option allows for specifying which type of media to resolve for:</para>
<para>
<verbatimText verbatimStyle="vs11"><!NOTATION png SYSTEM "png">
<!ENTITY ICN-12345-00001-001-01 SYSTEM "ICN-12345-00001-001-01.PNG"
NDATA png></verbatimText>
</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-icncatalog -c <catalog> -m pdf <object></verbatimText>
</para>
<para>
<verbatimText verbatimStyle="vs11"><!NOTATION png SYSTEM "png">
<!NOTATION jpg SYSTEM "jpg">
<!ENTITY ICN-12345-00001-001-01 SYSTEM "ICN-12345-00001-001-01.JPG"
NDATA jpg></verbatimText>
</para>
<para>
<verbatimText verbatimStyle="vs24">$ s1kd-icncatalog -c <catalog> -m web <object></verbatimText>
</para>
<para>
<verbatimText verbatimStyle="vs11"><!NOTATION png SYSTEM "png">
<!NOTATION svg SYSTEM "svg">
<!ENTITY ICN-12345-00001-001-01 SYSTEM "ICN-12345-00001-001-01.SVG"
NDATA svg></verbatimText>
</para>
</levelledPara>
<levelledPara>
<title>Reconstructing ICN entity declarations</title>
<para>Some processing, such as XSL transformations, may remove the DTD and external entity declarations as part of parsing an XML CSDB object. A catalog can be used to restore the necessary external entity declarations afterwards. For example:</para>
<para>
<verbatimText verbatimStyle="vs24">$ xsltproc ex.xsl <object></verbatimText>
</para>
<para>The resulting XML will not include a DTD or the external entity declarations for the ICNs referenced in the object, so it will not be valid according to the S1000D schema:</para>
<para>
<verbatimText verbatimStyle="vs24">$ xsltproc ex.xsl <object> | s1kd-validate
-:49:element graphic: Schemas validity error: Element 'graphic',
attribute 'infoEntityIdent': 'ICN-12345-00001-001-01' is not a valid
value of the atomic type 'xs:ENTITY'.</verbatimText>
</para>
<para>Passing the result to this tool, with a catalog containing all the ICNs used by the project:</para>
<para>
<verbatimText verbatimStyle="vs24">$ xsltproc ex.xsl <object> | s1kd-icncatalog -c <catalog></verbatimText>
</para>
<para>will reconstruct the required external entity declarations in the DTD.</para>
<note>
<notePara>The s1kd-tools will copy the DTD and external entity declarations automatically when performing transformations, so this is only necessary when using more generic XML tools.</notePara>
</note>
</levelledPara>
<levelledPara>
<title>ICN pattern rules</title>
<para>By default, each catalog entry matches a single ICN, but multiple ICNs can be resolved with a single entry by using a pattern rule. An entry with attribute <verbatimText>type="pattern"</verbatimText> specifies a regular expression to use to match ICNs and a template used to construct the resolved URI:</para>
<para>
<verbatimText verbatimStyle="vs11"><![CDATA[<icn
type="pattern"
infoEntityIdent="ICN-(.{5})-(.*)"
uri="graphics/\1/ICN-\1-\2.PNG"
notation="PNG"/>]]></verbatimText>
</para>
<para>The above entry would match a series of CAGE-based ICNs, resolving them to a subfolder of 'graphics' based on their CAGE code. Using this entry, the following input:</para>
<para>
<verbatimText verbatimStyle="vs11"><![CDATA[<!DOCTYPE dmodule [
<!NOTATION PNG SYSTEM PNG>
<!ENTITY ICN-12345-00001-001-01
SYSTEM "ICN-12345-00001-001-01"
NDATA PNG>
<!ENTITY ICN-54321-00001-001-01
SYSTEM "ICN-54321-00001-001-01"
NDATA PNG>
]>]]></verbatimText>
</para>
<para>would be resolved as follows:</para>
<para>
<verbatimText verbatimStyle="vs11"><![CDATA[<!DOCTYPE dmodule [
<!NOTATION PNG SYSTEM PNG>
<!ENTITY ICN-12345-00001-001-01
SYSTEM "graphics/12345/ICN-12345-00001-001-01.PNG"
NDATA PNG>
<!ENTITY ICN-54321-00001-001-01
SYSTEM "graphics/54321/ICN-54321-00001-001-01.PNG"
NDATA PNG>
]>]]></verbatimText>
</para>
<para>The regular expressions must conform to the extended POSIX regular expression syntax. Backreferences \1 through \9 can be used in the URI template to substitute captured groups.</para>
</levelledPara>
</levelledPara>
<levelledPara>
<title>CATALOG SCHEMA</title>
<para>The following describes the schema of an ICN catalog file.</para>
<levelledPara>
<title>Catalog</title>
<para>
<emphasis>Markup element:</emphasis>
<verbatimText><icnCatalog></verbatimText>
</para>
<para>
<emphasis>Attributes:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para>None</para>
</listItem>
</randomList>
</para>
<para>
<emphasis>Child elements:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para>
<verbatimText><notation></verbatimText>
</para>
</listItem>
<listItem>
<para>
<verbatimText><media></verbatimText>
</para>
</listItem>
<listItem>
<para>
<verbatimText><icn></verbatimText>
</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Notation</title>
<para>The element <verbatimText><notation></verbatimText> represents a NOTATION declaration.</para>
<para>
<emphasis>Markup element:</emphasis>
<verbatimText><notation></verbatimText>
</para>
<para>
<emphasis>Attributes:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para><verbatimText>name</verbatimText>, the NDATA name.</para>
</listItem>
<listItem>
<para><verbatimText>publicId</verbatimText>, the optional PUBLIC ID of the notation.</para>
</listItem>
<listItem>
<para><verbatimText>systemId</verbatimText>, the optional SYSTEM ID of the notation.</para>
</listItem>
</randomList>
</para>
<para>
<emphasis>Child elements:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para>None</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Media</title>
<para>The element <verbatimText><media></verbatimText> groups a set of alternative ICN formats for a particular output media type.</para>
<para>
<emphasis>Markup element:</emphasis>
<verbatimText><media></verbatimText>
</para>
<para>
<emphasis>Attributes:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para><verbatimText>name</verbatimText>, the identifier of the output media.</para>
</listItem>
</randomList>
</para>
<para>
<emphasis>Child elements:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para>
<verbatimText><icn></verbatimText>
</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>ICN</title>
<para>The element <verbatimText><icn></verbatimText> maps an ICN to a filename and optionally a notation. When this element occurs as a child of a <verbatimText><media></verbatimText> element, it will be used when that output media is specified with the -m option. When it occurs as a child of <verbatimText><icnCatalog></verbatimText>, it will be used if no media is specified.</para>
<para>
<emphasis>Markup element:</emphasis>
<verbatimText><icn></verbatimText>
</para>
<para>
<emphasis>Attributes:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para><verbatimText>type</verbatimText>, the type of ICN entry, with one of the following values:
<randomList>
<listItem>
<para><verbatimText>"single"</verbatimText> (D) - Specifies a single ICN to resolve.</para>
</listItem>
<listItem>
<para><verbatimText>"pattern"</verbatimText> - Specifies a pattern to resolve one or more ICNs.</para>
</listItem>
</randomList>
</para>
</listItem>
<listItem>
<para><verbatimText>infoEntityIdent</verbatimText>, the ICN, or pattern used to match ICNs.</para>
</listItem>
<listItem>
<para><verbatimText>uri</verbatimText>, the filename the ICN will resolve to.</para>
</listItem>
<listItem>
<para><verbatimText>notation</verbatimText>, a reference to a previously declared <verbatimText><notation></verbatimText> element.</para>
</listItem>
</randomList>
</para>
<para>
<emphasis>Child elements:</emphasis>
</para>
<para>
<randomList>
<listItem>
<para>None</para>
</listItem>
</randomList>
</para>
</levelledPara>
<levelledPara>
<title>Example ICN catalog</title>
<para>
<verbatimText verbatimStyle="vs11"><icnCatalog>
<notation name="jpg" systemId="jpg"/>
<notation name="png" systemId="png"/>
<notation name="svg" systemId="svg"/>
<media name="pdf">
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="ICN-12345-00001-001-01.JPG" notation="jpg"/>
</media>
<media name="web">
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="ICN-12345-00001-001-01.SVG" notation="svg"/>
</media>
<icn infoEntityIdent="ICN-12345-00001-001-01"
uri="ICN-12345-00001-001-01.PNG" notation="png"/>
</icnCatalog></verbatimText>
</para>
</levelledPara>
</levelledPara>
</description>
</content>
</dmodule>
gopher://khzae.net/0/s1kd/s1kd-tools/src/tools/s1kd-icncatalog/doc/DMC-S1KDTOOLS-A-32-00-00-00A-040A-D_EN-CA.XML