html2ps/html2pdf configuration files and options

# 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 `config.inc.php` file.

## html2ps.config, Common configuration options

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.

## html2ps.config, 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"/>
`metrics` | /fonts | Reference to a font metric file for this font family. Attributes: `typeface` – typeface name (refers to the ones used in `normal`, `italic` and `oblique` attributes) `file` – name of the font metric (AFM) file (searched in TYPE1_FONT_REPOSITORY directory)
`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

## html2ps, config PDFLIB/FPDF 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 TTF_FONTS_REPOSITORY directory) `embed` – flag indicating whether this font file should be embedded in generated PDF (0 - not embedded, 1 - embedded).

## config.inc.php, Common configuration options

Common configuration constants

Name | Description
--- | ---
HTML2PS_DIR | Path to directory on server where HTML2PS script files reside. All HTML2PS-specific directories and paths are relative to this directory.
DEFAULT_USER_AGENT | Value of the 'User-Agent' HTTP header which will be sent by PHP when fetching files from remote server.
OUTPUT_DEFAULT_NAME | Default PDF or PS file name to use when no filename have been specified via API.
DEFAULT_ENCODING | Default encoding to use when no encoding information is available (e.g. encoding was specified neither in HTTP headers nor in META tag of HTML page).
FILE_PROTOCOL_RESTRICT | Determines the prefix of the filesystem path allowed to be referred via 'file' protocol. By default, you may refer files in html2ps directory and below; to use files from `C:\images` directory you'll need to store `C:\images\` value in this constant. Note the trailing backslash; if it is omitted, the prefix may match several directories, e.g. both `C:\images\` and `C:\images-private\`.
FONT_EMBEDDING_MODE | Determines how font files are embedded. May be: 'all' — embed all fonts 'none' — do not embed any fonts 'config' — whether font is embedded is determined by html2ps.config 'embed' attribute value for this font

## config.inc.php, Postscript options

Postscript-related constants

Name | Description
--- | ---
GS_PATH | Path to your Ghostscript executable. Note to Windows users! Ghostscript distribution includes two executables: gswin32.exe (GUI version) and gswin32c.exe (command-line version). You should provide path to command-line version only!
TYPE1_FONTS_REPOSITORY | Path to font metric (AFM) files. Usually AFM files are packaged together with Ghostscript in 'fonts' subdirectory; in some Linux distibutions you should install 'ghostscript-fonts' package to get font metrics.

## config.inc.php, PDFLIB options

PDFLIB-related constants

Name | Description
--- | ---
PDFLIB_DL_PATH | Path to PDFLIB dynamically loaded library. If no "pdf" extension loaded, script attempts to call "dl" with PDFLIB_DF_PATH as argument.
PDFLIB_LICENSE | Your PDFLIB license key.
TTF_FONTS_REPOSITORY | Path to directory containing a set of True-Type font files to be used by PDFLIB.