← All changes | mpdf/README.txt +145 -2 1.7.5 → 1.5 View file →

		@@ -1,5 +1,148 @@
1		-Upgrading
	1	+Installation
2	2	============
	3	+ * Download the .zip file and unzip it
	4	+ * Create a folder e.g. /mpdf on your server
	5	+ * Upload all of the files to the server, maintaining the folders as they are
	6	+ * Ensure that you have write permissions set (CHMOD 6xx or 7xx) for the following folders:
	7	+ /ttfontdata/ - used to cache font data; improves performance a lot
	8	+ /tmp/ - used for some images and ProgressBar
	9	+ /graph_cache/ - if you are using JpGraph in conjunction with mPDF
3	10
4		-To upgrade from mPDF 5.7 to 5.7.1, simply upload the 3 files to their corresponding folders, overwriting files as required.
	11	+To test the installation, point your browser to the basic example file : [path_to_mpdf_folder]/mpdf/examples/example_basic.php
	12	+
	13	+If you wish to define a different folder for temporary files rather than /tmp/ see the note on 'Folder for temporary files' in
	14	+ the section on Installation & Setup in the manual (http://mpdf1.com/manual/).
	15	+
	16	+If you have problems, please read the section on troubleshooting in the manual.
	17	+
	18	+
	19	+Fonts
	20	+=====
	21	+I will refer to font names in 2 ways:
	22	+"CSS font-family name" - mPDF is designed primarily to read HTML and CSS. This is the name used in CSS e.g.
	23	+ <p style="font-family: 'Trebuchet MS';">
	24	+
	25	+"mPDF font-family name" - the name used internally to process fonts. This could be anything you like,
	26	+ but by default mPDF will convert CSS font-family names by removing any spaces and changing
	27	+ to lowercase. Reading the name above, mPDF will look for a "mPDF font-family name" of
	28	+ 'trebuchetms'.
	29	+
	30	+The configurable values referred to below are set in the config_fonts.php file
	31	+
	32	+When parsing HTML/CSS, mPDF will read the CSS font-family name (e.g. 'Trebuchet MS') and convert
	33	+by removing any spaces and changing to lowercase, to look for a mPDF font-family name (trebuchetms).
	34	+
	35	+Next it will look for a translation (if set) e.g.:
	36	+$this->fonttrans = array(
	37	+ 'trebuchetms' => 'trebuchet'
	38	+)
	39	+
	40	+Now the mPDF font-family name to be used is 'trebuchet'
	41	+
	42	+If you wish to make this font available, you need to specify the Truetype .ttf font files for each variant.
	43	+These should be defined in the array:
	44	+$this->fontdata = array(
	45	+ "trebuchet" => array(
	46	+ 'R' => "trebuc.ttf",
	47	+ 'B' => "trebucbd.ttf",
	48	+ 'I' => "trebucit.ttf",
	49	+ 'BI' => "trebucbi.ttf",
	50	+ )
	51	+)
	52	+
	53	+This is the array which determines whether a font is available to mPDF. Each font-family must have a
	54	+Regular ['R'] file defined - the others (bold, italic, bold-italic) are optional.
	55	+
	56	+mPDF will try to load the font-file. If you have defined _MPDF_SYSTEM_TTFONTS at the top of the
	57	+config_fonts.php file, it will first look for the font-file there. This is useful if you are running
	58	+mPDF on a computer which already has a folder with TTF fonts in (e.g. on Windows)
	59	+
	60	+If the font-file is not there, or _MPDF_SYSTEM_TTFONTS is not defined, mPDF will look in the folder
	61	+/[your_path_to_mpdf]/ttfonts/
	62	+
	63	+Note that the font-file names are case-sensitive and can contain capitals.
	64	+
	65	+If the folder /ttfontdata/ is writeable (CHMOD 644 or 755), mPDF will save files there which it can
	66	+re-use next time it accesses a particular font. This will significantly improve processing time
	67	+and is strongly recommended.
	68	+
	69	+mPDF should be able to read most TrueType Unicode font files with a .ttf extension
	70	+Truetype fonts with .ttf extension that are OpenType also work OK.
	71	+TrueType collections (.ttc) will also work if they contain TrueType Unicode fonts.
	72	+
	73	+
	74	+Character substitution
	75	+----------------------
	76	+Most people will have access to a Pan-Unicode font with most Unicode characters in it such as
	77	+Arial Unicode MS. Set $this->backupSubsFont = array('arialunicodems'); at the top of the config_fonts.php file
	78	+to use this font when substituting any characters not found in the specific font being used.
	79	+
	80	+Example:
	81	+You can set $mpdf->useSubstitutions = true; at runtime
	82	+or $this->useSubstitutions = true; in the config.php file
	83	+
	84	+<p style="font-family: 'Comic Sans MS'">This text contains a Thai character &#3617; which does not exist
	85	+in the Comic Sans MS font file</p>
	86	+
	87	+When useSubstitutions is true, mPDF will try to find substitutions for any missing characters:
	88	+1) firstly looks if the character is available in the inbuilt Symbols or ZapfDingbats fonts;
	89	+2) [If defined] looks in each of the the font(s) set by $this->backupSubsFont array
	90	+
	91	+NB There is an increase in processing time when using substitutions, and even more so if
	92	+a backupSubsFont is defined.
	93	+
	94	+Controlling mPDF mode
	95	+=====================
	96	+The first parameter of new mPDF('') works as follows:
	97	+new mPDF('c') - forces mPDF to only use the built-in [c]ore Adobe fonts (Helvetica, Times etc)
	98	+
	99	+new mPDF('') - default - font subsetting behaviour is determined by the configurable variables
	100	+ $this->maxTTFFilesize and $this->percentSubset (see below)
	101	+ Default values are set so that: 1) very large font files are always subset
	102	+ 2) Fonts are embedded as subsets if < 30% of the characters are used
	103	+
	104	+new mPDF('..-x') - used together with a language or language/country code, this will cause
	105	+ mPDF to use only in-built core fonts (Helvetica, Times) if the language specified is appropiate;
	106	+ otherwise it will force subsetting (equivalent to using "")
	107	+ e.g. new mPDF('de-x') or new mPDF('pt-BR-x') will use in-built core fonts
	108	+ and new mPDF('ru-x') will use subsets of any available TrueType fonts
	109	+ The languages that use core fonts are defined in config_cp.php (using the value $coreSuitable).
	110	+
	111	+new mPDF('..+aCJK') new mPDF('+aCJK')
	112	+new mPDF('..-aCJK') new mPDF('-aCJK')
	113	+ - used optionally together with a language or language/country code, +aCJK will force mPDF
	114	+ to use the Adobe non-embedded CJK fonts when a passage is marked with e.g. "lang: ja"
	115	+ This can be used at runtime to override the value set for $mpdf->useAdobeCJK in config.php
	116	+ Use in conjunction with settings in config_cp.php
	117	+
	118	+For backwards compatibility, new mPDF('-s') and new mPDF('s') will force subsetting by
	119	+ setting $this->percentSubset=100 (see below)
	120	+ new mPDF('utf-8-s') and new mPDF('ar-s') are also recognised
	121	+
	122	+Language/Country (ll-cc)
	123	+------------------------
	124	+You can use a language code ('en') or language/country code ('en-GB') to control which
	125	+mode/fonts are used. The behaviour is set up in config_cp.php file.
	126	+The default settings show some of the things you can do:
	127	+new mPDF('de') - as German is a Western European langauge, it is suitable to use the Adobe core fonts.
	128	+ Using 'de' alone will do nothing, but if you use ('de-x'), this will use core fonts.
	129	+new mPDF('th') - many fonts do not contain the characters necessary for Thai script. The value $unifonts
	130	+ defines a restricted list of fonts available for mPDF to use.
	131	+
	132	+NB <html dir="rtl"> or <body dir="rtl"> are supported.
	133	+
	134	+
	135	+
	136	+Configuration variables changed
	137	+===============================
	138	+Configuration variables are documented in the on-line manual (http://mpdf1.com/manual/).
	139	+
	140	+
	141	+Font folders
	142	+============
	143	+If you wish to define your own font file folders (perhaps to share),
	144	+you can define the 2 constants in your script before including the mpdf.php script e.g.:
	145	+
	146	+define('_MPDF_TTFONTPATH','your_path/ttfonts/');
	147	+define('_MPDF_TTFONTDATAPATH','your_path/ttfontdata/'); // should be writeable
5	148