Using the Command Line

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

4.1. Running IREn

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

On all platforms, by invoking Java directly from the command line.
On Windows, IREn can be run from a Command Prompt window via the xep.bat batch file.
On Linux, MAC, and UNIX, IREn 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 IREn is run via Java, via a Windows batch file, or via a Linux/MAC shell script.

4.2. IREn Options

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

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

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

Table 4.1. Customizing IREn Configuration

Customization Description Syntax

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 IREn Assistant.	For editing `xep.xml` in a text editor, see Section 5.2. For the IREn Assistant, see Section 5.1.
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 IREn 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>`

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 IREn Assistant.

For editing xep.xml in a text editor, see Section 5.2.

For the IREn Assistant, see Section 5.1.

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

4.3. IREn Switches

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

Table 4.2. IREn Switches

Switch	Description
`-help`	Displays the detailed syntax of the IREn switches and arguments.
`-hosted`	The Java Virtual Machine continues to run after the renderer has completed rendering the file.
`-quiet`	By default, IREn 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; IREn 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 IREn rendering engine.

4.4. IREn Arguments

The IREn arguments instruct IREn 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 IREn arguments are described in the following table.

Table 4.3. IREn 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 IREn file, generated previously using the at output format. The IREn 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 IREn 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. Alternatively the XSL stylesheet can be specified in the XML file itself using `<?xml-stylesheet>` processing instruction. This processing instruction must be placed at the beginning of an XML file before document root element. Ex: `<?xml version="1.0" encoding="UTF-8"?> <?xml-stylesheet type="text/xsl" href="<stylesheet>"?> <root> ...`
`-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: IREn, PDF, PostScript (PS), AFP, SVG, XPS, XHTML and PPML. `at` — Internal IREn 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. `svg` — SVG format. `xps` — XPS format. `html` — XHTML format. `ppml` — PPML format. PPML is Personalized Print Markup Language for high-volume and full-color variable data printing. PPML is an open industry standard that uses an XML grammar to define how to compose digital assets into objects, pages, documents, and sets. `ps` — PostScript format. PostScript is useful when preparing a file to send to a printing service provider. `xep` — Internal IREn 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.

4.5. Examples of Running IREn from the Command Line

This section presents a number of examples of how to run IREn 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 4.31.529 build 20230101
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), xep (XEP), pdf (PDF), ps (Postscript),
afp (AFP), svg (SVG), xps (XPS),  html (XHTML), ppml (PPML).

To view the version of IREn you are currently running:

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.31.529 build 20230101
(document [system-id file:stdin]
```
Press <Ctrl> + <C> to exit IREn 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

Download the complete IREn User Guide as PDF