Chapter 3. Using downCast

1. Basic operations
1.1. Choosing the source file
1.2. Choosing an XSLT processing sheet
1.3. Choosing the destination folder
1.4. Generating Word binary (.doc) files
1.5. Setting the default image resolution
1.6. Setting the Whitespace Handler
1.7. The conversion process
1.8. Aborting a running conversion
2. Working with Configurations
2.1. What is a configuration?
2.2. Saving a configuration
2.3. Opening a configuration
2.4. A special configuration: preferences.plist
3. Logging
4. WordLink
5. Magic Folders and Locations

1. Basic operations

This section describes basic operations for running downCast in GUI mode.

1.1. Choosing the source file

The source file should either be an XML file valid against the upCast DTD, or you should provide an XSLT processing sheet that transforms the source file to an XML file that then is valid against the upCast DTD (see Section 1.2, “Choosing an XSLT processing sheet”).

If the specified file is not a valid file, chances are that the conversion process does not succeed, though downCast will try to process the file anyway as far as possible.

Clicking the Browse… button next to the Source file text field brings up a file chooser dialog which lets you navigate through the folder structure of your mounted hard drive(s) or volumes. Select the file you want to convert and close the dialog by clicking OK.

You can also directly type in the name and access path of the source file you want to convert.

In doing so, to separate folder names, you must use the forward slash ('/') on Unix and Macintosh systems. On Windows machines, use the backslash ('\') character instead. The slashes will be converted to the appropriate, system specific separator character during file access.

1.2. Choosing an XSLT processing sheet

Note

This step is optional.

In case your source XML file does not conform to the upCast DTD, downCast has an XSLT processor built in to let you perform an appropriate transformation automatically to the source file. The result of that transformation is then processed by downCast - all at the mere click of a button.

Clicking the Browse… button next to the Pre-process with XSLT text field brings up a file chooser dialog which lets you navigate through the folder structure of your mounted hard drive(s) or volumes. Select the XSLT file you want to process the Source file with and close the dialog by clicking OK.

You can also directly type in the name and access path of the XSLT file you want to use.

In doing so, to separate folder names, you must use the forward slash ('/') on Unix and Macintosh systems. On Windows machines, use the backslash ('\') character instead. The slashes will be converted to the appropriate, system specific separator character during file access.

You can also choose which of the included XSLT processors you want to use, Xalan or Saxon (if installed).

Note

Saxon 8 (supporting the current XSLT 2 draft specification) is only available on Java 1.4 or later.

You can also supply (constant) parameter values to the XSLT processor. These can only be of type string. The syntax to be used in the XSLT Parameters field is as follows:

[name '=' '"' value '"']? [ '[;,]' name '=' '"' value '"' ]*

XSLTProcessor String xalan | saxon

XSLTParameters String parameters

ProcessingSheet String absolute/path/to/preprocess.xsl

1.3. Choosing the destination folder

Next, choose the destination folder, i.e. the location where downCast will put its output file.

Clicking the Browse… button next to the Destination folder input field brings up a folder chooser dialog which lets you navigate through the folder structure of your hard drive(s). Select the folder you want downCast to put its result file into and close the dialog by clicking Choose Folder.

Note

The folder to be selected must be highlighted when you click Choose Folder.

You can also type in the path of the desired destination folder directly.

In doing so, to separate folder names, you must use the forward slash ('/') on Unix and Macintosh systems. On Windows machines, use the backslash ('\') character instead. The slashes will be converted to the appropriate, system specific separator character during file access.

1.4. Generating Word binary (.doc) files

When you are running under Windows and have installed WordLink properly, you can have the RTF file generated by downCast automatically post-processed into Word binary (.doc) format. Also in this process, all fields contained in the file will be updated with current contents. To enable this functionality, check the Convert .rtf output to .doc format checkbox.

Note

This option is only enabled when running the application on Windows platforms and if WordLink is installed and functional.

ConvertToDoc Boolean true | false

1.5. Setting the default image resolution

When downCast must include images that do not specify their resolution explicitly in the file, the application uses the value that you specify in the Default image resolution field to calculate image size and resulting scaling factor to apply in .rtf output. The default is 96 dpi.

DefaultPixmapResolution Integer 20..9999

1.6. Setting the Whitespace Handler

(Experts only) downCast makes use of special code to handle whitespace characters in the input stream. This field lets you set a custom whitespace handler if this is required. A whitespace handler must be a Java class that implements the WhitespaceHandler interface. If you think you need to implement your own whitespace handler, please contact us directly at in advance.

The default value is '*' (asterisk) which lets downCast decide on the most appropriate whitespace handler for the input document and should not be changed for normal use.

WhitespaceHandler String fully.qualified.WhitespaceHandler.class

1.6.1. Standard Whitespace Handlers

downCast comes with three Whitespace Handlers for different situations. You request their explicit use by specifying their full, qualified class name in the Whitespace Handler input field.

Warning

Except for the NoOp handler, all are more or less experimental and we do not guarantee their correctness or usefulness.

de.infinityloop.downcast.rtflib.NoopWhiteSpaceHandler

This is the default handler for input documents valid according to the upCast DTD. All whitespace is significant in mixed-content elements. It is automatically used when you specify '*' and the input document has an .xml extension.

de.infinityloop.downcast.rtflib.XSLFOWhiteSpaceHandler

This is a white space minimizing handler, minimizing whitespace in mixed-content elements. It is automatically used when you specify '*' and the input document has an .fo extension. It tries to mimic XSL-FO required behaviour when minimizing whitespace before and around inline elements. Whitespace is collapsed to the left.

de.infinityloop.downcast.rtflib.CSS3WhiteSpaceHandler

This handler behaves exactly the same as the XSLFOWhiteSpaceHandler, except that it respects the setting of the white-space CSS3 shorthand property, resp. its all-space-treatment component when resolved to its constituent properties. When this has the value preserve, whitespace is preserved in that element, unless overridden in a child element. When this is collapse (the default), the handler behaves as described above. Note that you should explicitly specify the desired behaviour on the immediate parent element of (probably) mixed content.

1.7. The conversion process

To start a conversion process, click the Start Conversion button.

The conversion process in downCast consists of up to three phases:

First, downCast optionally reads and pre-processes the source file with the specified XSLT processing sheet. Then it reads in the XML file and any linked CSS file. Finally, the export process is initiated and the resulting RTF file is generated. The exported file will have the name basefilename.rtf.

1.8. Aborting a running conversion

The progress window that is displayed during a conversion process provides a Cancel button. You can abort the conversion process at any time by clicking this button.

Note

The progress bar's dispaly is sluggish and it may take some time until it reacts to user input. This will be remedied in a future version.

2. Working with Configurations

2.1. What is a configuration?

A configuration in downCast consists of all settings you can make via the GUI. It describes the current state of the application and comprises the following areas:

  • current source file selection

  • current XSLT processing sheet file selection

  • current destination folder

2.2. Saving a configuration

To save the current configuration of downCast to disk, choose Save Configuration… from the File menu. This brings up a file chooser dialog that lets you select the location and the name of the file where the configuration will be stored. Click on Save to actually save the configuration.

Important

For consistency reasons, you should make sure that the file name has the extension .plist.

2.3. Opening a configuration

To open or reload a configuration you had previously saved, choose Open Configuration… from the File menu. In the file chooser dialog presented, choose the configuration you want to open.

2.4. A special configuration: preferences.plist

The preferences file preferences.plist, located in the {Preferences Folder}, is a special configuration file that is saved every time you quit downCast, and that is automatically restored whenever you start downCast.

For you, this means that the configuration of the downCast application is automatically preserved across single sessions.

This file is stored in the platform specific {Preferences Folder} folder.

3. Logging

downCast relies on the log4java™ logging framework. Describing the configuration of this system is beyond the scope of this manual; for details, see the log4java project website.

The default configuration of the system is:

# Set root logger level to DEBUG and its only appender to A1.
log4j.rootLogger=INFO, A1

# A1 is set to be a RollingFileAppender.
log4j.appender.A1=org.apache.log4j.RollingFileAppender

# A1 Set options.
log4j.appender.A1.MaxFileSize=4096KB
log4j.appender.A1.MaxBackupIndex=10
log4j.appender.A1.File=${de.infinityloop.application.logfile}
log4j.appender.A1.layout=org.apache.log4j.PatternLayout
log4j.appender.A1.layout.ConversionPattern=%d{DATE} %X{ilInstance} %-5p %x - %m%n

As you can see, downCast defines the property de.infinityloop.application.logfile to hold the path to the log file to write to. This configuration file is found in the downCast distribution JAR at the following location: {JAR Resource Location Path}/config/log4j.properties. If you need or want to change the logging behaviour of the product, you need to change this file in the distribution JAR.

Note

We recommend to remove the log4j.properties file completely when using downCast as a library and control logging completely from the host application's log4j configuration. When you remove the log4j.properties file from upcast.jar, downCast does not set up any logging.

You'll probably want to change the default configuration when using downCast as a library in a custom application, where you want it to write to a specific log or a stream. You may do this e.g. programmatically using the log4java™ API.

To view the contents of the logfile select View Log File from the File menu. This displays the current contents of the logfile in a new window at the time this window is opened.

If you want to save the contents of the logfile persistent to a different file, use the Save Text As… button at the bottom of the window.

Note

When you submit a bug report to infinity-loop or request technical support, please include the contents of the respective logfile along with the document itself in your e-mail. This might be valuable information for our technical support staff to track down your problem and assist you in finding a solution.

4. WordLink

If you're running upCast on Windows 95/98/2000/NT/XP and have a working installation of Word 97 or later, you can also convert to Microsoft Word binary (*.doc) files directly. For this to work, you need to install some additional software included in the downCast distribution. To do this, choose the ExtrasInstall WordLink command. After relaunching downCast, WordLink should be available and active. You can check this in the HelpSystem Information… window.

This additional software lets downCast remote-control the installed copy of the Word application for invisibly and automatically converting the generated RTF file to Word binary .doc format. Once installed, WordLink performs transparently in the background when needed.

Note

The WordLink feature is not available on Macintosh and Unix platforms. Therefore, when running on these platforms, the ExtrasInstall WordLink command will always be disabled.

5. Magic Folders and Locations

downCast makes use of certain locations in the running machine's file system to store support and session information. These locations are different depending on the underlying native Operating System that runs the Java Virtual Machine. This manual denotes these "magic" places by placing the name of the location in curly braces, e.g. {Application Support Folder}. To learn the actual location on the machine downCast is running on, open the HelpSystem Information... window, where the name as enclosed in the curly braces is listed with its corresponding file system location.

The following magic folders and locations are currently defined:

{Application Support Folder}

The root folder for application support data.

{Licenses Folder}

This folder contains installed licenses for the software. License files must end in .license to be recognized. If several licenses are valid for the application, it will show a list of them to choose from at startup time.

{current license file}

This indicates the license file currently in effect.

{JAR License Location Path}

This is the path in the distribution JAR where you may store a file named downcast.license. If this file exists at the specified location, it is used. If there are also license files in the {Licenses Folder}, a list will be displayed to choose from at application launch time.

{Log File}

The path to the application's log file.

{Encodings Folder}

The folder where custom encodings can be placed. For encodings to be recognized by the application, their file name must end in .encoding.

{'stdfonts.config' File}

The stdfonts.config file currently in effect.

{DTDs Folder}

The folder where the application copies its own DTD and where you should put any additional DTDs, each one in its own folder.

{Application Preferences}

The folder where application preferences will be stored at quit time.

{'preferences.plist' file}

The location of the preferences.plist file where current application configuration parameters are persistently stored when the application is quit and where these settings are restored from upon next launch.

{Documentation Folder}

The root folder for application documentation data and related files.

{documentation root file}

The file that is opened when the user chooses HelpBuilt-in Help... . By replacing the default file with a custom one at this location, you can provide custom help files or documentation for specific installations.

{JAR Resource Location Path}

The root location in the application JAR where configuration files for the application are retrieved from.