XSL Formatter V3.4 - Command-line Interface

The Command-line Interface is provided as an executable file. You can call it from either a Windows batch file or a Solaris/Linux/Macintosh/HP-UX/AIX shell script.

XSL Formatter V3.4 can be executed from the Command-line Interface by:

Specifying an FO (XSL Formatting Objects) files to be formatted and the destination of the formatted file.
Specifying an XML and XSL file which automatically starts transformation with XSLT, then formatting and finally outputting.
As a filter that reads FO from standard in and writes PDF to standard out.

Executable File Name

The executable file names are as follows:

Windows	XSLCmd.exe
Solaris/Linux/Macintosh/HP-UX/AIX	XSLCmd

Environment Variables have to be set in order to execute these files. For Windows version these are automatically set by the installer. For the Solaris/Linux/Macintosh/HP-UX/AIX versions they have to be set. Please refer to Environment Variables.

Running Command-line program on Windows

To run the command-line program of XSL Formatter V3.4 for Windows, enter the following command.

> cd [Install directory]
> XSLCmd -d samples\sample.fo -o \tmp\sample.pdf

If XSL Formatter V3.4 for Windows is successfully installed, the following message will be displayed.

XSLCmd : XSL Formatter V3.4 R1 Copyright (c) 1999-2005 Antenna House, Inc.
XSLCmd : Formatting finished normally.

Then you can view sample.pdf in the \tmp directory.

Running Command-line program from a shell script

On XSL Formatter V3.4 for Solaris/Linux/Macintosh/HP-UX/AIX, the installation program will place the shell script file named run.sh in the [Install directory]. This is a sample shell script for running the command-line program XSLCmd. This script sets the necessary environment variables in script, and runs XSLCmd. To run the command-line program of XSL Formatter V3.4 for Solaris/Linux/Macintosh/HP-UX/AIX using this script, enter the following command from your terminal window.

$ cd [Install directory]
$ ./run.sh -d samples/sample.fo -o /tmp/sample.pdf

If XSL Formatter V3.4 for Solaris/Linux/Macintosh/HP-UX/AIX is successfully installed, the following message will be displayed. Then you can get sample.pdf in /tmp directory.

XSLCmd : XSL Formatter V3.4 R1 Copyright (c) 1999-2005 Antenna House, Inc.
XSLCmd : Formatting finished normally.

The same parameters in the same formats apply to both XSLCmd and run.sh.

Command-line Parameters

The following parameters apply to the Command-line Interface:

Parameter	Functions
-d XML-Document	Specifies the URI of the target XML/FO document to be formatted. When -d @STDIN is specified, FO document is loaded from standard in. The document loaded from standard in is supposed to be an FO file. If this parameter is omitted, a simple Command-line error message appears and processing stops without formatting.
-s XSL-Stylesheet	Specifies the URI of the target XSL document. If the specified XML document is FO or the XML file contains the processing instruction and a stylesheet is specified in the file, this parameter is ignored. Otherwise if there is no setting of this parameter, an error occurs. An XSLT processor is necessary to use XSL stylesheets. In the Windows version, MSXML4 or MSXML3 is used as the standard XSLT processor. If you want to use another XSLT processors or in Solaris/Linux/Macintosh/HP-UX/AIX version, you need to set which XSLT processor you are going to use. Setting the XSLT processor is performed by "Environment Variables" or "Option Setting File".
-o Output-File	Specifies the path name of the resulting output file. When -o @STDOUT is specified, it is considered as standard out. If both the printer name and this property are specified, the formatted result will be stored in the file using the printer driver. When -p @PDF or -p @TEXT or etc. is specified, the resulting PDF or text will be stored in the file specified by this parameter. If this parameter is omitted, it is considered as standard out.
-i Option-Setting-File	Specifies the path name of "Option Setting File" which defines XSL Formatter V3.4 options in XML-format. Any number of these parameters can be specified. If the content of this file is changed it overwrites the previous settings. Because only the described parameter in Option Setting File is evaluated, it is possible to change a part of setting by adding the file that describes parameters that should be changed. If the same parameter is specified in both the Option Setting File and the Command-line, and the value is different, the Command-line takes precedence.
-p Printer-Name	Specifies the printer name where the formatted result is outputted . If it is omitted, -p @PDF is automatically specified. When -p @STDPRN is specified, the standard printer is used. When -p @PDF is specified, the formatted result is not output to a printer but rather to PDF. When -p @SVG is specified, the formatted result is output as SVG. When -p @TEXT is specified, the formatted result will be outputted to the file as text format. no-LT When -p @AreaTree is specified, the AreaTree will be outputted. no-LT The printer name can only be specified with the Windows version. For printer name, please refer to "How to specify the Printer Name". Please refer to "PDF Output" for the PDF output. Please refer to SVG Output for the SVG output. Please refer to "Text Output" for the text output. @TEXT and @AreaTree is not effective with XSL Formatter V3.4 Lite.
-start Start-Page -end End-Page	Specifies the start page and the end page of output document. If the start page is omitted or the specified value is 0 or less, the start page is considered the first page. If the end page is omitted or the specified value exceeds the actual page number, the end page is considered the last page. If the setting is inconsistent, (for example, -start 5 -end 3) an error occurs. When -multivol parameter is specified, the value does not mean the page number but the separate volume number. For example -start 3 outputs the third separate volume.
-multivol	Specifies to output PDF in separate volume. The error occurs when FO doesn't include the axf:output-volume-info extension property. When this parameter is specified, -start/-end can be specified as the unit of separate volume.
-base BaseURI	Specifies the default base URI.
-param name=value	Specifies the parameter name and the value of xsl:param. If the value contains a white space, please specify "name=value". -param can be specified multiply.
-fontalias name=substname	Specifies font substitutions. If the option -fontalias A=B is specified, all of the font family-name A in the FO file will be substituted by B. If you are going to specify multiple substitutions, please specify the -fontalias parameter per substitution. You can also specify this option using the "Option Setting File". The substitution is not recursive, in other words substitution is done only once.
-extlevel Error-Level	Permits setting the error level at which XSL Formatter V3.4 will stop formatting and abort the job. Information Warning Recoverable Error Fatal Error The default value is 2. Thus if an error occurs and the error level is "warning" or higher, the formatting process will be aborted. If a fatal error occurs, the formatting process will be aborted unconditionally.
-silent	Suppresses the output of error information. Normally error information is sent to stdout or stderr.
-stdout	Error information is sent to stdout if this parameter is specified. It is outputted to stderr by default.
-stderr	Error information is sent to stderr if this parameter is specified. It is outputted to stderr by default.
-v	Shows the version, copyright and license information. Cannot be used with any other parameter.
-h or -?	Displays a list of all the Command-line parameters.

Parameters for Printer

Parameter	Functions
-ps Printer-Setting-File	Specify the path name of the Printer Setting file. Please refer to "How to create a Printer Setting file".
-copies Copies	Specifies the number of copies when outputting to a printer. Default value is 1.
-collate -nocollate	This parameter is effective only when multiple copies to be output. When -nocollate is specified, the same page is continuously printed as multiple copies. When -collate is specified, the print from the specified starting page to the end page is repeated.

Parameters for PDF Output

Parameter

Functions

-pdfver Version

Specifies PDF version:

1.3
1.4 (default)
1.5

-encrypt Key-Length

Specifies the key length when encrypting the PDF file during outputting. The key length can be specified as either 40 or 128 (bit). This parameter is effective only when you specify PDF1.4 or later with PDF version (-pdfver).

-userpwd Password

Specifies the user password for PDF. The password must be within 32 bytes.

-masterpwd Password

Specifies the master password for PDF. The password must be within 32 bytes.

-npt

Prohibits printing the PDF file.

-ncg

Prohibits making changes of the PDF file.

-ncc

Prohibits copying the content of the PDF file.

-nca

Prohibits adding comments and form fields to the PDF file.

-nff

Prohibits filling in of form fields and signing of the PDF file. This parameter is effective only when you specify PDF1.4 or later to PDF version (-pdfver). In order to make this parameter effective, the setting of the other parameters may be required. See also the 'PDF Reference' from Adobe Systems Incorporated for more details.

-nab

Prohibits text access for screen reader devices of the PDF file. This parameter is effective only when you specify 1.4 or later with PDF version (-pdfver).

-nad

Prohibits inserting, deleting and rotating the PDF pages. This parameter is effective only when you specify 1.4 or later with PDF version (-pdfver).

-pea

Embeds all embeddable fonts when creating PDF.

-pee Fontname

Embeds the specified font in the PDF. If you want to specify plural fonts, put commas between fonts.

-pef

An error is not issued when font embedding fails.

-peg

An error is not issued when glyphs are missing.

-ppa Value

Specifies whether to permit printing PDF to create with one of the following values. This parameter is effective only when you specify 1.4 or later with PDF version.

0.	Not Allowed
1.	Low Resolution Printing
2.	High Resolution Printing

-pic Value

Selects how to compress the color images embedded in PDF following.

0.	Auto
1.	JPEG compression
2.	ZLIB compression
3.	JPEG2000 compression

-picg Value

Selects how to compress the grayscale images embedded in PDF.

0.	Auto
1.	JPEG compression
2.	ZLIB compression
3.	JPEG2000 compression

-picm Value

Selects how to compress the monochrome images embedded in PDF.

0.	None
1.	CCITT Group4
2.	CCITT Group3
3.	Run Length compression
4.	ZLIB compression

-pjq Percent

Specifies the quality of the raster graphics when stored in JPEG format using the range of 1-100(%). The quality becomes higher in proportion to the increase in the number; however the file size also becomes larger. The initial value is 80.

-pcs

Specifies not to compress text and line art in PDF.

-plr
-noplr

Specifies whether the external link specified by the relative address is transformed into 'Open the file' or into 'World Wide Web link' in the PDF link properties. When -plr is specified, it is transformed to 'World Wide Web link'. When -noplr is specified, it is transformed to 'Open the file'.

-prc Value

Specifies how to convert the RGB color space (DeviceRGB) to DeviceGray.

0.	No Conversion
1.	Black to DeviceGray
2.	Gray to DeviceGray
3.	All RGB to DeviceGray

-prr dpi

Specifies the value of the rasterized-resolution of the transformed raster images in the range from 70 to 500(dpi). This parameter is available only in the Windows version.

-lpdf
-nolpdf

When -lpdf is specified, generates linearized PDF. When -nolpdf is specified, generates non-linearized PDF. no-LT

Parameters for SVG Output

Parameter

Functions

-svgver Profile

Specifies the SVG profile:

1.1 (default)
Basic
Tiny

-svgip Method

Specifies how to treat images within the SVG file.

0.	Embeds all image files.
1.	Copies all image files to the destination that is specified by -svgicp, and then links.
2.	Links images that can be linked and embeds images that have to be embedded. Raster images other than JPEG and PNG are always embedded.
3.	Copies images that have been linked to the destination that is specified by -svgicp and links.

If this parameter is omitted, it is considered as 0 and all images are embedded. Refer to Image Output in SVG Output for details of operation.

-svgicp Directory

Specifies the destination to copy images to as specified in 1 or 3 for -svgip parameter. When a relative path is used to specify the Directory, outputted is to the relative path from the specified output path by the -o parameter. When -o is the standard output, an error will occur if the relative path is specified. Then it is necessary to specify an absolute path.

-svgiren

Specifies whether to rename all file names to the prefix specified by -svgiprfx, or use original name when images are copied to the directory specified by -svgicp. When the file name overlaps, a sequential number is added. When -svgiren is specified, all files are renamed.

-svgiprfx Prefix

When images are copied to the directory specified by -svgicp, specifies the prefix of the file name. The file name will be prefixed followed by sequence number. When it is not specified, they are only sequential numbers.

-svggzip

Outputs SVG compressed in gzip.

-svgsingle

The document composed of multiple pages is outputted as a single SVG file.

-svgfmt Format

When the original document has multiple pages and -svgsingle parameter is not specified, each page will be output as an SVG files that has a consecutive number at the end of the file name. This parameter specifies the format of those consecutive numbers. For example, when "document.svg" is specified as the name for the output file, by specifying "-01" for -svgfmt parameter the output files will be document-01.svg, document-02.svg and so on. If this parameter is omitted, "1" is considered as specified.

-svgspn

When -svgsingle is not specified and output SVG has only one-page, the sequential number specified by -svgfmt is not added.

-svgea

Embeds all fonts that can be embedded in the SVG.

-svgee Font-Name

Embeds the specified font in SVG. If you want to specify plural fonts, put commas between fonts.

-svgef

An error is not issued when font embedding fails.

-svgic Value

Selects how to convert the raster images which may not be embedded in SVG directly.

0.	Auto
1.	JPEG conversion
2.	PNG conversion

When Auto is selected monochrome, grayscale or 256-or-less-color images are converted into PNG and the rest are converted into JPEG. When this parameter is omitted, the default is Auto. As for the image that can be stored directly, refer to Image Output in SVG Output.

-svgjq Percent

Specifies the quality of the raster graphics, when it is specified as JPEG for -svgic, using the range of 1-100(%). The quality becomes higher in proportion to the increase in the number; however the file size also becomes larger. The initial value is 80.

-svgrr dpi

Specifies the value of the rasterized-resolution of the transformed raster images in the range from 70 to 500(dpi). This parameter is available only in the Windows version.

Parameters for Text Output

Parameter	Functions
-tenc Encoding	Specifies the encoding for Text Output. If this parameter is omitted, UTF-8 is adopted. See also Text Output Setting for more detail.
-teol EOL-mark	Specifies the end-of-line code for Text Output. If this parameter is omitted, CRLF is adopted. See also Text Output Setting for more detail.

When specifying a path name that contains a space the path name must be enclosed in double quotation marks. When the same parameter or a contrary parameter is specified, the last specified becomes effective.

The following sample illustrates formatting sample.xml using XSL stylesheet sample.xsl and outputting the formatted result to sample.pdf.

XSLCmd -d "c:\My Documents\xml\sample.xml" -s "c:\My Documents\xml\sample.xsl" -p @PDF -o "c:\My Documents\xml\sample.pdf"

In order to use the stylesheet in the non-Windows environment, it's necessary to specify external XSLT prosessor in the Option Setting File using -i parameter.

The following sample illustrates how to load the Option Setting File options.xml, format sample.fo and send the formatted result to a printer.

XSLCmd -d "c:\My Documents\xml\sample.fo" -i "c:\My Documents\xml\option.xml" -p "EPSON LP-7100"

Return Value

When executing formatting with the Command-line Interface, if the formatting is successfully performed, it finishes the process with the return value of 0. If the formatting is not successful, it finishes the process with the return value of 1. If the formatting is not done by specifying -v, the return value is 0.

How to specify the Printer Name

The followings parameter settings apply only to the Windows version.

To send a file to a printer use the printer name that is specified in the list of installed printers in the Printers dialog in the Windows start menu or Printers and Faxes in the Control Panel.

-p "Acrobat Distiller"
-p "EPSON LP-7100"

[Printer Window]

How to create a Printer Setting file

The followings are effective only in the Windows version.

In the Windows environment, applications use the DEVMODE structure to exchange information about the printer settings. Also Windows printer drivers initialize themselves according to the information of the DEVMODE structure. XSL Formatter V3.4 provides XSLDev.exe as a utility to save the DEVMODE structure to a file.

When this program is launched, the "Print Setup" dialog will be displayed. You can choose printers from "Name" combo box or you can set various printer properties by clicking the "Properties" button. After you set up printer properties, click "save" button, the "Save As" dialog will be displayed. Specify a file name to save the print setup to. This will then modify DEVMODE structure as a "data file that records printer setup." You can specify this file name for the PrinterSetting property of the .NET/COM Interface or -ps Parameter of the command line interface or other interfaces. To quit this application, click "close" button.

[PrinterSetting dialog]

When a printer setting file is specified, a document is printed unless -p option is specified. The following shows how it operates.

XSLCmd -p printer-name -ps setting-file -d ...
Prints a document by applying DEVMODE specified in the setting-file to the printer-name.
XSLCmd -p @PDF -ps setting-file -d ...
Outputs a document to PDF disregarding the -ps option.
XSLCmd -ps setting-file -d ...
Prints a document using the DEVMODE specified in the setting-file. If the printer-name is not specified in DEVMODE, the default printer is used.

When -collate or -copies is specified, the content of DEVMODE is overwritten.

The printer setting file created by XSL Formatter V2.5 AXFODEV.exe can be used with XSL Formatter V3.4 without change.

Restrictions for Printing

See also restrictions in the Graphical User Interface.