source: trunk/client/inc/hpdf/_fpdf/tutorial/tuto7.htm@ 2

Last change on this file since 2 was 2, checked in by root, 15 years ago

importo il progetto

File size: 14.2 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3<head>
4<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5<title>Adding new fonts and encoding support</title>
6<link type="text/css" rel="stylesheet" href="../fpdf.css">
7<style type="text/css">
8table {border-collapse:collapse; border-style:solid; border-width:2px; border-color:#A0A0A0 #000000 #000000 #A0A0A0}
9table {margin:1.4em 0 1.4em 1em}
10th {background-color:#E0EBFF; color:#900000; text-align:left}
11th, td {border:1px solid #808080; padding:2px 10px}
12tr.alt0 {background-color:#FFFFEE}
13tr.alt1 {background-color:#FFFFE0}
14</style>
15</head>
16<body>
17<h1>Adding new fonts and encoding support</h1>
18This tutorial explains how to use TrueType or Type1 fonts so that you are not limited to the standard
19fonts any more. The other interest is that you can choose the font encoding, which allows you to
20use other languages than the Western ones (the standard fonts having too few available characters).
21<br>
22<br>
23There are two ways to use a new font: embedding it in the PDF or not. When a font is not
24embedded, it is searched in the system. The advantage is that the PDF file is lighter; on the other
25hand, if it is not available, a substitution font is used. So it is preferable to ensure that the
26needed font is installed on the client systems. If the file is to be viewed by a large audience,
27it is recommended to embed.
28<br>
29<br>
30Adding a new font requires three steps for TrueTypes:
31<ul>
32<li>Generation of the metric file (.afm)</li>
33<li>Generation of the font definition file (.php)</li>
34<li>Declaration of the font in the script</li>
35</ul>
36For Type1, the first one is theoretically not necessary because the AFM file is usually shipped
37with the font. In case you have only a metric file in PFM format, use the convertor available
38<a href="http://www.fpdf.org/fr/dl.php?id=34">here</a>.
39<h2>Generation of the metric file</h2>
40The first step for a TrueType consists in generating the AFM file. A utility exists to do this
41task: <a href="http://ttf2pt1.sourceforge.net" target="_blank">ttf2pt1</a>. The Windows binary
42is available <a href="http://www.fpdf.org/fr/dl.php?id=22">here</a>. The command line to use is
43the following:
44<br>
45<br>
46<kbd>ttf2pt1 -a font.ttf font</kbd>
47<br>
48<br>
49For example, for Comic Sans MS Regular:
50<br>
51<br>
52<kbd>ttf2pt1 -a c:\windows\fonts\comic.ttf comic</kbd>
53<br>
54<br>
55Two files are created; the one we are interested in is comic.afm.
56<h2>Generation of the font definition file</h2>
57The second step consists in generating a PHP file containing all the information needed by FPDF;
58in addition, the font file is compressed. To do this, a helper script is provided in the font/makefont/
59directory of the package: makefont.php. It contains the following function:
60<br>
61<br>
62<code>MakeFont(<b>string</b> fontfile, <b>string</b> afmfile [, <b>string</b> enc [, <b>array</b> patch [, <b>string</b> type]]])</code>
63<dl class="param" style="margin-bottom:2em">
64<dt><code>fontfile</code></dt>
65<dd>
66<p>Path to the .ttf or .pfb file.</p>
67</dd>
68<dt><code>afmfile</code></dt>
69<dd>
70<p>Path to the .afm file.</p>
71</dd>
72<dt><code>enc</code></dt>
73<dd>
74<p>Name of the encoding to use. Default value: <code>cp1252</code>.</p>
75</dd>
76<dt><code>patch</code></dt>
77<dd>
78<p>Optional modification of the encoding. Empty by default.</p>
79</dd>
80<dt><code>type</code></dt>
81<dd>
82<p>Type of the font (<code>TrueType</code> or <code>Type1</code>). Default value: <code>TrueType</code>.</p>
83</dd>
84</dl>
85The first parameter is the name of the font file. The extension must be either .ttf or .pfb and
86determines the font type. If you own a Type1 font in ASCII format (.pfa), you can convert it to
87binary format with <a href="http://www.lcdf.org/~eddietwo/type/#t1utils" target="_blank">t1utils</a>.
88<br>
89If you don't want to embed the font, pass an empty string. In this case, type is given by the
90<code>type</code> parameter.
91<br>
92Note: in the case of a font with the same name as a standard one, for instance arial.ttf, it is
93recommended to embed. If you don't, some versions of Acrobat will use their own fonts.
94<br>
95<br>
96The AFM file is the one previously generated.
97<br>
98<br>
99The encoding defines the association between a code (from 0 to 255) and a character. The first
100128 are fixed and correspond to ASCII; the following are variable. The encodings are stored in
101.map files. Those available are:
102<ul>
103<li>cp1250 (Central Europe)</li>
104<li>cp1251 (Cyrillic)</li>
105<li>cp1252 (Western Europe)</li>
106<li>cp1253 (Greek)</li>
107<li>cp1254 (Turkish)</li>
108<li>cp1255 (Hebrew)</li>
109<li>cp1257 (Baltic)</li>
110<li>cp1258 (Vietnamese)</li>
111<li>cp874 (Thai)</li>
112<li>ISO-8859-1 (Western Europe)</li>
113<li>ISO-8859-2 (Central Europe)</li>
114<li>ISO-8859-4 (Baltic)</li>
115<li>ISO-8859-5 (Cyrillic)</li>
116<li>ISO-8859-7 (Greek)</li>
117<li>ISO-8859-9 (Turkish)</li>
118<li>ISO-8859-11 (Thai)</li>
119<li>ISO-8859-15 (Western Europe)</li>
120<li>ISO-8859-16 (Central Europe)</li>
121<li>KOI8-R (Russian)</li>
122<li>KOI8-U (Ukrainian)</li>
123</ul>
124Of course, the font must contain the characters corresponding to the chosen encoding.
125<br>
126In the particular case of a symbolic font (that is to say which does not contain letters, such
127as Symbol or ZapfDingbats), pass an empty string.
128<br>
129The encodings which begin with cp are those used by Windows; Linux systems usually use ISO.
130<br>
131Remark: the standard fonts use cp1252.
132<br>
133<br>
134The fourth parameter gives the possibility to alter the encoding. Sometimes you may want to add
135some characters. For instance, ISO-8859-1 does not contain the euro symbol. To add it at position
136164, pass <code>array(164=>'Euro')</code>.
137<br>
138<br>
139The last parameter is used to give the type of the font in case it is not embedded (that is to
140say the first parameter is empty).
141<br>
142<br>
143After you have called the function (create a new file for this and include makefont.php, or
144simply add the call directly inside), a .php file is created, with the same name as the .afm one.
145You may rename it if you wish. If the case of embedding, the font file is compressed and gives a
146second file with .z as extension (except if the compression function is not available, it
147requires zlib). You may rename it too, but in this case you have to alter the variable <code>$file</code>
148in the .php file accordingly.
149<br>
150<br>
151Example:
152<div class="source">
153<pre><code>MakeFont<span class="kw">(</span><span class="str">'c:\\windows\\fonts\\comic.ttf'</span><span class="kw">,</span><span class="str">'comic.afm'</span><span class="kw">,</span><span class="str">'cp1252'</span><span class="kw">);
154</span></code></pre>
155</div>
156which gives the files comic.php and comic.z.
157<br>
158<br>
159Then you have to copy the generated file(s) to the font directory. If the font file
160could not be compressed, copy the .ttf or .pfb instead of the .z.
161<br>
162<br>
163Remark: for TTF fonts, you can generate the files online <a href="http://fpdf.fruit-lab.de" target="_blank">here</a>
164instead of doing it manually.
165<h2>Declaration of the font in the script</h2>
166The last step is the most simple. You just need to call the <a href='../doc/addfont.htm'>AddFont()</a> method. For instance:
167<div class="source">
168<pre><code>$pdf<span class="kw">-&gt;</span>AddFont<span class="kw">(</span><span class="str">'Comic'</span><span class="kw">,</span><span class="str">''</span><span class="kw">,</span><span class="str">'comic.php'</span><span class="kw">);
169</span></code></pre>
170</div>
171or simply:
172<div class="source">
173<pre><code>$pdf<span class="kw">-&gt;</span>AddFont<span class="kw">(</span><span class="str">'Comic'</span><span class="kw">);
174</span></code></pre>
175</div>
176And the font is now available (in regular and underlined styles), usable like the others. If we
177had worked with Comic Sans MS Bold (comicbd.ttf), we would have put:
178<div class="source">
179<pre><code>$pdf<span class="kw">-&gt;</span>AddFont<span class="kw">(</span><span class="str">'Comic'</span><span class="kw">,</span><span class="str">'B'</span><span class="kw">,</span><span class="str">'comicbd.php'</span><span class="kw">);
180</span></code></pre>
181</div>
182<h2>Example</h2>
183Let's now see a small complete example. The font used is Calligrapher, available at
184<a href="http://www.abstractfonts.com/fonts/" target="_blank">www.abstractfonts.com</a> (a site
185offering numerous free TrueType fonts). The first step is the generation of the AFM file:
186<br>
187<br>
188<kbd>ttf2pt1 -a calligra.ttf calligra</kbd>
189<br>
190<br>
191which gives calligra.afm (and calligra.t1a that we can delete). Then we generate the definition
192file:
193<div class="source">
194<pre><code>&lt;?php
195<span class="kw">require(</span><span class="str">'font/makefont/makefont.php'</span><span class="kw">);
196
197</span>MakeFont<span class="kw">(</span><span class="str">'calligra.ttf'</span><span class="kw">,</span><span class="str">'calligra.afm'</span><span class="kw">);
198</span>?&gt;</code></pre>
199</div>
200The function call gives the following report:
201<br>
202<br>
203<b>Warning:</b> character Euro is missing<br>
204<b>Warning:</b> character Zcaron is missing<br>
205<b>Warning:</b> character zcaron is missing<br>
206<b>Warning:</b> character eth is missing<br>
207Font file compressed (calligra.z)<br>
208Font definition file generated (calligra.php)<br>
209<br>
210The euro character is not present in the font (it is too old). Three other characters are missing
211too, but we are not interested in them anyway.
212<br>
213We can now copy the two files to the font directory and write the script:
214<div class="source">
215<pre><code>&lt;?php
216<span class="kw">require(</span><span class="str">'fpdf.php'</span><span class="kw">);
217
218</span>$pdf<span class="kw">=new </span>FPDF<span class="kw">();
219</span>$pdf<span class="kw">-&gt;</span>AddFont<span class="kw">(</span><span class="str">'Calligrapher'</span><span class="kw">,</span><span class="str">''</span><span class="kw">,</span><span class="str">'calligra.php'</span><span class="kw">);
220</span>$pdf<span class="kw">-&gt;</span>AddPage<span class="kw">();
221</span>$pdf<span class="kw">-&gt;</span>SetFont<span class="kw">(</span><span class="str">'Calligrapher'</span><span class="kw">,</span><span class="str">''</span><span class="kw">,</span>35<span class="kw">);
222</span>$pdf<span class="kw">-&gt;</span>Cell<span class="kw">(</span>0<span class="kw">,</span>10<span class="kw">,</span><span class="str">'Enjoy new fonts with FPDF!'</span><span class="kw">);
223</span>$pdf<span class="kw">-&gt;</span>Output<span class="kw">();
224</span>?&gt;</code></pre>
225</div>
226<p class='demo'><a href='tuto7.php' target='_blank' class='demo'>[Demo]</a></p>
227<h2>About the euro symbol</h2>
228The euro character is not present in all encodings, and is not always placed at the same position:
229<table>
230<tr><th>Encoding</th><th>Position</th></tr>
231<tr class="alt0"><td>cp1250</td><td>128</td></tr>
232<tr class="alt1"><td>cp1251</td><td>136</td></tr>
233<tr class="alt0"><td>cp1252</td><td>128</td></tr>
234<tr class="alt1"><td>cp1253</td><td>128</td></tr>
235<tr class="alt0"><td>cp1254</td><td>128</td></tr>
236<tr class="alt1"><td>cp1255</td><td>128</td></tr>
237<tr class="alt0"><td>cp1257</td><td>128</td></tr>
238<tr class="alt1"><td>cp1258</td><td>128</td></tr>
239<tr class="alt0"><td>cp874</td><td>128</td></tr>
240<tr class="alt1"><td>ISO-8859-1</td><td>absent</td></tr>
241<tr class="alt0"><td>ISO-8859-2</td><td>absent</td></tr>
242<tr class="alt1"><td>ISO-8859-4</td><td>absent</td></tr>
243<tr class="alt0"><td>ISO-8859-5</td><td>absent</td></tr>
244<tr class="alt1"><td>ISO-8859-7</td><td>absent</td></tr>
245<tr class="alt0"><td>ISO-8859-9</td><td>absent</td></tr>
246<tr class="alt1"><td>ISO-8859-11</td><td>absent</td></tr>
247<tr class="alt0"><td>ISO-8859-15</td><td>164</td></tr>
248<tr class="alt1"><td>ISO-8859-16</td><td>164</td></tr>
249<tr class="alt0"><td>KOI8-R</td><td>absent</td></tr>
250<tr class="alt1"><td>KOI8-U</td><td>absent</td></tr>
251</table>
252ISO-8859-1 is widespread but does not include the euro sign. If you need it, the simplest thing
253to do is using cp1252 or ISO-8859-15 instead, which are nearly identical but contain the precious
254symbol.
255<br>
256As for ISO-8859-2, it is possible to use ISO-8859-16 instead, but it contains many differences.
257It is therefore simpler to patch the encoding to add the symbol to it, as explained above. The
258same is true for the other encodings.
259<h2>Font synthesis under Windows</h2>
260When a TrueType font is not available in a given style, Windows is able to synthesize it from the
261regular version. For instance, there is no Comic Sans MS Italic, but it can be built from Comic
262Sans MS Regular. This feature can be used in a PDF file, but unfortunately requires that the
263regular font be present in the system (you must not embed it). Here is how to do it:
264<ul>
265<li>Generate the definition file for the regular font without embedding (you may rename it to
266reflect the desired style)</li>
267<li>Open it and append to the variable <code>$name</code> a comma followed by the desired style
268(<code>Italic</code>, <code>Bold</code> or <code>BoldItalic</code>)</li>
269</ul>
270For instance, for the file comici.php:
271<br>
272<br>
273<code>$name='ComicSansMS,Italic';</code>
274<br>
275<br>
276It can then be used normally:
277<div class="source">
278<pre><code>$pdf<span class="kw">-&gt;</span>AddFont<span class="kw">(</span><span class="str">'Comic'</span><span class="kw">,</span><span class="str">'I'</span><span class="kw">,</span><span class="str">'comici.php'</span><span class="kw">);
279</span></code></pre>
280</div>
281<h2>Reducing the size of TrueType fonts</h2>
282Font files are often quite voluminous (more than 100, even 200KB); this is due to the fact that
283they contain the characters corresponding to many encodings. zlib compression reduces them but
284they remain fairly big. A technique exists to reduce them further. It consists in converting the
285font to the Type1 format with ttf2pt1 by specifying the encoding you are interested in; all other
286characters will be discarded.
287<br>
288For instance, the arial.ttf font shipped with Windows 98 is 267KB (it contains 1296 characters).
289After compression it gives 147. Let's convert it to Type1 by keeping only cp1250 characters:
290<br>
291<br>
292<kbd>ttf2pt1 -b -L cp1250.map c:\windows\fonts\arial.ttf arial</kbd>
293<br>
294<br>
295The .map files are located in the font/makefont/ directory of the package. The command produces
296arial.pfb and arial.afm. The arial.pfb file is only 35KB, and 30KB after compression.
297<br>
298<br>
299It is possible to go even further. If you are interested only by a subset of the encoding (you
300probably don't need all 217 characters), you can open the .map file and remove the lines you are
301not interested in. This will reduce the file size accordingly.
302</body>
303</html>
Note: See TracBrowser for help on using the repository browser.