Verbatim
Date: 2016-07-03

com.nwalsh.saxon

## Class Verbatim

- java.lang.Object
- - com.nwalsh.saxon.Verbatim

-     public class Verbatim
      extends java.lang.Object

  Saxon extensions supporting DocBook verbatim environments

  $Id: Verbatim.java 7155 2007-07-26 21:34:48Z mzjn $

  Copyright (C) 2000 Norman Walsh.

  This class provides a Saxon implementation of two features that would be impractical to implement directly in XSLT: line numbering and callouts.

  Line Numbering

  The `numberLines` method takes a result tree fragment (assumed to contain the contents of a formatted verbatim element in DocBook: programlisting, screen, address, literallayout, or synopsis) and returns a result tree fragment decorated with line numbers.

  Callouts

  The `insertCallouts` method takes an `areaspec` and a result tree fragment (assumed to contain the contents of a formatted verbatim element in DocBook: programlisting, screen, address, literallayout, or synopsis) and returns a result tree fragment decorated with callouts.

  Change Log:

  1.0

    Initial release.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Verbatim()` Constructor for Verbatim

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static java.lang.String` | `getVariable(com.icl.saxon.Context context, java.lang.String varName)` Find the string value of a stylesheet variable or parameter
    `static com.icl.saxon.expr.NodeSetValue` | `insertCallouts(com.icl.saxon.Context context, org.w3c.dom.NodeList areaspecNodeList, com.icl.saxon.expr.NodeSetValue rtf_ns)` Insert text callouts into a verbatim environment.
    `static com.icl.saxon.expr.NodeSetValue` | `numberLines(com.icl.saxon.Context context, com.icl.saxon.expr.NodeSetValue rtf_ns)` Number lines in a verbatim environment

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Verbatim

          public Verbatim()

      Constructor for Verbatim

      All of the methods are static, so the constructor does nothing.

  - ### Method Detail

    - #### getVariable

          protected static java.lang.String getVariable(com.icl.saxon.Context context,
                                     java.lang.String varName)

      Find the string value of a stylesheet variable or parameter

      Returns the string value of `varName` in the current `context`. Returns the empty string if the variable is not defined.

      Parameters:
        `context` - The current stylesheet context
        `varName` - The name of the variable (without the dollar sign)
      Returns:
        The string value of the variable

    - #### numberLines

          public static com.icl.saxon.expr.NodeSetValue numberLines(com.icl.saxon.Context context,
                                                    com.icl.saxon.expr.NodeSetValue rtf_ns)

      Number lines in a verbatim environment

      The extension function expects the following variables to be available in the calling context: $linenumbering.everyNth, $linenumbering.width, $linenumbering.separator, and $stylesheet.result.type.

      This method adds line numbers to a result tree fragment. Each newline that occurs in a text node is assumed to start a new line. The first line is always numbered, every subsequent 'everyNth' line is numbered (so if everyNth=5, lines 1, 5, 10, 15, etc. will be numbered. If there are fewer than everyNth lines in the environment, every line is numbered.

      Every line number will be right justified in a string 'width' characters long. If the line number of the last line in the environment is too long to fit in the specified width, the width is automatically increased to the smallest value that can hold the number of the last line. (In other words, if you specify the value 2 and attempt to enumerate the lines of an environment that is 100 lines long, the value 3 will automatically be used for every line in the environment.)

      The 'separator' string is inserted between the line number and the original program listing. Lines that aren't numbered are preceded by a 'width' blank string and the separator.

      If inline markup extends across line breaks, markup changes are required. All the open elements are closed before the line break and "reopened" afterwards. The reopened elements will have the same attributes as the originals, except that 'name' and 'id' attributes are not duplicated if the stylesheet.result.type is "html" and 'id' attributes will not be duplicated if the result type is "fo".

      Parameters:
        `context` - The current stylesheet context.
        `rtf_ns` - The result tree fragment of the verbatim environment.
      Returns:
        The modified result tree fragment.

    - #### insertCallouts

          public static com.icl.saxon.expr.NodeSetValue insertCallouts(com.icl.saxon.Context context,
                                                       org.w3c.dom.NodeList areaspecNodeList,
                                                       com.icl.saxon.expr.NodeSetValue rtf_ns)

      Insert text callouts into a verbatim environment.

      This method examines the `areaset` and `area` elements in the supplied `areaspec` and decorates the supplied result tree fragment with appropriate callout markers.

      If a `label` attribute is supplied on an `area`, its content will be used for the label, otherwise the callout number will be used, surrounded by parenthesis. Callout numbers may also be represented as graphics. Callouts are numbered in document order. All of the `area`s in an `areaset` get the same number.

      Only the `linecolumn` and `linerange` units are supported. If no unit is specifed, `linecolumn` is assumed. If only a line is specified, the callout decoration appears in the defaultColumn. Lines will be padded with blanks to reach the necessary column, but callouts that are located beyond the last line of the verbatim environment will be ignored.

      Callouts are inserted before the character at the line/column where they are to occur.

      If graphical callouts are used, and the callout number is less than or equal to the $callout.graphics.number.limit, the following image will be generated for HTML:

           <img src="$callout.graphics.path/999$callout.graphics.ext"
                   alt="conumber">

      If the $stylesheet.result.type is 'fo', the following image will be generated:

           <fo:external-graphic src="$callout.graphics.path/999$callout.graphics.ext"/>

      If the callout number exceeds $callout.graphics.number.limit, the callout will be the callout number surrounded by parenthesis.

      Parameters:
        `context` - The stylesheet context.
        `areaspecNodeList` - The source node set that contains the areaspec.
        `rtf_ns` - The result tree fragment of the verbatim environment.
      Returns:
        The modified result tree fragment.