html2ps/pdf configuration files and options

Back to table of contents

Currently, configuration is done both via configuration file (.html2ps.config) and configuration constants inside the source files. We're planning to eventually move all user-configurable data to a external configuration file, so you'll not need to modify the script source.

Please note that the configuration file is a so-called "dot-file" -- it will behave as hidden file on most Unix-like systems. If you're missing it, please check your system settings and make it show "hidden" files (it is hightly dependent on which software you're using, so we won't give any concrete suggestions here).

Common configuration

Common directives in .html2ps.config
Option Appears at Description
media Top level Defines the output media size. This tag should have three arguments:
  • name -- media name; you'll be able to refer to this media by name while calling the script;
  • width -- media width in millimetres;
  • height -- media height in millimetres.


Common constants
Name File Description
MAX_REDIRECTS fetcher.class.php Maximum number of HTTP redirects to follow when fetching an HTML page. This prevents an infinite loop on HTML pages redirecting to themselves. Default value is 10; it is unlikely you'll need to increase this value.
OUTPUT_FILE_ALLOWED output.class.php Enables or disables the local file output mode ("Destination: File on server"). Default value is 'true'. Disable it if you're limited in disk space because these files are never removed automatically.
OUTPUT_FILE_DIRECTORY output.class.php Name of directory (relative to script file) where generated files will be placed (if OUTPUT_FILE_ALLOWED is enabled and users chooses "Destination: File on server")
OUTPUT_DEFAULT_NAME output.class.php Default name to assign to the generated file in case no filename could be guessed using the TITLE file tag. Default value is 'unnamed'. Note that appropriate extension depending on the output file type will be appended to this name.
WRITER_TEMPDIR writer.class.php Path to directory where temporary script files will be created. Set it to your system temporary directory. Default value is to use script local temporary dir, like './temp/'
WRITER_FILE_PREFIX writer.class.php Prefix that will be appended to temporary file names used by the script. Default is 'ps_'. It is unlikely you need to modify this value.
PDFLIB_UPR_PATH writer.class.php Path to your PDFLIB configuration path containing information about the additional fonts and encodings supported by PDFLIB
CACHE_DIR image.class.php Path to directory containing temporary image cache files.
PDFLIB_TTF_FONTS_REPOSITORY writer.class.php Path to directory containing TrueType fonts used by PDFLIB.

Postscript and Ghotscript configuration

Postscript-specific directives in .html2ps.config
Option Appears at Description
fonts Top level Contains information about font-family value to Postscript font name mappings. See descrripton of nested directives.
family /fonts Contains information about particular font-family value mapping. Attributes:
  • name -- value of 'font-family' property being mapped.
encoding-override /fonts, /fonts/family Contains information about exceptions in font-family mappings. Attributes:
  • name -- comma-separated list of encodings to apply this rule for.
For example, normally 'times' family is mapped to /Times-Roman font. On the other hand, this standard font does not contain cyrillic symbols, so when one of the cyrillic encodings is met, 'times' will be mapped to /TimesCyr-Medium.
alias /fonts List of font-family aliases. Attributes:
  • alias -- font family alias to be translated
  • family -- real font family name for this alias
Note that alias resolving is done once, so there's not much use of constructions similar to 
  <alias alias="verdana" family="arial"/>
  <alias alias="arial" family="helvetica"/>
normal /fonts/family, /fonts/family/encoding-override, /encoding-override System font names for normal font variant. Attributes:
  • normal -- font name for roman (non-italic) font
  • italic -- font name for italic font
  • oblique -- font name for oblique font
bold /fonts/family, /fonts/family/encoding-override, /encoding-override System font names for bold font variant. Attributes:
  • normal -- font name for bold roman (non-italic) font
  • italic -- font name for bold italic font
  • oblique -- font name for bold oblique font

Postscript-specific constants
Name File Description
GS_PATH writer.class.php

Path to your Ghostscript executable (including executable name). Required for PS2PDF conversion. If you have your system path set properly, you'll be happy with the default value gs; otherwise try /usr/bin/gs or /usr/local/bin/gs. If this doesn't work, ask your system administrator.

Windows users, please note you need to provide the path to the console version of Ghostscript (usually named gswin32c.exe), NOT GUI version (usually named gswin32.exe). GUI version will cause a script to hang during PS2PDF conversion (it happens as GUI version waits for user input after completing commands, causing script to wait for its termination forever).

IMAGEMAGICK_ CONVERT_EXECUTABLE ps.image.encoder. imagemagick.inc.php Path to convert executable file from the ImageMagick package, including the executable name. If you have set it properly, you may get a small increase in image processing.

PDFLIB configuration

PDFLIB-specific directives in .html2ps.config
Option Appears at Description
fonts-pdf Top level Contains information about font-family value to PDF font name mappings. Note that nested directives and their meanings are the same as for the fonts directive, except that they're applied when PDFLIB is used.
ttf fonts-pdf Defines mapping of typefaces to available TrueType fonts. Attributes:
  • typeface -- typeface name (refers to the ones used in normal, italic and oblique attributes)
  • file -- name of the TTF file (searched in PDFLIB_TTF_FONTS_REPOSITORY directory)

PDFLIB-specific constants
Name File Description
PDFLIB_DL_PATH writer.class.php Path to pdflib PHP extension library (pdflib.so, for example) if you need to load it dynamically. Note that your PHP configuration should allow dl function calls in this case. You don't need this constant if you have PDFLIB enabled in your php.ini.