<?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_4-2/xml_schema_flat/descript.xsd">
  <identAndStatusSection>
    <dmAddress>
      <dmIdent>
        <dmCode modelIdentCode="XMLUTILS" systemDiffCode="A" systemCode="03" subSystemCode="0" subSubSystemCode="0" assyCode="00" disassyCode="00" disassyCodeVariant="A" infoCode="040" infoCodeVariant="A" itemLocationCode="D"/>
        <language languageIsoCode="en" countryIsoCode="CA"/>
        <issueInfo issueNumber="010" inWork="01"/>
      </dmIdent>
      <dmAddressItems>
        <issueDate year="2020" month="07" day="07"/>
        <dmTitle>
          <techName>xml-highlight(1) | xml-utils</techName>
        </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="S1000D" systemDiffCode="F" 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 id="rfu-xml-catalog" updateHighlight="1" updateReasonType="urt02">
        <simplePara>Add --xml-catalog parser option.</simplePara>
      </reasonForUpdate>
    </dmStatus>
  </identAndStatusSection>
  <content>
    <description>
      <levelledPara>
        <title>NAME</title>
        <para>xml-highlight - Highlight syntax in XML documents</para>
      </levelledPara>
      <levelledPara>
        <title>SYNOPSIS</title>
        <para>
          <verbatimText verbatimStyle="vs24">xml-highlight [options] [<document>...]</verbatimText>
        </para>
      </levelledPara>
      <levelledPara>
        <title>DESCRIPTION</title>
        <para>The <emphasis>xml-highlight</emphasis> tool adds syntax highlighting to program listings in an XML document. By default this is accomplished by wrapping detected syntax in XSL-FO inline elements with the proper namespace to allow a stylesheet to pass them through to the final FO processor. The actual elements used can be customized, however.</para>
        <para>To enable highlighting on text in an element, include the processing instruction <verbatimText><?language ...?></verbatimText> in the element, where <verbatimText>...</verbatimText> is the name of the language.</para>
      </levelledPara>
      <levelledPara>
        <title>OPTIONS</title>
        <para>
          <definitionList>
            <definitionListItem>
              <listItemTerm>-c, --classes <classes></listItemTerm>
              <listItemDefinition>
                <para>Use a custom class definitions file.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-f, --overwrite</listItemTerm>
              <listItemDefinition>
                <para>Overwrite input XML file(s) instead of outputting to stdout.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-h, -?, --help</listItemTerm>
              <listItemDefinition>
                <para>Show help/usage message.</para>
              </listItemDefinition>
            </definitionListItem>
            <definitionListItem>
              <listItemTerm>-s, --syntax <syntax></listItemTerm>
              <listItemDefinition>
                <para>Use a custom syntax definitions file.</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>--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>
      <levelledPara>
        <title>CLASS FILE FORMAT</title>
        <para>The following describes the format of the custom class file specified with -c.</para>
        <levelledPara>
          <title>Classes</title>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">classes</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 verbatimStyle="vs12">class</verbatimText>></para>
              </listItem>
            </randomList>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Class</title>
          <para>Represents a type of syntax and how it should be highlighted. This element can also occur within the <verbatimText verbatimStyle="vs12">syntax</verbatimText> element or within a particular <verbatimText verbatimStyle="vs12">language</verbatimText> element, in which case it is specific to that language.</para>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">class</verbatimText>></para>
          <para>
            <emphasis>Attributes:</emphasis>
          </para>
          <para>
            <randomList>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">id</verbatimText>, the identifier of the class.</para>
              </listItem>
            </randomList>
          </para>
          <para>
            <emphasis>Child elements:</emphasis>
          </para>
          <para>The element <verbatimText verbatimStyle="vs12">class</verbatimText> contains one child element of any kind, which any matching syntax will be wrapped in to.</para>
        </levelledPara>
        <levelledPara>
          <title>Example custom classes file</title>
          <para>
            <verbatimText verbatimStyle="vs11"><classes xmlns:fo="http://www.w3.org/1999/XSL/Format">
<class id="type">
<fo:inline color="green"/>
</class>
<class id="control">
<fo:inline color="blue"/>
</class>
<class id="string">
<fo:inline color="red"/>
</class>
<class id="comment">
<fo:inline color="pink"/>
</class>
</classes></verbatimText>
          </para>
        </levelledPara>
      </levelledPara>
      <levelledPara>
        <title>SYNTAX FILE FORMAT</title>
        <para>The following describes the format of the custom syntax file specified with -s.</para>
        <levelledPara>
          <title>Syntax</title>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">syntax</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 verbatimStyle="vs12">class</verbatimText>
                </para>
              </listItem>
              <listItem>
                <para>
                  <verbatimText verbatimStyle="vs12">language</verbatimText>
                </para>
              </listItem>
            </randomList>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Language</title>
          <para>Describes the syntax of a particular language.</para>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">language</verbatimText>></para>
          <para>
            <emphasis>Attributes:</emphasis>
          </para>
          <para>
            <randomList>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">name</verbatimText>, the identifier of the language.</para>
              </listItem>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">caseInsensitive</verbatimText>, indicates whether keywords are case-insensitive in this language, with one of the following values:</para>
                <para>
                  <randomList>
                    <listItem>
                      <para><verbatimText verbatimStyle="vs14">"no"</verbatimText> - Keywords are case-sensitive (default)</para>
                    </listItem>
                    <listItem>
                      <para><verbatimText verbatimStyle="vs14">"yes"</verbatimText> - Keywords are case-insensitive</para>
                    </listItem>
                  </randomList>
                </para>
              </listItem>
            </randomList>
          </para>
          <para>
            <emphasis>Child elements:</emphasis>
          </para>
          <para>
            <randomList>
              <listItem>
                <para><<verbatimText verbatimStyle="vs12">class</verbatimText>></para>
              </listItem>
              <listItem>
                <para><<verbatimText verbatimStyle="vs12">area</verbatimText>></para>
              </listItem>
              <listItem>
                <para><<verbatimText verbatimStyle="vs12">keyword</verbatimText>></para>
              </listItem>
            </randomList>
          </para>
        </levelledPara>
        <levelledPara>
          <title>Area</title>
          <para>Matches a section of delimited text, such as strings, comments, etc.</para>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">area</verbatimText>></para>
          <para>
            <emphasis>Attributes:</emphasis>
          </para>
          <para>
            <randomList>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">start</verbatimText>, the opening delimiter.</para>
              </listItem>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">end</verbatimText>, the closing delimiter.</para>
              </listItem>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">class</verbatimText>, reference to the <verbatimText verbatimStyle="vs12">class</verbatimText> element to use for this area.</para>
              </listItem>
            </randomList>
          </para>
          <para>
            <emphasis>Child elements:</emphasis>
          </para>
          <para>If attribute <verbatimText verbatimStyle="vs13">class</verbatimText> is not used, this element can contain one element of any kind, in which the text matching the area will be wrapped.</para>
        </levelledPara>
        <levelledPara>
          <title>Keyword</title>
          <para>Matches a particular keyword.</para>
          <para><emphasis>Markup element:</emphasis> <<verbatimText verbatimStyle="vs12">keyword</verbatimText>></para>
          <para>
            <emphasis>Attributes:</emphasis>
          </para>
          <para>
            <randomList>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">match</verbatimText>, the keyword to match.</para>
              </listItem>
              <listItem>
                <para><verbatimText verbatimStyle="vs13">class</verbatimText>, reference to the <verbatimText verbatimStyle="vs12">class</verbatimText> element to use for this keyword.</para>
              </listItem>
            </randomList>
          </para>
          <para>
            <emphasis>Child elements:</emphasis>
          </para>
          <para>If attribute <verbatimText verbatimStyle="vs13">class</verbatimText> is not used, this element can contain one element of any kind, in which the text matching the keyword will be wrapped.</para>
        </levelledPara>
        <levelledPara>
          <title>Example custom syntax file</title>
          <para>
            <verbatimText verbatimStyle="vs11"><syntax>
<language name="c">
<area start="&quot;" end="&quot;" class="string"/>
<area start="/*" end="*/" class="comment"/>
<keyword match="if" class="control"/>
<keyword match="else" class="control"/>
<keyword match="int" class="type"/>
<keyword match="char" class="type"/>
</language>
</syntax></verbatimText>
          </para>
        </levelledPara>
      </levelledPara>
      <levelledPara>
        <title>BUILT-IN LANGUAGES</title>
        <para>The following is a list of language syntaxes currently built-in to the tool:</para>
        <para>
          <randomList>
            <listItem>
              <para>c</para>
            </listItem>
            <listItem>
              <para>csharp</para>
            </listItem>
            <listItem>
              <para>go</para>
            </listItem>
            <listItem>
              <para>java</para>
            </listItem>
            <listItem>
              <para>javascript</para>
            </listItem>
            <listItem>
              <para>pascal</para>
            </listItem>
            <listItem>
              <para>python</para>
            </listItem>
            <listItem>
              <para>ruby</para>
            </listItem>
            <listItem>
              <para>rust</para>
            </listItem>
            <listItem>
              <para>sh</para>
            </listItem>
            <listItem>
              <para>sql</para>
            </listItem>
            <listItem>
              <para>xml</para>
            </listItem>
            <listItem>
              <para>xsl</para>
            </listItem>
          </randomList>
        </para>
      </levelledPara>
    </description>
  </content>
</dmodule>