6. User preferences

By default, the user preferences are stored in the following directory:

$HOME/.xfc/ on Linux.
$HOME/Library/Application Support/XMLmind/FOConverter/ on the Mac.
%APPDATA%\XMLmind\FOConverter\ on Windows. Example: C:\Users\john\AppData\Roaming\XMLmind\FOConverter\.

You may delete this directory if you want to restore the “factory settings”.

File user_preferences_dir/xslutil.conversions contains the modifications made to the stock conversion specifications and the original conversion specifications personally created by the user. Deleting just this file will have the effect to restore all the stock conversion specifications (db5ToXXX, dbToXXX, xhtmlToXXX, etc) and to delete all the user's original conversion specifications.

6.1. The `-p` command-line option

The -p command-line option allows to specify a custom user preferences directory. This option may be used when XMLmind XSL Utility is used as a graphical application:

/opt$ xslutil-6_4_3/bin/xslutil -p /usr/local/share/xslutil &

or when XMLmind XSL Utility is used as a command-line tool:

/opt/xslutil-6_4_3/bin$ xslutil -p /usr/local/share/xslutil \
    dbToDocx /tmp/help.xml /tmp/help.docx

Specifying a custom user preferences directory allows to use XMLmind XSL Utility, a convenient graphical application, to configure the conversions of XMLmind XSL Server. For example, if xslsrv/WEB-INF/web.xml contains:

<init-param>
  <param-name>customizeDir</param-name><param-value>/etc/xslutil</param-value>
</init-param>

then run xslutil -p /etc/xslutil to configure the conversions of XMLmind XSL Server.

6.2. General preferences

Use the native file chooser in preference to the multi-platform file chooser

If this toggle is checked, the native file chooser will be used in preference to Java's multi-platform file chooser.

Note that file extension filters are not supported when the native file chooser is invoked by Java™.

Default: not checked on Windows and on the Mac, disabled (grayed out) on the other platforms.

Warn me when the output directory is not empty

Some conversion (example: conversion to multi-page HTML, to Eclipse Help) require an output directory rather than an output file. This output directory will be created if it does not exist. However, if it exists, the output directory will be made empty before performing the conversion, which is potentially dangerous. When this option is turned on, you'll have to confirm that you really want to delete all the files contained in the output directory before proceeding with the conversion. We do not recommend to turn this option off.

Default: checked.

Cache compiled stylesheets

Compiling an XSLT stylesheet may take a few seconds. When this option is turned on, an XSLT stylesheet is compiled the first time it is used and then, it is cached in compiled form for all subsequent uses. Unless you are developing a XSLT stylesheet and testing it with XMLmind XSL Utility, there is no need to turn this option off.

Default: checked.

Restore stock conversion specifications

Clicking this button allows to restore all the stock conversion specifications. The user's original conversion specifications are, of course, left untouched.

6.3. Helper applications preferences

	Converting DITA documents to HTML Help
	In addition to letting you specify which external applications are launched when "Preview result in a helper application" is checked, this preferences sheet also lets you specify the location of `hhc.exe`, an external tool, which is required to convert DITA documents to HTML Help.

File types

List of file types. Each file type has an associated helper application. This helper application is assumed to be able to open files detected as having this type. A helper application may be a viewer or an editor.

The following buttons may be used to modify this list:

Add: Displays the "Helper Application Editor" dialog box in order to add a new file type to the list.
Edit: Displays the "Helper Application Editor" dialog box in order to view or modify selected file type.
Remove: Removes selected file type from the list.

Default viewer

Specifies which default viewer to use in case the type of the file to be opened has not been detected. In practice, commands making use of the default viewer typically assumes that it is in fact a Web browser. This implies that these commands assume that a default viewer can open URLs as well as filenames and that it can open text, HTML, GIF, PNG and JPEG files.

This field must contain a command line interpreted by the native shell of the platform: cmd.exe on Windows and /bin/sh on the Mac and on Unix.

This command line must reference one of these two substituted variables: %U and %F. In principle, %U is replaced by the URL of the file to be opened by the helper application and %F is replaced by a filename. In practice, %U is just a hint meaning: the helper application can open URLs as well as filenames.

Default: depends on the platform:

On Windows: start "" "%U"
On the Mac: open "%U"
On Unix: dynamically detected. For example: firefox "%U"

The following buttons may be used to modify this field:

Reset

Resets the field to its default value (see above).

Choose

Displays the standard file chooser in order to specify an application (e.g. a .exe or a .bat file on Windows). String " "%F"" is automatically appended to the chosen application.

6.3.1. The "Helper Application Editor" dialog box

This dialog box allows to view or modify a file type listed in the "Helper applications" preferences sheet.

A file type is specified by at least one of the following characteristics:

MIME type

The official (or just well-known) formal name of the file type. Generally returned by Web servers to their client Web browsers. Non-registered MIME types typically start with string "application/x-".

A MIME type may end with a wildcard. Example: "image/*" matches "image/gif", "image/jpeg", etc.

Examples: text/plain, image/jpeg, application/excel, application/x-java-help-index.

Filename extension

If the filename or URL of a file ends with specified ".extension", then this file is detected as having this file type.

An extension may or may not start with a dot. This is unimportant because, in all cases, a leading dot would be automatically stripped.

Examples: txt, jpeg, jpg, xls.

Magic string

For some file formats, the first bytes of a file are always the same and therefore, can be considered as being the signature of this file type.

If a file starts with specified first bytes, then this file is detected as having this file type. This type of detection is supposed to work like magic, hence the name: ``magic string''.

A magic string may be specified by a the hexadecimal representation of a sequence of bytes (example, one of the two TIFF magic strings: 4949) or by a quoted sequence of ASCII characters (same example, one of the two TIFF magic strings: "II").

Examples: TIFF: "II" or 4949, "MM"or 4D4D; GIF: "GIF87a", "GIF89a"; PNG: 89504E47; PDF: "%PDF-".

XML name pattern

If the root element of an XML file has a name which matches specified pattern, then this XML file is detected as having this file type.

An XML name pattern follows this syntax:

( '{' namespace_URI? '}' )? local_part

One of local_part or namespace_URI may be equal to wildcard "*"

Examples: {*}svg, {http://www.w3.org/1998/Math/MathML}:math.

Each file type has an associated helper application. This helper application is assumed to be able to open files detected as having this type. A helper application may be a viewer or an editor.

Description

Description of the file type. Not mandatory, just recommended. This text is displayed in the File types list of the "Helper applications" preferences sheet.

MIME type

One or more MIME types (see definition above) separated by spaces.

Filename extension

One or more extensions (see definition above) separated by spaces.

Magic string

One or more magic strings (see definition above) separated by spaces.

XML name pattern

One or more XML name patterns (see definition above) separated by spaces.

Use helper application

This field must contain a command line interpreted by the native shell of the platform: cmd.exe on Windows and /bin/sh on the Mac and on Unix.

The Choose Helper Application button displays the standard file chooser in order to specify an application (e.g. a .exe or a .bat file on Windows). String " "%F"" is automatically appended to the chosen application.

Helper applications on the Mac

	Helper applications on the Mac
When an application, that is, a folder having a name ending with hidden suffix "`.app`", containing a package bundle, has been selected by the user, the Choose Helper Application button automatically prepends "`open -W -n -a` " to chosen `.app` folder. Example: "`open -W -n -a /Applications/Inkscape "%F"`". Options "`-W -n`" mean: start a new instance of the application and wait until this instance has exited. These options are required when the helper application is used to edit the content of an element, the content of an attribute or the whole document.

When an application, that is, a folder having a name ending with hidden suffix ".app", containing a package bundle, has been selected by the user, the Choose Helper Application button automatically prepends "open -W -n -a " to chosen .app folder. Example: "open -W -n -a /Applications/Inkscape "%F"".

Options "-W -n" mean: start a new instance of the application and wait until this instance has exited. These options are required when the helper application is used to edit the content of an element, the content of an attribute or the whole document.

Use default viewer

Files having specified type are to be opened using the default viewer. The default viewer is specified in the "Helper applications" section of the "Preferences" dialog box.

Use text editor

Files having specified type are to be opened using the “default text editor”.

	Which text editor?
	This text editor to be used is the helper application associated to the "`text/plain`" MIME type. If such association has not been defined, the standard text editor of the platform is automatically used (e.g. on Windows, it's `notepad`).

6.4. FOP preferences

Figure 9. The "FOP" preferences sheet

By default, only the 14 built-in fonts: Times, Helvetica, Courier, Symbol and ZapfDingbats are used in the generated PDF. The above preferences sheet allows to specify which custom TrueType (.ttf) fonts are to be embedded in the generated PDF.

This facility is useful in the following two cases:

The 14 PDF standard fonts (Helvetica, Times, Courier, etc), which are used by default by FOP, have glyphs only for the Western languages. If, for example, you convert a DocBook document written in Russian to PDF, the generated PDF will mainly contain the '#' placeholder character. Fortunately, widely available TTF fonts such as Microsoft® Arial, Times New Roman and Courier New or the DejaVu fonts have glyphs for almost all the languages of the world.
Use fonts nicer than the 14 PDF standard fonts.

Procedure 5. How to use Times New Roman, Arial and Courier New instead of Times, Helvetica, Courier

Click Use Windows® standard fonts.
Note that the Use Windows® standard fonts button is grayed if the Arial font is not found in the standard fonts folder of your system.
Click OK.
Restart XMLmind XSL Utility.

Procedure 6. How to choose specific fonts (for example, you want to replace Times fonts by Georgia fonts)

Click Add.

This displays the following dialog box:

Figure 10. The "Choose a TTF font and specify its aliases" dialog box

Choose the .ttf file containing font "Georgia".


On Windows, for permissions reasons, there is no way to pick a font file from the "`C:\Windows\Fonts\`" folder using the standard file chooser. Therefore the only way to register with Apache FOP a font found in "`C:\Windows\Fonts\`" is to drag its file from the Windows file manager and to drop it onto the list found in the "FOP" preferences sheet (see above figure). However, after you do this, do not forget to select each entry added by the drop action and then click Edit to possible change or complement what's have been automatically specified there.

On Windows, for permissions reasons, there is no way to pick a font file from the "C:\Windows\Fonts\" folder using the standard file chooser. Therefore the only way to register with Apache FOP a font found in "C:\Windows\Fonts\" is to drag its file from the Windows file manager and to drop it onto the list found in the "FOP" preferences sheet (see above figure).

However, after you do this, do not forget to select each entry added by the drop action and then click Edit to possible change or complement what's have been automatically specified there.

Specify the following alias: serif.
Click OK.

Click Add.
1. Choose the .ttf file containing font "Georgia Bold".
2. Specify the following alias: serif, Bold.
3. Click OK.
Click Add.
1. Choose the .ttf file containing font "Georgia Italic".
2. Specify the following alias: serif, Italic.
3. Click OK.
Click Add.
1. Choose the .ttf file containing font "Georgia Bold Italic".
2. Specify the following alias: serif, Bold, Italic.
3. Click OK.
Click OK.
Doing this automatically creates a standard FOP configuration file in user_preferences_dir/fop/fop.conf. User preferences directory user_preferences_dir is documented in Section 6, “User preferences”.
It is recommended to repeat the above steps in order to specify fonts replacing Helvetica, that is, fonts having a sans-serif alias and fonts replacing Courier, that is fonts having a monospace alias.
Restart XMLmind XSL Utility.

Using in XSL Utility an existing FOP configuration file

	Using in XSL Utility an existing FOP configuration file
The location of an existing Apache FOP configuration file may be specified to XSL Utility by the means of Java™ system property or environment variable `XXE_FOP_CONFIG`. The value of this variable is an URL or an absolute file path. Examples: `-DXXE_FOP_CONFIG=http://localhost/~john/fop/fop.conf` (Java™ system property), `set XXE_FOP_CONFIG=C:\Users\john\misc\fop\fop.conf` (Windows environment variable).

The location of an existing Apache FOP configuration file may be specified to XSL Utility by the means of Java™ system property or environment variable XXE_FOP_CONFIG. The value of this variable is an URL or an absolute file path. Examples: -DXXE_FOP_CONFIG=http://localhost/~john/fop/fop.conf (Java™ system property), set XXE_FOP_CONFIG=C:\Users\john\misc\fop\fop.conf (Windows environment variable).

6.5. XEP preferences

XEP preferences are identical to FOP preferences. There are two minor differences though:

Some fonts have licensing restrictions that forbid embedding them in a PDF file. RenderX XEP enforces these licensing restrictions, not Apache FOP. XMLmind XSL Utility has currently no way to detect these licensing restrictions, therefore you may follow the above procedure and end up with glyphs still missing in the generated PDF.
The standard XEP configuration file is created in user_preferences_dir/xep/xep.conf.

Using in XSL Utility an existing XEP configuration file

	Using in XSL Utility an existing XEP configuration file
The location of an existing RenderX XEP configuration file may be specified to XSL Utility by the means of Java™ system property or environment variable `XXE_XEP_CONFIG`. The value of this variable is an URL or an absolute file path. Examples: `-DXXE_XEP_CONFIG=http://localhost/~john/xep/xep.conf` (Java™ system property), `set XXE_XEP_CONFIG=C:\Users\john\misc\xep\xep.conf` (Windows environment variable).

The location of an existing RenderX XEP configuration file may be specified to XSL Utility by the means of Java™ system property or environment variable XXE_XEP_CONFIG. The value of this variable is an URL or an absolute file path. Examples: -DXXE_XEP_CONFIG=http://localhost/~john/xep/xep.conf (Java™ system property), set XXE_XEP_CONFIG=C:\Users\john\misc\xep\xep.conf (Windows environment variable).