## 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,v 1.6 2000/11/14 19:31:13 ndw Exp $

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` family of functions 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` family of functions 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
`Verbatim()` Constructor for Verbatim

Method Summary
`static com.icl.saxon.expr.FragmentValue` `insertCallouts(com.icl.saxon.expr.NodeSetIntent areaspecNodeSet, com.icl.saxon.expr.FragmentValue saxonRTF, int defaultColumn)` Insert text callouts into a verbatim environment.
`static com.icl.saxon.expr.FragmentValue` `insertCallouts(com.icl.saxon.expr.NodeSetIntent areaspecNodeSet, com.icl.saxon.expr.FragmentValue saxonRTF, int defaultColumn, java.lang.String gPath, java.lang.String gExt, int gMax, boolean useFO)` Insert graphical callouts into a verbatim environment.
`static com.icl.saxon.expr.FragmentValue` `numberLines(com.icl.saxon.expr.FragmentValue saxonRTF)` Number lines in a verbatim environment using default values for modulus, width and separator.
`static com.icl.saxon.expr.FragmentValue` `numberLines(com.icl.saxon.expr.FragmentValue saxonRTF, int saxonMod)` Number lines in a verbatim environment using default values for width and separator.
`static com.icl.saxon.expr.FragmentValue` `numberLines(com.icl.saxon.expr.FragmentValue saxonRTF, int saxonMod, int saxonWidth)` Number lines in a verbatim environment using the default value separator.
`static com.icl.saxon.expr.FragmentValue` `numberLines(com.icl.saxon.expr.FragmentValue saxonRTF, int saxonMod, int saxonWidth, java.lang.String saxonSep)` Number lines in a verbatim environment.

Methods inherited from class java.lang.Object
`equals, 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

### numberLines

    public static com.icl.saxon.expr.FragmentValue numberLines(com.icl.saxon.expr.FragmentValue saxonRTF)

  Number lines in a verbatim environment using default values for modulus, width and separator.

  The default modulus is 1, the default width is 5, and the default separator is a space.

  Parameters:
    `saxonRTF` - The result tree fragment of the verbatim environment.
  Returns:
    The modified result tree fragment.

### numberLines

    public static com.icl.saxon.expr.FragmentValue numberLines(com.icl.saxon.expr.FragmentValue saxonRTF,
                                                               int saxonMod)

  Number lines in a verbatim environment using default values for width and separator.

  The default width is 5, and the default separator is a space.

  Parameters:
    `saxonRTF` - The result tree fragment of the verbatim environment.
    `saxonMod` - The modulus to use for line numbering.
  Returns:
    The modified result tree fragment.

### numberLines

    public static com.icl.saxon.expr.FragmentValue numberLines(com.icl.saxon.expr.FragmentValue saxonRTF,
                                                               int saxonMod,
                                                               int saxonWidth)

  Number lines in a verbatim environment using the default value separator.

  The default separator is a space.

  Parameters:
    `saxonRTF` - The result tree fragment of the verbatim environment.
    `saxonMod` - The modulus to use for line numbering.
    `saxonWidth` - The width of line numbers.
  Returns:
    The modified result tree fragment.

### numberLines

    public static com.icl.saxon.expr.FragmentValue numberLines(com.icl.saxon.expr.FragmentValue saxonRTF,
                                                               int saxonMod,
                                                               int saxonWidth,
                                                               java.lang.String saxonSep)

  Number lines in a verbatim environment.

  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 saxonMod line is numbered (so if saxonMod=5, lines 1, 5, 10, 15, etc. will be numbered. If there are fewer than saxonMod lines in the environment, every line is numbered.

  Every line number will be right justified in a string saxonWidth 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 saxonSep string is inserted between the line number and the original program listing. Lines that aren't numbered are preceded by a saxonWidth 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.

  Parameters:
    `saxonRTF` - The result tree fragment of the verbatim environment.
    `saxonMod` - The modulus to use for line numbering.
    `saxonWidth` - The width of line numbers.
    `saxonSep` - The separator between line numbers and lines.
  Returns:
    The modified result tree fragment.

### insertCallouts

    public static com.icl.saxon.expr.FragmentValue insertCallouts(com.icl.saxon.expr.NodeSetIntent areaspecNodeSet,
                                                                  com.icl.saxon.expr.FragmentValue saxonRTF,
                                                                  int defaultColumn)

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

  Parameters:
    `areaspecNodeSet` - The source node set that contains the areaspec.
    `saxonRTF` - The result tree fragment of the verbatim environment.
    `defaultColumn` - The column for callouts that specify only a line.
  Returns:
    The modified result tree fragment.

### insertCallouts

    public static com.icl.saxon.expr.FragmentValue insertCallouts(com.icl.saxon.expr.NodeSetIntent areaspecNodeSet,
                                                                  com.icl.saxon.expr.FragmentValue saxonRTF,
                                                                  int defaultColumn,
                                                                  java.lang.String gPath,
                                                                  java.lang.String gExt,
                                                                  int gMax,
                                                                  boolean useFO)

  Insert graphical 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. Callouts are numbered in document order. All of the `area`s in an `areaset` get the same number.

  If the callout number is not greater than `gMax`, the callout generated will be:

       <img src="$gPath/conumber$gExt" alt="conumber">

  Otherwise, it will be the callout number surrounded by parenthesis.

  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.

  Parameters:
    `areaspecNodeSet` - The source node set that contains the areaspec.
    `saxonRTF` - The result tree fragment of the verbatim environment.
    `defaultColumn` - The column for callouts that specify only a line.
    `gPath` - The path to use for callout graphics.
    `gExt` - The extension to use for callout graphics.
    `gMax` - The largest number that can be represented as a graphic.
    `useFO` - Should fo:external-graphics be produced, as opposed to HTML imgs. This is bogus, the extension should figure it out, but I haven't figured out how to do that yet.
  Returns:
    The modified result tree fragment.