3.1. Using convertdoc
Prev | 3. The convertdoc command-line tool | Next

### 3.1. Using convertdoc

Usage:

    convertdoc [-t XSLT_stylesheet_file_or_URL]?
         [-r|-ru resource_name resource_value]*
         [-p|-pu XSLT_stylesheet_param_name XSLT_stylesheet_param_value]*
         -v? -d? [-auth credentials]*
         process_command_name doc_file_or_URL
         [-s|-u process_command_arg]*

or, secondary function:

    convertdoc -h [process_command_name]?

or, secondary function:

    convertdoc -l

or, secondary function:

    convertdoc -acd [file_or_URL]+
    convertdoc -rcd [file_or_URL]+
    convertdoc -cmp|-diff file_or_URL1 file_or_URL2

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:

`-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.

`-r|-ru `resource_name` `resource_value``

  Copy specified resource rather than the one specified in the `<copyProcessResources name="resource_name">` child element of the process command.

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

`-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.

Advanced options:

`-v`|`-vv`|`-vvv`

  Turn verbosity on. The more Vs, the more verbose.

`-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/xxe`NNNN`/`) at the end of the processing.

`-auth `credentials``

  This option can be used to specify authentication credentials for a given server. This allows to connect to the specified server without interactively asking the user to enter a username and a password.

  String `credentials` consists in 6 fields: `host`, `port`, `prompt`, `scheme`, `username`, `password`, in that order, separated by a newline character (`'\n'`). Fields `host`, `port`, `prompt`, `scheme` can be left empty, which means: match any. The UTF-8 bytes of the string are then encoded in base-64.

  Command-line utility "`java -cp xxe.jar com.xmlmind.netutil.SimpleAuthenticatorModule`" allows to generate such encoded string. Example: encode string "`\n\nDocument Store\n\nvictoria\nsecret`":

      /opt/xxe/bin$ java -cp xxe.jar com.xmlmind.netutil.SimpleAuthenticatorModule \
      victoria secret - "Document Store"
      CgpEb2N1bWVudCBTdG9yZQoKanZpY3RvcmlhCnNlY3JldA==

      /opt/xxe/bin$ convertdoc -auth CgpEb2N1bWVudCBTdG9yZQoKanZpY3RvcmlhCnNlY3JldA== \
      docb.toHTML http://www.acme.com/docstore/push_up.xml -u docs/

Secondary functions:

convertdoc `-h [`process_command_name`]?`

  Print the names of all documented process commands and exit. If a process command name has been specified, print a short help text describing how to invoke this process command.

  ### Tip

  This integrated help facility allows to quickly learn how to invoke a given process command and this, without having to look at the “XML source code” of this process command. Example:

      $ convertdoc -h
      db5.toEclipseHelp
      db5.toEpub
      db5.toHTML
      ...
      xhtml.toPSPrinter
      xhtml.toRTF

      $ convertdoc -h db5.toHTML
      convertdoc [options] db5.toHTML docbook_file_or_URL \
        -u output_dir_filename_or_URL

        Convert DocBook document docbook_file_or_URL to multi-page HTML.
        Create the HTML pages in directory output_dir_filename_or_URL.

        Example:
        convertdoc db5.toHTML doc.xml -u out/

convertdoc `-l`

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

convertdoc `-acd` `[`file_or_URL`]+`

  Activate change detection in specified XML documents. This implies adding a processing-instruction `<?xxe-serial-numbers>` at the end of a document and then saving the modified document to disk.

  No effect if change detection is already activated in a document.

  `file_or_URL` may specify a local directory, in which case this directory is recursively traversed.

convertdoc `-rcd` `[`file_or_URL`]+`

  Deactivate change detection in specified XML documents. This implies removing a processing-instruction `<?xxe-serial-numbers>` from the end of a document and then saving the modified document to disk.

  No effect if change detection is already deactivated in a document.

  `file_or_URL` may specify a local directory, in which case this directory is recursively traversed.

convertdoc `-cmp` ``file_or_URL1`` ``file_or_URL2``

  Compare specified XML documents. If these documents differ, print the changes on the console.

  The documents being compared must be two revisions of the same initial document in which change detection has been activated.

  The arguments may specify two local directories, in which case these directories are recursively traversed in parallel.

convertdoc `-diff` ``file_or_URL1`` ``file_or_URL2``

  Same as `-cmp` except that changes are not detailed. If one or more XML documents differ, convertdoc exits with a non-zero exit code.

Prev | Up | Next
3. The convertdoc command-line tool | Home | 3.2. Example 1: convert a DocBook document to multi-page HTML