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.