XEP User Guide/Using the Command Line

From Docs

Jump to: navigation, search

Get PDF

This topic describes how to run XEP from the command line.

Contents

Running XEP

XEP can be run from the command line, as follows:

  • On all platforms, by invoking Java directly from the command line.
  • On Windows, XEP can be run from a Command Prompt window via the xep.bat batch file.
  • On Linux, MAC, and UNIX, XEP can be run from a command shell, via the xep bash script.

To learn more about the xep.bat batch file or the xep bash script, open the file in a text editor. These files use standard scripting features available in the operating system.

The syntax of the Java command is:
java com.renderx.xep.XSLDriver {options} {switches} {arguments}

The above syntax has been simplified by assuming that the directory containing the Java executable is specified in your PATH environment variable, and that the full path of the xep.jar file is in your CLASSPATH environment variable. If you specify an XSL file to convert an XML source document into XSL-FO, then it is assumed that saxon.jar or xt.jar are also specified in your CLASSPATH environment variable.

The syntax of the Windows batch and Linux/MAC shell command is:
xep {options} {switches} {arguments}

The above syntax assumes that the full path to the Windows batch file xep.bat or the Linux/MAC shell script xep 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 options, switches, and arguments are the same whether XEP is run via Java, via a Windows batch file, or via a Linux/MAC shell script.

XEP Options

The XEP options are used to configure and customize the behavior of the XEP rendering engine.

XEP requires a configuration file in order to run. By default, the formatter looks for a file named xep.xml in the current directory. If a different configuration file is used, the path to the configuration file must be specified on the command line.

XEP is a flexible tool in which the configuration can be customized according to your preferences. There are several methods to customize XEP. These methods are summarized in the following table:

Customizing XEP Configuration
Customization Description Syntax
Editing the configuration file. The xep.xml configuration file can be customized, thereby customizing all transformations. There are two ways to customize the file:
  • Edit the xep.xml file in a text editor.
  • From the Options tab in the XEP Assistant.
For editing xep.xml in a text editor, see Configuring XEP via the XEP Configuration File . For the XEP Assistant, see Configuring XEP using XEP Assistant.
Setting a custom configuration file. You can set a custom configuration file in the command line for a single file transformation. The location of the custom configuration file can be specified as either a file name in the local file system or as a URL. All subsequent file transformations will continue to use the standard xep.xml file. -DCONFIG=<CUSTOM_FILE_PATH>
Customizing the XEP configuration through the command line. In the command line, the configuration can be customized for a single file transformation. The xep.xml file is not changed, and all subsequent file transformations are not affected.

Note: It is possible to specify multiple options in the same command line.

Note: If there is a contradiction between the configuration file and the customization through the command line, the command line overrides the settings specified in the configuration file.

-D<OPTION_NAME>=<OPTION_VALUE>


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

XEP Switches

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

XEP Switches
Switch Description
-help Displays the detailed syntax of the XEP switches and arguments.
-hosted The Java Virtual Machine continues to run after the renderer has completed rendering the file.
-quiet By default, XEP writes detailed messages to the command line console. 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.

-valid The validation is turned off; XEP does not validate the input when rendering.

Note: The rendering runs faster, but since the XML source is not validated, there is a chance that the output will not be correct.

-version Displays detailed version information of the XEP rendering engine.

XEP Arguments

The XEP arguments instruct XEP how to process a file. For example, arguments may specify the input file, the target format to render to, and the output filename. When multiple arguments are specified, they must be specified in the following order:
( [-xml] <infile> [-xsl <stylesheet>] {-param <name=value>}
         | -fo <infile>
         | -xep <infile> )
[-format]
[[-<output format>] <outfile>]

The XEP arguments are described in the following table.

XEP Arguments
Argument Description
-xml The specified input file is an XML source document. When the input file is an XML document, this argument may be omitted.
-fo The specified input file is an XSL-FO document ready to be rendered.
-xep The specified input file is an XEP file, generated previously using the at output format. The XEP file is an XML document that is an internal representation of the rendered document.
<infile> Specifies the input file. This argument is required.
-xsl <stylesheet> Specifies the XSL stylesheet XEP must use to transform the input XML document into XSL-FO. <stylesheet> is the path (absolute or relative to the working directory) of the XSL stylesheet.
-param <name=value> If the XSL stylesheet supports global parameters, they can be set via the -param argument. Each XSL parameter you want to set on the command line requires a separate -param argument.
-<output format> Specifies the output format to render to. Available output formats are: XEP, PDF, PostScript (PS), and AFP.
  • at — Internal XEP format. This is an XML file that represents the rendered document.
  • pdf — PDF format. This is the default output format if no output format is specified.
  • afp — AFP format. AFP is an architecture standard for High Volume Transaction Output supported by vendors of printing equipment.
  • ps — PostScript format. PostScript is useful when preparing a file to send to a printing service provider.
  • xep — Internal XEP format (same as at ).
-format Another way of specifying the output format.
-<outfile> Specifies the path and name of the output file. If no output file is specified, the default output file is the same file path and name as the input file with the extension corresponding to file format.

Examples of Running XEP from the Command Line

This section presents a number of examples of how to run XEP from the command line.

To list all available options and switches:

  • At the system prompt, enter:
    xep -help. A list of all available commands is displayed.
    c:\myfiles>xep -help
    XEP build 20080425
    java com.renderx.xep.XSLDriver
           {<option>}
           {-quiet | -version | -valid | -hosted | -help}
           ( [-xml] <infile> [-xsl <stylesheet>] {-param <name=value>}
             | -fo <infile>
             | -xep <infile> )
           [-f]
           [[-<output format>] <outfile>]
    Available output formats: at (XEP), pdf (PDF), afp (AFP), ps (Postscript),
     xep (XEP).

To view the version of XEP you are currently running:

  1. At the system prompt, enter: xep -version. The version you are currently running as well as the build are displayed.
    c:\myfiles>xep -version
    XEP 4.13 build 20080814
    (document [system-id file:stdin]
  2. Press <Ctrl> + <C> to exit XEP interactive mode.

To render an XML document to PDF:

  • To render the XML document CommandLine.xml to PDF, using the stylesheet custom-fo.xsl to transform the XML to an XSL-FO document and relying on the default settings for the output format and output filename, at the system prompt, enter:

xep CommandLIne.xml -xsl custom-fo.xsl


Back to XEP User Guide

Personal tools