White Papers/DiType Configuration

From Docs

Jump to: navigation, search

Get PDF

Contents

Configuring DiType

The following sections describe how to configure DiType and its components.

DiType Cliser Configuration

Cliser configuration parameters are the following:

data port - DITYPE_DATA_PORT environment variable with default value 19790

http port - DITYPE_HTTP_PORT environment variable with default value 19800

The values of these variables that are set by user or the default values should be opened in firewall.

DiType Configuration

DiType configuration is a configuration file. Cliser receives the name of that file on startup. After the installation DiType configuration file 'ditype.conf' included in distributive is located in DITYPE_FRAMEWORK_ROOT\Framework\Configuration

DiType RelaxNG configuration (rnc) scheme is presented in Appendix A.

Configuration file is an XML file with root element 'ditype'. It has two attributes:

root - an absolute URL to DiType root directory[1]

license - a relative URL[1],[2] to DiType license file[3]

DiType configuration file 'ditype.conf' specifies the XSL-FO and XEPOUT validation schemas. It also specifies the spaces (such as lambda and pi) and services (such as the graphic-server and the transformer) that will be used and any relevant options. To achieve maximum throughput on architectures with multiple CPUs or CPU cores, specify as many engine elements as the number of cores available, each such element with unique port.

The ditype-conf.rnc schema validates this file.

DiType options

xsl-schema - a relative URL[2] to xsl-fo document validation rnc scheme[1], default value - lib/schema/xsl-1.1/main.rnc

xepout-schema - a relative URL[2] to xepout (xep intermediate format) document validation rnc scheme[1], default value - lib/schema/xepout.rnc

debug - switch debug mode, possible values - true|false, default - false.

Configuring spaces

A space is being configured by an xml element <space>:

<space name="name_of_the_space">

See Appendix A for schemes.

Attributes

name - name of the space. Don't change this value.

type - process|thread. Don't change this value.

command - anyURL - used when type=process. Don't change this value.

port - integer. Space XML-RPC server is being launched on this port[4].

The options of the space are descendants of <space> element.

lambda space options

<space name="lambda" port="<PORT>" type="process"
command="lambda">

The following parameters for DiType's space 'lambda' affect the performance:

log-queue-size - buffer size to store log messages before the sending to clients; the default value is 16. The lesser value parameter has the more often the client gets log messages from formatter, and greater value of parameter improves the performance.

mark-and-sweep-rate - the frequency of calls the garbage collector in the formatter; the optimal value of the parameter is the maximum number of renderings that does not need memory swapping out, it depends on the average size of documents and the system RAM. The default is 5.

log-thread-priority - the priority of the stream which serves processing of the system messages and document procession messages, type: integer, default value: -100 (for comparison normal priority is 0);

log-queue-size - buffer size, type: integer, default value: 16;

debug-server-port - port nubmer[4], has value if DiType is launched in debug mode, type: integer, default value: 12345;

pi space options

pi space does not have options.

Configuring services

A service should be configured with <service> element:

<service name="the_service_name" [configuration="anyURL"]> (see Appendix A for details).

Attributes

name - the service name. Don't change this value.

configuration - some services may include this attribute - URL[1],[2] to the configuration file of the service.


XEP

See Appendix B for details.

FONT-SERVER

See Appendix C for details.

PS

drop-unused-destination - specify whether named destinations are created for objects not referenced within the document;

unicode-annotations - Enable or disable use of Unicode to represent annotations strings, such as bookmark text, and document info;

initial-view-mode - document may contain definition of default view mode which is activated by the viewer upon rendering and viewing the file. This option allows specifying this mode;

initial-zoom - specify the magnification factor to be activated when the file is first opened in the viewer;

clone-eps - specify whether EPS graphics are included in the PostScript output using the forms mechanism, or by pasting their contents at each occurrence.

Some options are in development state and will be available soon:

compress-ttf-fonts

compress-t1-fonts

PDF

gs-executable - path to ghostscript executable;

gs-external-command-line - additional command-line options for ghostscript;

linearize - check to linearize (or optimize for the Web) the PDF output;

compress - check to compress content streams in PDF using Flate algorithm;

ownerpassword - set an owner password for the PDF document. Owner passwords give the owner full control over the PDF document.

userpassword - set a user password for the PDF document. Holders of user passwords are subject to access restrictions specified in the userprivileges option.

userprivileges - set the privilege for users accessing the resulting document with user password.

pdf-version - switch PDF version of output documet. Supported versions are 1.3, 1.4 and 1.5 (by default, 1.4).

SVG

SVG service does not have any supported options at present but is supposed to have some in future.

LOGGER

Logger does not have any supported options at present but is supposed to have some in future.

FILE-SERVER

temporary-directory - URL[1],[2] to a temporary directory. DiType process should have the write access to this directory.

RESOURCE-PROXY

The resource-proxy service includes document-resources-limit and maximum-resource-size options.

The document-resources-limit option limits a total size of all external resource per document. External resource is non-relative and non-local (not a 'file:///') resources in that case. The possible values are integers and look like the following: xxx - xxx bytes, xxxk - xxx KB, xxxМ - xxx MB, xxxG - xxx GB

The maximum-resource-size option limits a maximum allowed resourcessize.

GRAPHIC-SERVER

404-url - URL[1],[2] to the picture to be used to replace missing/invalide images.

PREPROCESSOR

indent-output - pretty-print preprocessing result properly indenting nested elements.

abbreviate-attributes - replace attribute names by short abbreviations.

remove-defaults - don't write attributes with default values.

px-length - length of 1px unit.

These are internal options, excluding, maybe px-length that may become a common DiType option.

REGISTRY

No options for registry.

TRANSFORMER

arx - URL[1],[2] to arx executable;

arx-configuration - URL[1],[2] to arx configuration file (arx.conf)

Element document can have the following attributes:

type - document input type

result-type - document output type (result of transformation)

transformer - a transformer to use; possible values:

  * XSLT - XSLT transformer
  * identity - no transformation, output format is the same as input format
  * external - external transformer
  * none - input type is recognized but no transformation for that type of document is supported.

transformation - path to an XSL stylesheet for XSLT transformation or an external program to use in case of external transformer. Not specified if the option transformer has value identity or none.

Transformer uses arx to define the type of input document.

catalog - path to XML catalog. Used for XML catalog resolution.

Configuring arx

Arx configuration file arx.conf contains the list of grammars that that can be processed by DiType and the rules for arx to recognize documents that use one of the listed grammars. It is written in RelaxNG syntax. Additional documentation about arx can be found at http://davidashen.net/rnv.html .

---

  1. 1.0 1.1 1.2 1.3 1.4 1.5 1.6 1.7 1.8 URL to the resource that is included in base distribution. Do not change this value if you are not sure what to do.
  2. 2.0 2.1 2.2 2.3 2.4 2.5 2.6 2.7 Relative URL is being joined with DiType Root URL.
  3. If specified during the installation, the license file will be located in its right place, otherwise user should manually copy the file to the directory shown by (root, license) pair or change the 'license' attribute value to license file URL.
  4. 4.0 4.1 Indicated port should be opened on firewall to connect from 'localhost'.

Appendix A - DiType configuration file scheme

default namespace = "http://renderx.com/DiType/ditype-conf"

start = ditype

ditype = element ditype {
	attribute root {xsd:anyURI},
	attribute license {xsd:anyURI},
	option*,
	engine+,
	space+
}

engine = element engine {
        host?,
	port
}

space = element space {
	name,
	(process | thread ),
	port?,
	command?,
	option*,
	( element service {name, attribute configuration {xsd:anyURI}?, option*})*
}

process = attribute type { xsd:token { pattern = "process" } }
thread = attribute type {xsd:token { pattern = "thread" } }
command = attribute command { xsd:anyURI }

name = attribute name {xsd:token}

host = attribute host {xsd:string}
port = attribute port {xsd:integer}

option = element option {
	attribute name {xsd:token},
	attribute value {xsd:string}
}

Appendix B - XEP configuration file scheme

 
start = element xep {
xml-base,
 
(element option {           # used to override default options, for internal use
attribute name {text},      # option name, corresponds to the special variable names sans
asterisks
attribute value {text}      # option value, must be Common-Lisp-READable expression of compatible
type
}*
&
element hyphenation-rules { # tables for the Liang hyphenator
xml-base,
 
element hyphenation {
xml-base,
attribute language {text},  # a space-separated list of language codes, corresponding to those
specified in XSL language attribute
attribute table {text},     # URL of the hyphenation table (in a subset of TeX hyphenation table
syntax, see XEP4 documentation for limitations)
attribute code-list {text}? # URL of the code translation table, <hyphenation-table-character-
code> <unicode codepoint>: required since many national hyphenation tables in TeX are in 8-bit
encodings
}*
}?)
}
 
xml-base = attribute xml:base {text}?

Appendix C - FONT-SERVER configuration file scheme font-server.conf.rnc

 
default namespace = "http://www.renderx.com/XEP/config"
start = FontConfig
 
# Datatypes
Boolean = xsd:NMTOKEN "false" | xsd:NMTOKEN "true"
 
# Common attributes
 
FontFamilyName = xsd:string
 
FontFamilyRef = attribute name { FontFamilyName }
 
FontName = attribute name { xsd:string }
 
Embed = attribute embed { Boolean }
 
Subset = attribute subset { Boolean }
 
Type1FontDataAttributes = ( attribute afm {text}?,
                            ( attribute pfa {text} | attribute pfb {text})?
                          )
 
# XEP supports TrueType fonts (*.ttf) and TrueType font collections (*.ttc).
# To access a font from a TrueType Collection file, it is necessary to specify
# subfont number in a "subfont" attribute.
 
OpenTypeFontDataAttributes = ( attribute ttf {text} |
                               attribute otf {text} |
                               ( attribute ttc {text}, attribute subfont {text} )
                             )
 
InheritableFontAttribs = Embed?, Subset?
 
XmlBase = attribute xml:base {text}?
 
HRef = attribute href {text}?
 
# A set of ligature characters is specified in the ligatures attribute of the font element,
# as a space- or comma -separated list of ligature characters.
# The characters must be a Unicode ligature codepoints.   fi
Ligatures = attribute ligatures {
     xsd:string { pattern = "[^\s](\s+[^\s])*" } |
     xsd:string { pattern = "[^,](,[^,])*" } }
#     xsd:string { pattern = "&#x[0-9a-fA-F]{1,4};(\s+&#x[0-9a-fA-F]{1,4};)*" } |
#     xsd:string { pattern = "&#x[0-9a-fA-F]{1,4};(,&#x[0-9a-fA-F]{1,4};)*" } }
 
FontConfig = element fonts {
        attribute default-family { FontFamilyName },
        attribute adobe-glyph-list {text}?,
    InheritableFontAttribs,
        XmlBase?,
        HRef?,
        ( FontGroup | FontFamily )+,
        FontAlias*,
        GenericFontFamily*
}
 
# Several font families can be wrapped into a font-group container element. Groups can be nested,
forming
# complex font hierarchies. This element does not affect font mapping, and serves only for
logical grouping
# of font families. In particular, it is often convenient to use it as a host for xml:base
property, to specify
# a common base directory for a group of font families that form a package. Another suggested use
of font-group
# is for remoting: contents of the font group can be placed into a separate file, and reused
across
# multiple font configurations.
# The only attribute specific to font-group is label: it assigns a name to the group. The name
serves only
# for record keeping: no constraints are imposed on it.
 
FontGroup = element font-group {
    attribute label { xsd:string }?,
        InheritableFontAttribs,
        XmlBase,
        HRef?,
        ( FontGroup | ( FontFamily, FontAlias*) )+
}
 
# All data pertinent to one font family is contained in a <font-family> element.
# It bears a required name attribute that identifies the font family. Family names should
# be unique within the configuration file.
# Inside family descriptor, there are one or more entries for individual fonts that belong
# to the family. A font entry is specified by a <font> element.
 
FontFamily = element font-family {
         FontFamilyRef,
     InheritableFontAttribs,
     Ligatures?,
         XmlBase,
         Font+
}
 
# A font entry is specified by a <font> element. It has attributes to specify features of the font
# within the family, such as language, weight, style, and variant.
# Actual characteristics of the font are specified by a mandatory <font-data> element,
# located inside the <font>. Its attributes specify locations of various auxiliary files
# used by the formatter to retrieve font metric data and outlines, and set additional
# parameters that may be needed to interpret font data properly.
 
# Note: "name" attribute in <font> element seems to be redundant and outdated.
# It is allowed only for backward compartibility with XEP 4 configuration files.
Font = element font {
        FontName?,
    attribute language {xsd:string}?,
        attribute weight { xsd:int { minInclusive = "100" maxInclusive = "900" } |
                           xsd:NMTOKEN "normal" | xsd:NMTOKEN "bold" }?,
        attribute style { xsd:NMTOKEN "normal" | xsd:NMTOKEN "italic" |
                          xsd:NMTOKEN "oblique" | xsd:NMTOKEN "backslant" }?,
        attribute variant { xsd:NMTOKEN "normal" | xsd:NMTOKEN "small-caps" }?,
    Ligatures?,
    InheritableFontAttribs,
        XmlBase,
        FontData,
        Transform?
}
 
FontData = element font-data {
        ( Type1FontDataAttributes | OpenTypeFontDataAttributes ),
    attribute glyph-list {text}?,
    XmlBase
}
 
Transform = element transform {
    attribute slant-angle {xsd:token}
}
 
# XEP uses font aliases to provide alternate names for font families, and group several
# families into one logical family. A font alias is defined by a <font-alias> element.
# The element has two attributes, both required: "name" is the name of the logical font family,
# and "value" is a comma-separated list of font family names to which it should resolve.
# The list may contain a single font family; in this case, the alias merely provides an
# alternate name for it.
 
FontAlias = element font-alias {
        FontFamilyRef,
        attribute value { xsd:string { pattern = "[^,]+(,[^,]+)*" } }
}
 
GenericFontFamily = element generic-font-family {
    attribute name {FontFamilyName},
    element font-family-reference {
        attribute name {FontFamilyName}
    }*
}
Personal tools