se/SE/schema/WPS_Functions/dita-ot/dita-ot-3.0.4/docsrc/reference/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 file for applicable license.  -->

<reference id="code-reference">

  <title>Extended code reference processing</title>

  <titlealts>
    <navtitle>Coderef extensions</navtitle>
  </titlealts>

  <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>

  <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 also supports the line position and range syntax 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>
    <section>
      <title>Line range by content</title>
      <p>Instead of specifying line numbers, you can also select lines to include in the code reference by specifying
        keywords (or “<term>tokens</term>”) that appear in the referenced file.</p>
      <div id="coderef-by-content">
        <p>DITA-OT supports the <codeph>token</codeph> pointer in the URI fragment to extract a line range based on the
          file content. The format for referencing a range of lines by content is:</p>
        <codeblock>uri ("#token=" start? ("," end)? )?</codeblock>
        <p>Lines identified using start and end tokens are exclusive: the lines that contain the start token and end
          token will be not be included. If the start token is omitted, the range starts from the first line in the
          file; if the end token is omitted, the range ends on the last line of the file. </p>
      </div>
    </section>
    <example>
      <p>Given a Haskell source file named <filepath>fact.hs</filepath> with the following content,</p>
      <codeblock><coderef href="../resources/fact.hs"/></codeblock>
      <p>a range of lines can be referenced as:</p>
      <codeblock>&lt;coderef href="fact.hs#token=START-FACT,END-FACT"/></codeblock>
      <p>to include the range of lines that follows the <codeph>START-FACT</codeph> token, up to (but not including) the
        line that contains the <codeph>END-FACT</codeph> token. The resulting <xmlelement>codeblock</xmlelement> would
        contain the following lines:</p>
      <codeblock><coderef href="../resources/fact.hs#token=START-FACT,END-FACT"/></codeblock>
      <note type="tip" id="coderef-by-content-tip">This approach can be used to reference code samples that are
        frequently edited. In these cases, referencing line ranges by line number can be error-prone, as the target line
        range for the reference may shift if preceding lines are added or removed. Specifying ranges by line content
        makes references more robust, as long as the <codeph>token</codeph> keywords are preserved when the referenced
        resource is modified.</note></example>
  </refbody>
</reference>