se/SE/stuff/dita-ot-2.3.3/docsrc/user-guide/extended-functionality.dita

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.-->

<reference id="extended-functionality">

  <title>Extended functionality</title>

  <shortdesc>DITA-OT provides additional code reference processing support beyond that which is mandated by the DITA
    specification. These extensions can be used to define character encodings or line ranges for use in code
    blocks.</shortdesc>

  <reference id="code-reference">
    <title>Code reference processing</title>
    <refbody>
      <section id="coderef-charset">
        <title>Character set definition</title>
        <p>DITA-OT supports defining the code reference target file encoding using the <xmlatt>format</xmlatt>
          attribute. The supported format is:</p>
        <codeblock>format (";" space* "charset=" charset)?</codeblock>
        <p>If a character set is not defined, the system default character set will be used. If the character set is not
          recognized or supported, the <msgnum>DOTJ052E</msgnum> error is thrown and the system default character set is
          used as a fall-back.</p>
      </section>
      <example>
        <codeblock>&lt;coderef href="unicode.txt" format="txt; charset=UTF-8"/></codeblock>
      </example>
      <section>
        <title>Line range extraction</title>
        <p>Code references can be limited to extract only a specified line range by defining the
            <codeph>line-range</codeph> pointer in the URI fragment. The format is:</p>
        <codeblock>uri ("#line-range(" start ("," end)? ")" )?</codeblock>
        <p>Start and end line numbers start from 1 and are inclusive. If the end range is omitted, the range ends on the
          last line of the file.</p>
      </section>
      <example>
        <codeblock>&lt;coderef href="Parser.scala#line-range(5, 10)" format="scala"/></codeblock>
        <p>Only lines from 5 to 10 will be included in the output.</p>
      </example>
      <section>
        <title>RFC 5147</title>
        <p>DITA-OT implements line position and range from <xref keyref="rfc5147"/>. The format for line range is:</p>
        <codeblock>uri ("#line=" start? "," end? )?</codeblock>
        <p>Start and end line numbers start from 0 and are inclusive and exclusive, respectively. If the start range is
          omitted, the range starts from the first line; if the end range is omitted, the range ends on the last line of
          the file. The format for line position is:</p>
        <codeblock>uri ("#line=" position )?</codeblock>
        <p>Position line number starts from 0.</p>
      </section>
      <example>
        <codeblock>&lt;coderef href="Parser.scala#line=4,10" format="scala"/></codeblock>
        <p>Only lines from 5 to 10 will be included in the output.</p>
      </example>
    </refbody>
  </reference>
</reference>