3. The convertdoc command line tool

3. The convertdoc command line tool
Prev	Chapter 5. Process commands	Next

The convertdoc tool allows to execute XXE process commands from the command line, exactly as if these process commands were executed from XXE.

Just like XXE, the convertdoc command line tool scans directories for configurations and XML catalogs, loads image toolkit plug-ins, loads XSL-FO processor plug-ins, supports XInclude, etc.

Usage:

convertdoc -l

or:

convertdoc ?-v? ?-t XSLT_stylesheet_file_or_URL?
     ?-p|-pu XSLT_stylesheet_param_name XSLT_stylesheet_param_value? ...
     ?-p|-pu XSLT_stylesheet_param_name XSLT_stylesheet_param_value?
     process_command_name doc_file_or_URL
     ?-s|-u process_command_arg? ... ?-s|-u process_command_arg?

Converts XML document doc_file_or_URL using process command called process_command_name, found in any of the XXE configuration files scanned during the startup of convertdoc (see XMLmind XML Editor - Configuration and Deployment).

Options:

-l

Print XXE configuration (XXE configuration files but also XML catalogs, plug-ins, spell-checker dictionaries, CLASSPATH) and exit.

-v

Turn verbosity on.

-d

Sets the debug attribute of the process command to value true (no matter what has been specified in the process element).

This prevents the process command from deleting its work directory (/tmp/xxeNNNN/) at the end of the processing.

-t XSLT_stylesheet_file_or_URL

Use this alternate XSLT style sheet instead of the one specified in the first transform child element of the process command.

If specified process command has no transform child element but has subProcess child elements, these sub-processes are searched recursively for a transform child element.

-p|-pu XSLT_stylesheet_param_name XSLT_stylesheet_param_value

Add/replace corresponding XSLT style sheet parameter in the first transform child element of the process command.

-pu is useful when the parameter value is a relative filename that needs to be converted to an absolute "file:" URL.

If specified process command has no transform child element but has subProcess child elements, these sub-processes are searched recursively for a transform child element.

-s|-u process_command_arg ... -s|-u process_command_arg

Pass these arguments to the process command as the values of process variables %0, %1, ..., %9.

If -s (String) is specified, the argument is passed as is.

If -u (URL) is specified, the argument, a file or directory name, is first converted to an URL.

About convertdoc and user authentication

Most remote document repositories (e.g. WebDAV servers) will require the user of convertdoc to authenticate herself/himself.

Convertdoc being a command-line tool designed to be used in makefiles, batch files, shell scripts, etc, authentication by the means of an interactive dialog with the user is not a solution. That's why convertdoc automatically uses the credentials stored by XMLmind XML Editor in the preferences file of the user.

Example:

User john needs to run convertdoc to convert http://www.acme.com/docs/foo.xml to HTML.

Server http://www.acme.com/docs/ requires user john to authenticate himself.

User john starts XMLmind XML Editor and opens http://www.acme.com/docs/foo.xml.

A dialog box is displayed prompting user john for his credentials.

User john types his user name and password and, by checking the "Remember these user name and password" checkbox, allows XMLmind XML Editor to store the credentials in XXE_user_preferences_dir/preferences.properties.

From then, user john may run convertdoc to convert any document stored on http://www.acme.com/docs/.

Prev	Up	Next
2.3. Convert ImageDemo document to HTML	Home	3.1. Example 1: convert a DocBook document to multi-page HTML