DiType User Guide/Standard Applications

From Docs

Jump to: navigation, search

< DiType User Guide

The DiType installation contains three simple applications that expose the functionality of the DiType engine. The three applications are:

  • DiType Assistant - A user-friendly GUI tool.
  • DiType Command Line - A command line interface to the DiType formatting engine.
  • ActiType - A tool to aid automatic formatting of XSL files to PDF, PostScript and SVG (or ZIP) output.

These applications are intended for personal use to help new users get started using DiType. The applications are detailed in the following sections.

Note: All figures in this chapter show the applications running on a Windows platform. On other platforms, the applications contain identical features that are displayed according to the platform's user interface.

Contents

DiType Assistant

This section describes the DiType Assitant.

What is the DiType Assistant?

XEP DiType contains a user-friendly GUI tool, called the DiType Assistant. Using the DiType Assistant simplifies rendering from XML or XSL-FO into the desired output format.

Opening the DiType Assistant

To open the DiType Assistant:

  • On Windows, from the Start menu, choose All Programs > RenderX > DiType > DiType Assistant.
  • On Mac OS X, DiType Assistant is installed in the Applications menu.
  • On Linux/Unix the script that invokes DiType Assistant is bin/assistant in the DiType installation directory.

Rendering an XML File using the DiType Assistant

Opening a File

To render a file, you must first open the XML or XSL-FO file you wish to publish.

To open an existing XML or XSL-FO file:

1. From the File menu, click Open.

A dialog box is displayed .

2. Browse to the file you wish to open.

The file is opened within DiType Assistant.

XML file displayed in the DiType Assistant
XML file displayed in the DiType Assistant

Formatting a File

Formatting a file is a two-stage process comprising transforming and rendering. After an XML file is opened, it must be transformed before it can be rendered to PDF or PostScript output.

The transformation stage of the formatting process assigns the settings required for applying an XSL stylesheet to the XML file. The XML file is transformed into an XSL-FO. The XSL-FO is then rendered to your final output format (PDF, PS or SVG).

To format an XML file:

1. From the Format menu, click Start.

The Formatting Settings dialog box appears.

Formatting Settings dialog box
Formatting Settings dialog box

2. Set the desired settings as described in the following table.

Formatting Settings
Parameter Description
Stylesheet
Stylesheet Select the name and location of the stylesheet you wish to apply to your XML file.
Output
Format Select the format to which you want to render the XML file. Available options are PDF, XEP, PS, SVG (or ZIP).
Path Select the location and name of the file to which the output will be saved.

Note: If a file with the same name already exists in the chosen location, the new file will overwrite the preexisting file with no warning.

Viewer
Path Browse to the location of the program with which you wish to view the rendered file.

3. Click Format to format the file, or Cancel to cancel the formatting.

To cancel formatting:

1. From the Format menu, click Stop.

Formatting is canceled.


DiType Command Line

This section describes how to run DiType from the command line.

Running DiType

DiType can be run from the command line using the ditype Command Line Tool.

  • On Windows, ditype is located in the DiType installation directory in the Framework/Commands/ directory.
  • On Mac OS X, ditype is located in the /Library/Frameworks/DiType.framework/Commands directory.
  • On Linux/UNIX, ditype is located in the DiType installation directory in the bin/ directory.

ditype is a batch/shell script that invokes diclick.py , which is a Python application that communicates with the DiType server.

The syntax of the Windows batch and Linux/Mac shell command is:
ditype {switches} {arguments}

This syntax assumes the full path to the Windows batch file ditype.bat or the Linux/Mac shell script ditype is specified in the PATH environment variable, or that the current directory is the directory containing the Windows batch file or Linux/Mac shell script.

The switches and arguments are the same whether ditype is run via a Windows batch file or via a Linux/Mac shell script.

ditype Switches

The ditype switches configure the behavior of the command line utility.

ditype Switches
Switch Description
--version Prints the program version and the exit option.
-h, --help Displays the usage syntax and the exit option.
-H <host>

--host=<host>

Sets the host name or IP address of the computer on which the DiType server is running. The command line client will connect to that host and make the DiType server do the formatting. The default value is 'localhost'.
-p <port>

--port=<port>

Sets the port number of the computer running the DiType server. The default value is 19790.
-i <format>

--input=<format>

Sets the format for the input files to the DiType rendering engine. The possible values for this switch are 'xsl', 'fo', 'dbx', 'dita', and 'auto'. The default value is 'auto'. When set to 'auto', the DiType server automatically determines the file type and applies the corresponding transformation, if configured.
-f <format>

--format=<format>

Sets the format for the output files from the DiType rendering engine. The possible values for this switch are 'ps', 'pdf', 'xep', 'svg' (or 'zip') for PostScript, PDF, DiType Intemediate Format, and SVG, respectively. The default value is 'ps'. Other values that correspond to document types known to transformer.conf can also be specified. This assumes that there is a path over the set of types from the input format to the output format. For example, to transform an arbitrary ('auto') input to 'fo', specify '-f fo'. In this case, only transformations will occur, the file will not be rendered.
-s <SysId>

--sysid=<SysId>

When a file to format is supplied as an argument to ditype , the DiType server will ask the client to provide locally referenced files; for example, stylesheets or images (if any). The client will send these files to the server, resolving relative links from the input file itself.

When ditype is invoked without arguments, it works as a pipe, reading input on stdin and writing output to stdout. In this case, the client does not have the information about the actual location of the input. In order to resolve relative links properly, the user must specify SysId so that if the input stream was read from a file located at this SysId, the relative links would point to the appropriate location.

The default value of SysId is file://$PWD/stdin. In general, ditype users may omit the -s option if the input stream originates from a file in the current directory:
cat afile.fo | ditype 
However, it is nesessary to specify the proper SysId in other cases:
cat /path/to/afile.fo | ditype -s "file:///path/to/afile"
-a, --append Specify this switch to append the file extension to the output filename. If the input filename is input.xml and the output format is 'ps', the output filename will be input.xml.ps. By default, the output file extension replaces the input file extension. This option has no effect when running as a pipe.
-q By default, ditype writes detailed messages to stderr. These messages indicate the current status and progress of the rendering process, as well as any warnings or errors that may occur during the rendering process.

Specify this switch to suppress the detailed informational messages. In this case, the renderer outputs only warning and error messages.

-d Specify this switch to include additional debugging information during the rendering process. By default, debugging is not enabled. It is possible to specify both the '-q' and '-d' switches.

ditype Arguments

The ditype arguments are one of the two ways to provide DiType with the data to process.

Note: If any argument string contains spaces, the entire string must be enclosed in quotation marks.

An xml/xsl pair of files may not be passed to ditype. Instead, add the xml-stylesheet processing instruction to the source file immediately after the XML declaration, as shown in the following example.
<?xml-stylesheet type="text/xsl" href="stylesheets/mystylesheet.xsl"?>

ActiType

ActiType is a simple application used for asynchronous formatting of XSL files to PDF, PostScript and SVG (or ZIP) output. ActiType constantly monitors its active folders. When a file is placed in an active folder for processing, ActiType formats it via DiType to a specified format according to the configured rules.

This section describes the ActiType application and how to share ActiType between multiple users.

Opening ActiType

To open ActiType in Windows, from the Start menu, choose All Programs > RenderX > DiType > ActiType.

The ActiType Window

ActiType Window
ActiType Window

The ActiType window consists of two panes:

  • Left pane - All hot folders, which are folders added to the ActiType configuration file for formatting, are displayed.
    Click on a hot folder to expand its node and view all rules that are configured for the specific folder.
  • Right pane - Displays properties and log of the hot folder in currently focus.

Formatting an XML or FO File using ActiType

In order for a document to be formatted you need to create a hot folder and to configure a rule or multiple rules to be applied to the hot folder. ActiType monitors all active hot folders: it detects new files added to the hot folders and automatically formats them via DiType according to the rules specified for the folder.

Formatting a file consists of the following steps:

  1. Creating a Hot Folder
  2. Configuring Rules for the Hot Folder
  3. Starting the Hot Folder
  4. Formatting a File

Creating a Hot Folder

To format a file, you must first create a hot folder by adding a folder to the ActiType configuration folder.

To create a hot folder:

1. From the Folder menu, click Add.

A dialog box is displayed .

2. Browse to the folder you wish to create as a hot folder.

The folder is added to ActiType as a hot folder.

Folder Added to DiType
Folder Added to DiType

3. Set the desired properties, as described in the following table.

Hot Folder Properties
Parameter Description
Format Select the format to which you want to format files within the hot folder. Available options are PDF and PostScript.
Output Path Select the location and name of the file to which the output will be saved.

Note: If a file with the same name already exists in the chosen location, the new file will overwrite the preexisting file with no warning.

State The current state of the folder. This is a non-editable field that reflects the status of the hot folder.
  • Started - The folder is being monitored and when a new file is detected it will be formatted according to the rules associated with it.
  • Stopped - The folder is not being monitored and files within the folder will not be formatted.

Configuring Rules for the Hot Folder

Once a hot folder is created, you must configure rules that define which type of files inside the hot folder will be formatted and which stylesheet will be used for formatting.

To add a rule:

1. Click on the hot folder.

2. From the Folder menu, click Rules > Add.

A new rule is added.

Adding a Rule
Adding a Rule

3. Set the desired properties, as described in the following table.

Rule Properties
Parameter Description
Name Specify a name for the new rule.
Extension Specify an extension. All files inside the hot folder with the extension specified will be formatted. All other files will be ignored.
Stylesheet Select the name and location of the stylesheet which will be used for formatting the files within the hot folder.

To edit a rule:

1. Click on the rule you wish to edit.

2. Make any changes you wish to the name, extension, or stylesheet fields.

An Apply button appears.

Editing a Rule
Editing a Rule

3. To apply the changes to the rule, click Apply.

The rule is updated.

To delete a rule:

1. Click on the rule you wish to delete.

2. From the Folder menu, click Rules > Delete.

The rule is deleted.

Starting the Hot Folder

In order for a hot folder to be monitored, it must be started.

To start the hot folder:

1. Click on the hot folder.

2. From the Folder menu, click Start.

The hot folder status is now "Started." The folder will now be monitored and all new files added to the folder will be detected and formatted according to the rules configured.

Formatting a File

To format a file, simply copy it into your hot folder. It will then be detected and formatted according to the rules you defined for the hot folder.

Stopping a Hot Folder

A hot folder can be stopped so that it is no longer monitored.

To stop a hot folder:

1. Click on the folder you wish to stop.

2. From the Folder menu, click Stop.

The hot folder status is now "Stopped." The folder will not be monitored and new files added to the folder will not be formatted.

To stop all hot folders:

1. From the Folder menu, click Stop All.

All hot folders are stopped.

Closing the Application

To close ActiType:

1. From the File menu, click Close.

The ActiType GUI is closed. However, ActiType continues to run in the system tray, monitoring all hot folders and formatting any new files added to the hot folders.

To quit ActiType:

1. From the File menu, click Exit.

ActiType is now inactive. It is no longer running in the system tray.

Running ActiType in Console Mode

During the DiType installation, a link to ActiType is installed in the Startup menu of the user. When the computer is restarted, ActiType also starts and appears as an icon in the System Tray (Windows only). Currently, the icon only supports opening the main ActiType window.

ActiType may also be run in console mode , that is, without the icon in the System Tray. In this mode, users may not use the GUI to change the configuration or to stop and start folders. The advantage of running ActiType in console mode is that it does not require a user log in. This is essential when ActiType is installed on an Intranet server.

If ActiType is not currently running, it can be started in console mode by running one of the following command at the command prompt:
python actitype.pyw -n -c actitype.conf
or
python actitype.pyw --non-gui-mode --config actitype.conf

Configuration File

ActiType is configured using a configuration file. The configuration file can be edited in any text editor, and the configuration can then be applied either in console mode or by using the ActiType GUI.

The following is a sample configuration file:
<?xml version="1.0"?>

<!-- ActiType configuration file -->

<actitype>
    <folder path="C:\My Documents\ActiType Hot Folder"
            output-path="C:\My Documents\ActiType Output Folder"
            output-format="application/pdf"
            state="started"
            <rule name="XML" ext=".xml"/>
    </folder>
</actitype>
If the name of the sample configuration file is MyActiTypeConfig.conf , it can be loaded by running the following command at the command prompt:
python actitype.pyw -n -c MyActiTypeConfig.conf

Sharing ActiType

It is possible to share an installation of ActiType between multiple users in a Windows environment. The steps required to share an ActiType installation are described in the following section.

Note: This procedure assumes that there is a dedicated computer running Windows with DiType installed with the default options.

To share ActiType:

1. Navigate to C:\Documents and Settings\<your_user_name>\Start Menu\Programs\Startup and delete ActiType.lnk - this prevents ActiType from being started twice.

2. Create a new shared folder (it must be viewable on the Windows network from other computers):

C:\Documents and Settings\All Users\Documents\Shared ActiType Hot Folder

3. Add the new folder to the ActiType configuration file:
<folder path="C:\Documents and Settings\All Users\Documents\
        Shared ActiType Hot Folder"
        output-path="C:\Documents and Settings\All Users\Documents\
        Shared ActiType Hot Folder"
        output-format="application/pdf"
        state="started"
   <rule name="FO" ext=".fo"/>
</folder>

4. From Control Panel , open Scheduled Tasks and select Add Scheduled Task.

Apply the following parameters for the task:

  • Run:
    C:\PROGRA~1\RenderX\DiType\FRAMEW~1\Common\env\Python2.4\pythonw.exe -E 
    "C:\Program Files\RenderX\DiType\Actitype\actitype.pyw"
    -n -c actitype.conf
  • Start in: C:\Program Files\RenderX\DiType\Actitype\
  • Run as: < your credentials, password required >
  • Uncheck Run only if logged on.
  • Check Enabled.
  • On the Schedule tab, select At System Startup.
  • On the Settings tab, uncheck all boxes.

5. Reboot, but do not log on.

You can now copy source files to the shared hot folder and view the resulting output.



Personal tools