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 Linux / Solaris / Macintosh shell script.

AH Formatter V6.3 can be executed from the Command-line Interface by:

Executable File Name

The executable file names are as follows:

WindowsAHFCmd.exe
Linux / Solaris / MacintoshAHFCmd

Environment Variables have to be set in order to execute these files. In the Windows version these are automatically set by the installer. In the non-Windows versions they have to be set. Please refer to Environment Variables.

Running Command-line program on Windows

To run the command-line program of AH Formatter V6.3 for Windows, enter the following command.

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

If AH Formatter V6.3 for Windows is successfully installed, the following message will be displayed.

AHFCmd : AH Formatter V6.3 XX for Windows (XXXX/XX/XX XX:XX:XX)
         Copyright (c) 1999-20XX Antenna House, Inc.
AHFCmd : Formatting finished normally.

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

Running Command-line program from a shell script

In AH Formatter V6.3 for non-Windows, 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 AHFCmd. This script sets the necessary environment variables in the shell, and runs AHFCmd. To run the command-line program of AH Formatter V6.3 for non-Windows 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 AH Formatter V6.3 for non-Windows is successfully installed, the following message will be displayed. Then you can get sample.pdf in /tmp directory.

AHFCmd : AH Formatter V6.3 XX for Xxxxxx (XXXX/XX/XX XX:XX:XX)
         Copyright (c) 1999-20XX Antenna House, Inc.
AHFCmd : Formatting finished normally.

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

Command-line Parameters

The following parameters apply to the Command-line Interface: Parameters with * in the following table indicate a negative meaning if no is placed in the beginning of the command. For example, -nomultivol cancels to output PDF in separate volume.

When specifying a path name that contains a space, the path name must be enclosed in double quotation marks. If two conflicting parameters are specified, the last parameter on the line takes precedence.

The default parameter can be specified with the environment variable. The setting with the environment variable is compensated before the parameter specified here and being evaluated. This feature does not function with AH Formatter V6.3 Lite.

Parameter Default Functions
-d Document Specifies the URI of the target XML/FO/HTML 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 Stylesheet Specifies the URI of the target XSL/CSS document. If the specified XML document is FO, or the XML file contains the processing instruction <?xml-stylesheet ...?> and the stylesheet is specified, or the specified document is HTML, there is no need to specify a stylesheet.
An XSLT Processor is necessary to use XSL stylesheets. In the Windows version, MSXML is used as the standard XSLT Processor. If you want to use another XSLT Processors or in non-Windows 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".
If the specified document is CSS, it will be the last user stylesheet. It is applied posterior to the stylesheet added by -css and the Option Setting File specified by -i.
-f Formatter-Type AUTO Specifies the formatter type from the following:
  • AUTO
  • HTML
  • XHTML
  • XMLCSS
  • XSLFO
If this parameter is omitted or invalid, it is considered as AUTO.
-css User-Stylesheet Specifies the CSS user stylesheet you want to add. -css can be specified any number of times. It is applied by specified order prior to the stylesheet specified by -s.
-htmlcs Default-HTML-Charset UTF-8 Specifies the default encoding of HTML. This setting is applied to HTML whose encoding is unknown. If this parameter is omitted, UTF-8 is considered as default.
-o Output-File @STDOUT Specifies the path name of the resulting output file.
  • When -o @STDOUT is specified, the result is written to 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, the result will be written to standard out.
-i Option-Setting-File Specifies the path name of "Option Setting File" which defines AH Formatter V6.3 options in XML-format. Any number of these parameters can be specified. If any content of this file is changed it automatically overwrites the previous settings. Because only a described parameter in the Option Setting File is evaluated, it is possible to change a part of setting by adding a file that describes those parameters that should be changed. If conflicting values for a parameter are specified in the Option Setting File and the Command-line, the last specified value overwrites the previous value.
-ix Imports AHFSettings.xml (AHFSettings(x64).xml for Windows x64 version) in the application data directory indicated as the environment variable APPDATA as the Option Setting File. This parameter is equivalent to
-i "[APPDATA]\AntennaHouse\AHFormatter\6.3\AHFSettings.xml"
or
-i "[APPDATA]\AntennaHouse\AHFormatter\6.3\AHFSettings(x64).xml"
Effective only for Windows version.
-p Printer-Name @PDF Specifies the printer name where the formatted result is outputted If this parameter 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 @PS is specified, the formatted result is output as PostScript.
  • When -p @XPS is specified, the formatted result is output as XPS.
  • When -p @INX is specified, the formatted result is output as INX.
  • When -p @MIF is specified, the formatted result is output as MIF.
  • 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
A printer name other than the printer names above cannot be specified in non-Windows version. For details about specifying the printer name, please refer to How to specify the Printer Name.
Please refer to "PDF Output" for PDF output info.
Please refer to "SVG Output" for SVG output info.
Please refer to "PostScript Output" for PostScript output info.
Please refer to "XPS Output" for XPS output info.
Please refer to "INX Output" for INX output info.
Please refer to "MIF Output" for MIF output info.
Please refer to "TEXT Output" for text output info.
@TEXT and @AreaTree are not effective with AH Formatter V6.3 Lite.
-start Start-Page 1 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 0, 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.
-end End-Page 0
-2pass * When formatting a huge document with a large amount of unresolved <fo:page-number-citation>, a large amount of memories are consumed because the cancellation of the page information is impossible. Therefore, the limit is caused in the number of pages to format. This parameter solves that problem by making the formatting two passes. Although its processing time may be increased, only the page number information which should be solved will consume the memory and the memory consumption will be extremely decreased. Please refer to "Formatting Large Document". This setting is invalid with CSS formatting. no-LT
-dpw Length 210mm Specifies the default page width with a numerical value and its unit.
-dph Length 297mm Specifies the default page height with a numerical value and its unit.
-base BaseURI Specifies the default base URI.
-hypdic Directory Specifies the directory where the hyphenation dictionary exists.
-msxmlver version 0 Specifies the maximum version of MSXML used internally when msxml="true" is specified. Any version from 6 to 3 can be specified. For example, when 5 is specified, AH Formatter searches MSXML in order of MSXML5 → MSXML4 → MSXML3 and adopts the first found MSXML. If nothing is specified or the specified value is outside the range, the version will be regarded as 6. This setting is effective only with Windows version. V6.3
-param name=value Specifies the parameter name and the value of xsl:param used with the XSLT transformation. 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 font family-name A in the FO file will be substituted with font B. If you are going to specify multiple substitutions, you must specify the -fontalias parameter for every substitution. You can also specify this option using the "Option Setting File". The substitution is not recursive, or is done only once.
-x Error-Level 2 Permits setting the error level at which AH Formatter V6.3 will stop formatting and abort the job.
  1. Information
  2. Warning
  3. Recoverable Error
  4. Fatal Error
If a fatal error occurs, the formatting process will always be aborted.
-silent Suppresses the output of error information. Normally error information is sent to stdout or stderr.
-stdout Error information is sent to stdout only if this parameter is specified. It is outputted to stderr by default.
-stderr Error information is also sent to stderr if this parameter is specified. It is outputted to stderr by default.
-pgbar * Outputs the progress of the page generation to the console. "." shows the progress of formatting, "-" shows the progress of the outputted page.
-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 Default Functions
-ps Printer-Setting-File Specifies the path name of the Printer Setting file. Please refer to "How to create a Printer Setting file".
-copies Copies 1 Specifies the number of copies when outputting to a printer. The default value is 1.
-collate * This parameter is effective only when outputting multiple copies. When -collate is specified, printing from the specified starting page to the ending page repeated. When -nocollate is specified, the same page is continuously printed as multiple copies.
-gdismooth Value 0 Specifies whether anti-aliasing is performed or not when printing. The sum of the following values can be specified.
  1. Text
  2. Line-Art
  3. Image

Parameters for PDF Output

Parameter Default Functions
-pdfver Version PDF1.5 Specifies the PDF version from the following:
  • PDF1.3
  • PDF1.4 (default)
  • PDF1.5
  • PDF1.6
  • PDF1.7
  • PDF/X-1a:2001 no-LT
  • PDF/X-3:2002 no-LT
  • PDF/X-1a:2003 no-LT
  • PDF/X-2:2003 no-LT
  • PDF/X-3:2003 no-LT
  • PDF/X-4:2008 no-LT
  • PDF/A-1a:2005 no-LT
  • PDF/A-1b:2005 no-LT
Impossible to specify PDF/X or PDF/A with AH Formatter V6.3 Lite.
-tpdf * Generates Tagged PDF. Ignored if PDF cannot be tagged depending on the PDF versions. no-LT
-lpdf * Generates linearized PDF optimized for the display on the Web. no-LT
-prevp * Outputs pages in reverse order.
-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.
-encrypt Key-Length 128rc4 Specifies the key length when encrypting the PDF file. The key length can be specified from the following: When the specified key length is not applicable with the version of the created PDF, the key length is adjusted to be applicable one.
  • 40rc4
  • 128rc4
  • 128aes
  • 256aes
128aes is effective with PDF1.5 or later, 256aes is effective with PDF1.7 or later.
-nemd * Prevents metadata from being encrypted when encrypting a PDF to be created. V6.3
-userpwd Password Specifies the user password required to open the PDF. The password must be less than or equal to 32 bytes.
-ownerpwd Password Specifies the owner password for PDF. The password must be within 32 bytes.
-npt * Prohibits printing the PDF file. Use -ppa when you specify PDF version 1.4 or later and -encrypt 40rc4 is not specified.
It is necessary to specify -ownerpwd so that this parameter is effective.
-ncg * Prohibits making changes of the PDF file.
It is necessary to specify -ownerpwd so that this parameter is effective.
-ncc * Prohibits copying the content of the PDF file.
It is necessary to specify -ownerpwd so that this parameter is effective.
-nca * Prohibits adding comments and form fields to the PDF file.
It is necessary to specify -ownerpwd so that this parameter is effective.
-nff * Prohibits filling in of form fields and signing of the PDF file. Ignored when you specify PDF1.3 or -encrypt 40rc4. In order to make this parameter effective, other parameter settings 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. Ignored when you specify PDF1.3 or -encrypt 40rc4.
It is necessary to specify -ncg so that this parameter is effective.
-nad * Prohibits inserting, deleting and rotating the PDF pages. Ignored when you specify PDF1.3 or -encrypt 40rc4.
It is necessary to specify -ncg so that this parameter is effective.
-ppa Value 2 Specifies whether to permit printing of the created PDF with one of the following values. Use -npt when you specify PDF version 1.3 or -encrypt 40rc4.
0.Not Allowed
1.Low Resolution Printing
2.High Resolution Printing
It is necessary to specify -ownerpwd so that this parameter is effective.
-peb Value 1 Specifies whether to embed the embeddable fonts in PDF or not with one of the following values.
0.Specified font
1.All fonts excluding Base14 font
2.All fonts including Base14 font
-pee Fontname Embeds the specified font in the PDF. If you want to specify multiple fonts, put commas between the fonts.
-pesub Percent 100% Embeds all fonts when the percent of characters used is greater than or equal to specified value, subsets embedded fonts when the percent of characters used is less than the specified value. The value without unit or % value can be specified. (1.0 = 100%). If nothing is specified, it is considered as 100% and embedded fonts are always subset.
-pef * An error is not issued when font embedding fails.
-peg * An error is not issued when glyphs are missing.
-pex * Prevents PDF/X and PDF/A outputs from being cancelled even when an error occurs while outputting them. no-LT
-pt Value all Specifies whether to embed the image in PDF as is (pass-through). If both pass-through and downsampling are specified, downsampling will precede pass-through. This does not apply when it is not possible to embed the image as is for a certain reason. The following strings can be enumerated by separating with a white space to specify the image type.
all
gif
tiff
png
jpeg
jpeg2000
jbig2
none
Excludes an image type by placing a hyphen (-) before the image type. For instance, when specifying "all -gif", only GIF can be excluded. V6.3MR1 no-LT
-picc Value 0 Selects how to compress the color images embedded in PDF.
0.Auto
1.JPEG compression
2.ZLIB compression
3.JPEG2000 compression
4.Keep LZW
This parameter is effective for images that cannot be directly embedded into a PDF or -pidc value is not 0. JPEG2000 is effective only for PDF1.5 or later.
-picg Value 0 Selects how to compress the grayscale images embedded in PDF.
0.Auto
1.JPEG compression
2.ZLIB compression
3.JPEG2000 compression
4.Keep LZW
This parameter is effective for images that cannot be directly embedded into a PDF or -pidg value is not 0. JPEG2000 is effective only for PDF1.5 or later.
-picm Value 1 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
This parameter is effective for images that cannot be directly embedded into a PDF or -pidm value is not 0.
-pidc Value 0 Selects how to downsample the raster color images embedded in a PDF with the following values.
0.None
1.Average
2.Bicubic
3.Subsampling
When -pidc value (other than 0) is specified, a color image that has a resolution greater than -pidca dpi will be downsampled to the -pidct dpi value.
-pidca dpi 450
-pidct dpi 300
-pidg Value 0 Selects how to downsample the raster grayscale images embedded in PDF using the following values.
0.None
1.Average
2.Bicubic
3.Subsampling
When -pidg value (other than 0) is specified, a grayscale image with resolution greater than -pidga dpi will be downsampled to the -pidgt dpi resolution.
-pidga dpi 450
-pidgt dpi 300
-pidm Value 0 Selects how to downsample the raster monochrome images embedded in PDF using the following values.
0.None
1.Average
2.Bicubic
3.Subsampling
When -pidm value (other than 0) is specified, a monochrome image that has resolution greater than the -pidma dpi will be downsampled to the -pidmt dpi resolution.
-pidma dpi 1800
-pidmt dpi 1200
-pjq Percent 80 Specifies the quality of the raster graphics when specified JPEG format by -picc or -picg using the range of 1-100(%). A higher % increases the image quality. However the file size also becomes larger. The initial value is 80.
-pcs * Specifies not to compress text and line art in the PDF.
-pos * Compresses the object in the PDF. The setting is invalid when -pcs is specified.
-plr * Specifies whether the external link specified by the local file 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'. If the document is designed to be viewed on a browser then it is suggested to use the world wide web -plr as the default setting.
-prc Value 0 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
4.All RGB to CMYK
-pcics * Converts RGB images automatically into CMYK when outputting PDF/X and PDF/A. no-LT
-prr dpi 108 Specifies the resolution value of the transformed raster images from 70 to 500(dpi). This parameter is available only in the Windows version and should be set with consideration of on whether better image quality or file size is more important.
-p3da * Imports 3D object. no-LT
-psbkm * Suppresses the output of the bookmark. V6.3 no-LT
-pdfscale scale 100% Specifies the scaling ratio of the PDF to output. A value without a unit or % value can be specified as a scale (1.0 = 100%). When -pdfwidth is specified after - pdfscale, -pdfscale will take priority. The same applies to -pdfheight.
-pdfheight length 100% Scales the output height of PDF. Height values can be specified as a unit or a % value.
-pdfwidth length 100% Scales the output width of PDF. Width values can be specified as a unit or a % value.

Parameters for SVG Output

Parameter Default Functions
-svgver Profile SVG1.1 Specifies the SVG profile:
  • SVG1.1 (default)
  • SVGBasic
  • SVGTiny
If this parameter is omitted, SVG1.1 is outputted.
-svgip Method 0 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 the operation.
-svgicp Directory Specifies the destination for images when '1' or 3 is selected for the -svgip parameter (Outputs the image as an external file). When a relative path is used to specify the Directory, the path will be relative to the output path specified with -o. 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 to use the original name when images are copied to the directory specified by -svgicp. When the file name is duplicated, 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 * A document composed of multiple pages is outputted as a single SVG file.
-svgfmt Format 1 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 the 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 multiple fonts, put commas between fonts.
-svgef * An error is not issued when font embedding fails.
-svgic Value 0 Selects how to convert the raster images which may not be directly embedded in the SVG.
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. Refer to Image Output in SVG Output for information on embeddable images.
-svgjq Percent 80 Specifies the quality of the raster graphics with the range of 1-100(%) when JPEG format is specified to -svgic. 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 108 Specifies the rasterize-resolution value of the transformed raster images from 70 to 500(DPI). This parameter is available only in the Windows version.

Parameters for INX Output

Parameter Default Functions
-inxomode Value 0 Specifies the INX output mode in INX Output option
0.Text area output mode
1.Line area output mode
2.Block output mode
If this parameter is omitted, Text area output mode is adopted. Refer to INX Output Settings for details.

Parameters for MIF Output

Parameter Default Functions
-mifomode Value 0 Specify the MIF output mode in MIF Output option
0.Text area output mode
1.Line area output mode
2.Block output mode
If this parameter is omitted, Text area output mode is adopted. Refer to MIF Output Settings for details.
-mifip Method 0 Specifies how to treat the referred image.MIF Output option
0.Embeds all images in MIF.
1.Links images as external files.
If this parameter is omitted, embedding image is adopted. Refer to MIF Output Settings for details.

Parameters for TEXT Output

Parameter Default Functions
-tenc Encoding UTF-8 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 CRLF or LF Specifies the end-of-line code for TEXT Output. If this parameter is omitted, CRLF is adopted in Windows version, LF is adopted in non-Windows versions. See also TEXT Output Setting for more detail.

Text Output cannot be performed with AH Formatter V6.3 Lite.

Values can be added using one of the following units.

Representation Meanings
cm centimeter
mm millimeter. 1 mm = 1/10 cm
in inch. 1 in = 2.54 cm
pt point. 1 pt = 1/72 in
pc pica. 1 pc = 12 pt
jpt 1 jpt = 0.3514 mm
q 1 q = 0.25 mm

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

AHFCmd -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 processor 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.

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

Return Value

When executing formatting with a Command-line Interface, if the formatting is successful, it finishes the process with the return value of 0. If the formatting is not successful, the program finishes the process with a return value of 1. If the formatting is not performed by specifying -v, etc., 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 a printer name from the Printers dialog in the Windows start menu or from Printers and Faxes in the Control Panel.

-p "Adobe PDF"
-p "EPSON LASER LP-9000C"

[Printer and FAX]

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. AH Formatter V6.3 provides AHFDev.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.

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

Restrictions

See also Restrictions in Graphical User Interface to know more about restrictions on printing.