DiType User Guide/Configuring DiType

From Docs

Jump to: navigation, search

< DiType User Guide

This section describes how to configure DiType and the configuration files included with the DiType installation.

Configuring CLISER

CLISER is an internal protocol through which applications communicate with the DiType core. The two CLISER configuration parameters are described in the following table:

CLISER Configuration Parameters
Parameter Description
data port The DITYPE_DATA_PORT environment variable determines the port through which data is communicated between applications and the DiType core. The default value is 19790.
http port The DITYPE_HTTP_PORT environment variable determines the port through which http communications take place. The default value is 19800.

Note: You must open the selected ports, either user-defined or default value, in the firewall.


DiType Configuration Files

The DiType installation contains several configuration files that can be changed by the user. After changing any of the files, it is necessary for the file to be validated. The validation is performed using one of the build-in RelaxNG schemas.

  • ditype.conf - This is the main configuration file for the DiType engine. It specifies the URL of the DiType root directory and license file, and 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.

    DiType configuration specifies the following services: XEP, font-server, PS, PDF, preprocessor, transformer, logger, file-server, resource-proxy, graphic-server and registry. It is enough to specify configuration attribute to set XEP and font-server services. In both cases the attribute value is relative URL to xep.conf and font-server.conf files.

    Resource-proxy service options are not indicated in DiType configuration by default. Configuration of resource-proxy service is only necessary for resource uniform access and caching the resource during formatting. The service configuration includes document-resources-limit, maximum-resource-size and cache-local-resources options. The document-resources-limit option limits a total size of all external resources per document. External resource is a non-relative and non-local (not a 'file:///') resource. The possible values are have the following look: xxx - xxx bytes, xxxk - xxx KB, xxxМ - xxx MB, xxxG - xxx GB, where xxx is an integer. The maximum-resource-size option limits a maximum allowed resource size. The cache-local-resources option allows to cache local resources.

    There are no options for registry, logger and SVG services.

    To confugure PS service you can specify the following options:
    • 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.

    PDF service includes the following options:
    • gs-executable - indicate the path to GhostScript executable;
    • gs-external-command-line - additional command-line option 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.

    Dispite drop-unused-destination, unicode-annotations, initial-view-mode and initial-zoom options are specified in ps service, they also exert influence on PDF output.
    PDF and PostScript options can also be passed as Processing Instructions - The processing instructions are used to specify information that does not affect formatting and is safely ignored by the XSL-FO processors.
    Each processing instruction begins with a prefix that identifies the output generator to which the instruction is addressed. For PDF, the prefix is <?ditype-pdf-*> and for PostScript, the prefix is <?ditype-ps-*>.
    Instructions that pertain to an entire document should be placed at the top of the document, before or right after the <fo:root> start tag.

    <?ditype-ps-drop-unused-destinations value?>

    This processing instruction specifies whether named destinations are created for objects not referenced within the document. In PostScript, the information is coded in pdfmark operators and used for further conversion to PDF. The following are possible values:

    • true - Named destinations are created only for objects used as targets in internal-destination attributes.
    • false - Named destinations are created for all objects that have an id attribute.

      Default: true

    <?ditype-ps-unicode-annotations value?>

    This processing instruction enables or disables the use of Unicode to represent PDF annotations strings, such as bookmark text and document info. In PostScript, the information is coded in pdfmark operators and used for further conversion to PDF. The following are possible values:

    • true - Enable use of 16-bit Unicode to represent annotation strings. In this mode, Ditype uses 8-bit PDF Encoding for strings that can be represented in AdobeStandard character set and 16-bit Unicode for strings containing characters not included in AdobeStandard.
    • false - Unicode is not used. Annotations are always represented in 8-bit PDF Encoding; characters not included in the AdobeStandard set are replaced by bullet symbols. This option may be used to enforce compatibility with older versions of PDF software that do not support Unicode, such as Adobe Acrobat 3.0.

      Default: false

    <?ditype-ps-initial-zoom value?>

    This processing instruction specifies the magnification factor to be activated when the file is first opened in the PostScript and PDF viewers.The following are possible values:

    • auto - Page scaling is not specified.
    • fit - The page is scaled to fit completely into the view port.
    • fit-width - The page is scaled so that its width matches the width of the view port.
    • fit-height - The page is scaled so that its height matches the height of the view port.
    • number or percentage - The page is scaled by the number or percentage specified in the enabled box.

      Default: auto

    <?ditype-ps-initial-view-mode value?>

    This processing instructions sets the view mode to be activated in the PostScript and PDF viewers when the file is rendered and viewed. In PostScript, the information is coded in pdfmark operators and used for further conversion to PDF.
    The following are possible values:

    • auto - If there are bookmarks in the document, the bookmarks pane is displayed. Otherwise, all auxiliary panes are hidden.
    • show-none - All auxiliary panes are hidden.
    • show-bookmarks - The bookmarks pane is displayed.
    • show-thumbnails - The thumbnails pane is displayed.
    • full-screen - The document is displayed in full screen-mode.

      Default: auto

    <?ditype-ps-clone-eps value?>

    This processing instruction controls whether EPS graphics are included in the PostScript output using forms mechanism, or by pasting their contents at each occurrence. The following are possible values:

    • true - EPS graphics are pasted into the output stream at each occurrence. This may lead to a substantial growth of the resulting file size.
    • false - EPS graphics are in PostScript form. This minimizes the file size, however, some EPS images cannot be processed this way and it may corrupt the PostScript code.

      Default: true

    <?ditype-pdf-linearize value?>

    This processing instruction controls linearization (also known as Web optimization) of the PDF output. The following are possible values:

    • true - PDF is linearized. This options is used to prepare documents for HTML output.
    • false - PDF is not linearized.

      Default: false

    <?ditype-pdf-compress value?>

    This processing instruction controls compression of content streams in PDF. The following are possible values:

    • true - PDF streams are compressed using the Flate algorithm.
    • false - PDF streams are not compressed. This option is useful for debugging.

      Default: true

    <?ditype-pdf-ownerpassword value?>

    This processing instruction sets an owner password for the PDF document to value. Owner password gives its holder full control over the PDF document. This unlimited access includes the ability to change the document's passwords and access privilegies.

    Note: Adobe Acrobat by default applies user's access restrictions to owners too. To remove some of these restrictions, go to 'Document Properties -> Security' and choose 'Change Settings' option.

    <?ditype-pdf-userpassword value?>

    This processing instruction sets a user password for the PDF document to value. Holders of user password are subject to access restrictions; only operations included in the privilege list are authorized.

    <?ditype-pdf-userprivileges value?>

    Sets the default privilege list for users accessing the rendered document with user password. The value must be a sequence composed of the following tokens:

    • print - Enables printing the document.
    • modify - Enables editing the document.
    • copy - Enables copying text and images from the document to the clipboard.
    • annotate - Enables adding notations to the document and changing the field values.

    Tokens can be specified in any order, separated by commas and/or spaces.

    Note: If neither user password nor owner password is set, security is disabled and the rendered PDF is not encrypted.
    If the user password is set and the owner password is not set, then the latter is set equal to the former. This enables password protection on the PDF file, but gives password holder full control over the document: no distinction is made between user and owner.
    If the owner password is set and the user password is not set, the rendered PDF document can be viewed by anyone without entering a password. However, operations on this file will be restricted to privileges specified in the user privilege list; other operations will require authentication with the owner password.

    Default: Security disabled (neither of the passwords are set). Default privilege list is annotate.

    Note: Setting passwords through a configuration file poses obvious security risks, and is not recommended. Use processing instructions to enable file protection.

    <?ditype-pdf-pdf-version value?>

    This processing instruction sets target PDF version. The following are possible values:

    • 1.2
    • 1.3
    • 1.4

      Default: 1.3

    Note: When set to 1.3, advanced features of PDF 1.4 are disabled.

    A temporary-directory options of file-server service is URL to DiType temporary directory. DiType process should have the write access to this directory.

    Transformer service includes the folowing options:

    • arx - URL to arx executable;
    • arx-configuration - URL to arx configuration file arx.conf)

    Graphic-server service option - 404-url - is URL to the picture to be used to replace missing/invalid images.

    Preprocessor service includes the following options:

    • indent-output - to properly indent nested elements of preprocessing result;
    • abbreviate-attributes - to replace attribute names by short abbreviations;
    • remove-defaults - not to write attributes with default values;
    • px-length - to set length of 1px unit.

    The ditype-conf.rnc schema validates ditype.conf file.
  • arx.conf - ARX is a tool to automatically determine the type of a document from its name and contents. This configuration file contains the list of grammars that DiType can process and the rules that the ARX tool uses to recognize documents that use one of the listed grammers.
  • font-server.conf - Specifies the fonts to be used by DiType.
    The font-server-conf.rnc schema validates this file.
  • transformer.conf - Transformer determines the document type, applies necessary transformations to convert it to XSL FO, and then passes on. In this way, documents in WordML, XHTML, XSL 1.1, DocBook and potentially other formats are processed automatically; alternatively, the transformer applies the stylesheet referred to in xml-stylesheet processing instruction, allowing custom transformations as long as they produce XSL FO. You also can specify a stylesheet for specific XML documents in transformer.conf to avoid inserting processing instructions into each document. The transformer also can produce non-XSLT transformations, for example, it can call external programs such as RTF2FO instead of DiType transformer. The following example describes how to apply external transformer RTF2FO.EXE:
    <document type="RTF" transformer="external" transformation="RTF2FO.EXE %s %s" result-type="xsl"/>

    The document element can have the following attributes in the file transformer.conf:

    • type - document input type. Transformer uses arx to define the type of input document in DiType.
    • result-type - document output type (result of the transformation);
    • *transformer - a transformer to use; possible values are "xslt" (XSLT transformation), "identity" (no transformation, output format is the same as input format), "external" (use external transformer) and "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 a path to an external program in case of external transformer. Not specified if the option transformer has value "identity" or "none".
    • catalog - path to XML catalog. Used for XML catalog resolution.
      The transformer-conf.rnc schema validates transformer.conf file.
  • xep.conf - This configuration file is a supplementary configuration file for XEP-DiType.
    The xep-conf.rnc schema validates this file.


Personal tools