include/dompdf/INSTALL

   1 DOMPDF - PHP5 HTML to PDF converter
   2 ===================================
   3
   4 http://www.digitaljunkies.ca/dompdf
   5 Copyright (c) 2004 Benj Carson
   6
   7 Send bug reports, patches, feature requests, complaints & hate mail (no spam
   8 thanks though) to <benjcarson@digitaljunkies.ca>
   9
  10 ##### See README for usage information. #####
  11
  12
  13 Installation
  14 ------------
  15
  16 1. Untar/unzip the source package in a directory accessible by your
  17    webserver.
  18
  19 2. Edit dompdf_config.inc.php to fit your installation.
  20
  21 3. Give your webserver write permission on the path specified in
  22    DOMPDF_FONT_DIR (lib/fonts by default).  Under *nix, ideally you can make
  23    the webserver group the owner of this directory and give the directory
  24    group write permissions.  For example, on Debian systems, apache runs as
  25    the www-data user:
  26
  27    $ chgrp www-data lib/fonts
  28    $ chmod g+w lib/fonts
  29
  30    If your user is not a member of the www-data group or you do not have
  31    root priviledges, you can make the directory world writable and set the
  32    sticky bit:
  33
  34    $ chmod 1777 lib/fonts
  35
  36
  37 Font Installation
  38 -----------------
  39
  40 Linux/Unix:
  41
  42 The load_font.php utility installs and converts TrueType fonts for use with
  43 DOMPDF.  Since CSS uses the concept of font families (i.e. the same face can
  44 be rendered in differnt styles & weights) DOMPDF needs to know which actual
  45 font files belong to which font family and which style.  For example, the
  46 Microsoft core font pack includes the files Verdana.ttf, Verdana_Italic.ttf,
  47 Verdana_Bold.ttf and Verdana_Bold_Italic.ttf.  All four of these files need
  48 to be present in the DOMPDF font directory (DOMPDF_FONT_DIR), and entries
  49 need to be made in the dompdf_font_family_cache file.
  50
  51 Given the font family name and the path to the 'normal' font face file
  52 (Verdana.ttf, in our example), load_font.php will search for the bold,
  53 italic and bold italic font face files in the same directory as the
  54 specified file.  It searches for files with the same base name followed by
  55 '_Bold', 'B', or 'b' (similarly for italic and bold italic).  If it can not
  56 find the correct files, you can specify them on the command line.
  57
  58 In addition to copying the files to the DOMPDF font directory, it also
  59 generates .afm files.  The R&OS PDF class requires both the ttf file and an
  60 afm file, which describes glyph metrics.  The afm file is generated using
  61 the ttf2pt1 utlity (available at http://ttf2pt1.sourceforge.net).
  62
  63
  64 usage:
  65
  66 ./load_font.php font-family n_file [b_file] [i_file] [bi_file]
  67
  68 font_family:      the name of the font, e.g. Verdana, 'Times New Roman',
  69                   monospace, sans-serif.
  70
  71 n_file:           the .pfb or .ttf file for the normal, non-bold, non-italic
  72                   face of the font.
  73
  74 {b|i|bi}_file:    the files for each of the respective (bold, italic,
  75                   bold-italic) faces.
  76
  77 Examples:
  78
  79 $ ./load_font.php silkscreen /usr/share/fonts/truetype/slkscr.ttf
  80
  81 $ ./load_font.php 'Times New Roman' /mnt/c_drive/WINDOWS/Fonts/times.ttf
  82
  83 $ php -f load_font.php -- sans-serif /home/dude_mcbacon/myfonts/Verdana.ttf \
  84                                      /home/dude_mcbacon/myfonts/V_Bold.ttf
  85
  86 Windows:
  87
  88 (Note I don't have a windows test box at the moment, so these instructions
  89 may not work...  If someone has tried this and has any suggestions for me,
  90 please send me an email!)
  91
  92 Read the Linux/Unix section above first, as most of it applies.  The main
  93 difference is the ttf2pt1 utility.  Fortunately, there is a windows version,
  94 available at http://gnuwin32.sourceforge.net/packages/ttf2pt1.htm.  You will
  95 have to edit your dompdf_config.inc.php file to point to the path where you
  96 installed ttf2pt1.
  97
  98 You will also need the cli version of PHP in order to execute
  99 load_font.php, however it's usage is the same (see the last example above).
 100
 101
 102 Note for all platforms:
 103
 104 PDFs include support by default for Helvetica, Times-Roman, Courier and
 105 ZapfDingbats.  You do not need to install any font files if you wish to use
 106 these fonts.  This has the advantage of reducing the size of the resulting
 107 PDF, because additional fonts must be embedded in the PDF.
 108
 109 Also, if you have problems installing the font files, you can try and use
 110 the distributed dompdf_font_family_cache.dist file in lib/fonts.  Copy this
 111 file to lib/fonts/dompdf_font_family_cache and edit it directly to match the
 112 files present in your lib/fonts directory. You can uncomment the appropriate
 113 entries in dompdf_font_family_cache once you have copied the appropriate ttf
 114 files into lib/fonts and generated afm files for each one.
 115