$Header: /home/cvsroot/dvipdfmx/README,v 1.27 2005/06/27 09:04:52 hirata Exp $ The dvipdfmx Project ==================== Last modified: April 20, 2005 Copyright (C) 2002-2004 by Jin-Hwan Cho and Shunsaku Hirata, the dvipdfmx project team This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA. Contents -------- 1. Introduction 2. Installation 2.1. Compiling and Installation 2.2. TeX Directory Structure (TDS) 2.3. Auxiliary Files 3. CJK Support 3.1. Quick Test of Installation 3.2. CJK-LaTeX and HLaTeX 3.3. Omega and Other Extended TeX 3.4. Vertical Typesetting 4. Unicode Support 4.1. Unicode Support in General 4.2. ToUnicode CMap Support 4.3. OpenType Support and Unicode 4.4. Type1 Font Support and Unicode 5. Graphics and Image Format 5.1. Supported Graphics File Format 5.2. Graphics Extension 5.3. Using External Programs for Format Conversion 6. DVI Specials 6.1. Compatibility 6.2. Additions to Dvipdfm's pdf: Special 7. Font Mapping 8. Incompatible Changes From Dvipdfm 9. Other Improvement Over Dvipdfm 10. Font Licensing and Embedding 1. Introduction ------------ The dvipdfmx (formerly dvipdfm-cjk) project provides an eXtended version of the dvipdfm, a DVI to PDF translator developed by Mark A. Wicks. The primary goal of this project is to support multi-byte character encodings and large character sets for East Asian languages. The secondary goal is to support as many features as pdfTeX developed by Han The Thanh. This project is a combined work of the dvipdfm-jpn project by Shunsaku Hirata and its modified one, dvipdfm-kor, by Jin-Hwan Cho. 2. Installation ----------------------- Typical usage and installation steps are not different from the original dvipdfm. Please refer documents from dvipdfm distribution for detailed instruction on how to install and how to use dvipdfm. 2.1. Compiling and Installation If you have obtained older version, please use latest version unless you have a clear reason to choose older versions. The latest snapshot of dvipdfmx source is available at: http://project.ktug.or.kr/dvipdfmx/snapshot/ And the CVS repository for this project can be obtained through anonymous CVS access with the following command: cvs -d:pserver:anonymous@cvs.ktug.or.kr:/home/cvsroot login cvs -d:pserver:anonymous@cvs.ktug.or.kr:/home/cvsroot co dvipdfmx When prompted for a password, simply press the Enter key. The kpathsea library is required to compile and install dvipdfmx in UNIX or UNIX-like platforms. It is usually included for most of TeX distributions. If you already have installed dvipdfm (the original) by yourself, you should already have kpathsea library and it's headers. And zlib library is highly recommended as dvipdfmx can't compress data without this. Before starting things, you must check the location of your TeX installation. If other TeX related programs are installed under, e.g., '/usr/local/TeX/bin', you should specify directory '/usr/local/TeX' as an for ./configure script as ./configure --prefix=/usr/local/TeX --with-kpathsea=/usr/local/TeX If you are using libpaper to handle paper sizes for various program, you can use --with-paper option to ./configure. The location of libpaper library can be specified with this option as --with-paper=DIR Please note thath dvipdfmx uses JIS paper size for B-series paper instead of ISO's one for historical reason. (too late to change the default behavior) The most easiest way to fix this is to use libpaper if you already have that, otherwise define ISO_PAPERSIZE macro at compilation time. Dvipdfmx requires libpng library available from http://www.libpng.org/pub/png/libpng.html to read PNG format images. To tell dvipdfmx the location of libpng header and library, use configure option --with-png=DIR After you have finished ./configure, just type make && make install then dvipdfmx will be installed under the directory specified by the --prefix option to ./configure script. After you have successfully installed dvipdfmx, you may need to install various auxiliary files and slightly adjust location of files or configuration. Amount of additional files and modification depends on your environment, and briefly described in the sections follows. 2.2. TeX Directory Structure (TDS) If your TeX installation is conforming with TDS version 1.1 described in http://www.tug.org/ftp/tex/tds-1.1/ , then you'll need to adjust your dvipdfmx installtion. This also applies when you have updated programs without modifying existing platform independent files (files in texmf directory). Dvipdfmx installs few files in addition to dvipdfmx program itself, dvipdfmx.cnf, cid-x.map and others, but it currently does not choose installation directory as appropriate for TDS 1.1. If your 'kpsewhich' program recognizes '.sfd' file format, i.e., kpsewhich --show-path --format=.sfd does not answer as 'unknown format', then you should move several files under appropriate locations or should modify texmf.cnf as follows: * Subfont Definition (SFD) Files Recommended location of SFD files (.sfd) is $TEXMF/fonts/sfd/ and environmental variable for specifying additional search path for this file format files is SFDFONTS . To make those files visible to dvipdfmx under TDS 1.1 installation, you must move all .sfd files to the directory mentioned above or set SFDFONTS variable in texmf.cnf. As some programs may not be updated to follow this convention yet, it is recommended to preserve old installation directory. If you have .sfd files under "$TEXMF/dvipdfm/", please do not use that, please move all files to the directory mentioned above. * PostScript CMap Resources Recommended location of CMap files (no suffix or with suffix .cmap) is $TEXMF/fonts/cmap/ and environmental variable for adding extra search path for this format files is CMAPFONTS You may want to set CMAPFONTS to include GhostScript's Resource path, e.g., /usr/share/ghostscript/Resource/CMap// in your texmf.cnf file as this resource can be used by various programs that manipulates PS/PDF files. Dvipdfmx installs few additional files into the directory "$TEXMF/dvipdfm/CMap", please move this files to the directory for CMap files. But please note that file "Adobe-Identity-UCS2" is not meaningful to other programs at all, so you should place at least this file in different location than CMap files. (Or you can just remove this unless you see problems in copy-and-pasting text from dvipdfmx output PDF.) * Font Mapping Files Suggested place for dvipdfm's font mapping files (.map) is $TEXMF/fonts/map/dvipdfm/ and environmental variable for this format files is TEXFONTMAPS For files containing dvipdfmx extension to dvipdfm format, place them into $TEXMF/fonts/map/dvipdfmx/ instead of sub-directory 'dvipdfm'. * OpenType Fonts Appropriate place for OpenType font with PostScript outline (.otf) is $TEXMF/fonts/opentype/supplier/typeface/ where 'supplier' and 'typeface' should be replaced with font's supplier and typeface identifier strings. 2.3. Auxiliary Files 1) CMap PostScript Resources Dvipdfmx internally identifies glyphs in a font with identifier represented as numbers ranging from 0 to 65535. CMap PostScript Resources defines how the input character codes are translated to those ID's (CID). CID's should be uniquely assigned to every glyphs contained in a collection of glyphs. Adobe has defined several "character collection"s; Adobe-GB1 (Simplified Chinese), Adobe-CNS1 (Traditional Chinese), Adobe-Japan1 (Japanese), and Adobe-Korea1 (Korean), which contains much of glyphs necessary for publishing for each languages. Details on Adobe's character collections can be found at Adobe's developer site: http://partners.adobe.com/public/developer/font/index.html Please install CMap resource files under the directory ${TEXMF}/fonts/cmap , or set CMAPFONTS variable to point the directory containing CMap resource in texmf.cnf. If your TeX installation does not conforming TDS 1.1, then you should set CMAPINPUTS variable to make those files visible to dvipdfmx. For examples, CMAPINPUTS= .;$TEXMF/fonts/cmap// Adobe's "CMaps for PDF 1.4 CJK Fonts" are available from: http://partners.adobe.com/public/developer/acrobat/index_advanced.html or ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/ You can find a short explanation of each CMap files in cid2code.txt contained in the archive files found at the above FTP site. 2) SubFont Definition Files ..... 3) Adobe Glyph List and ToUnicode Mapping Files The Adobe glyph list (AGL) file describes correspondence between PostScript glyph names (e.g., AE, Aacute, ...) and it's Unicode character sequences. Most features described in the section "Unicode Support" requires this file. Dvipdfmx looks for file "glyphlist.txt" when conversion from PostScript glyph names to Unicode is necessary. This conversion is done in various situations; when creating ToUnicode CMap for 8bit encoded fonts, finding glyph description from TrueType/OpenType fonts supporting Unicode when the font itself does not provide the mapping from PostScript glyph names to glyph indices (version 2.0 "post" table), and when encoding "unicode" is specified for Type 1 font. The "glyphlist.txt" file written by Adobe is found at http://partners.adobe.com/asn/tech/type/glyphlist.txt You should place file "glyphlist.txt" in a directory shown by kpsewhich --progname=dvipdfm --show-path="other text files" Please check kpathsea library can find this file by 'kpsewhich' command: kpsewhich --progname=dvipdfm --format="other text files" glyphlist.txt The 'progname' is not dvipdfmx but dvipdfm here. ToUnicode mapping is similar to glyph list file but describes correspondence between CID numbers and Unicode values. The content of this file look like a CMap files and is contained in "CMaps for PDF 1.4 CJK Fonts" from Adobe (see "CMap PostScript Resources" above). This file is required to support TrueType font (including OpenType fonts with TrueType outline). Those files should be installed same directory as ordinary CMap files. 3. CJK Support 3.1. Quick Test of Installation 3.2. CJK-LaTeX and HLaTeX 3.3. Omega and Other Extended TeX 4. Unicode Support 4.1. Unicode Support in General 4.2. ToUnicode CMap Support 4.3. OpenType Support and Unicode 4.4. Type1 Font Support and Unicode 5. Graphics and Image Format 5.1. Supported Graphics File Format 5.2. Graphics Extension 5.3. Using External Programs for Format Conversion 6. DVI Specials 6.1. Compatibility 6.2. Additions to Dvipdfm's pdf: Special 7. Font Mapping 7.1. Options for CJK Font Few options are available in dvipdfmx (for CID-keyed fonts) in addition to the original dvipdfm. 1) TTC Index You can specify TrueType Collection index number with :n: option in front of TrueType font name. min10 H :1:mincho In this example, the option :1: tells dvipdfmx to select TrueType font #1 from TrueType collection font "mincho.ttc". 2) No-embed Switch It is possible to block embedding glyph data with the character `!' in front of the font name in the font mapping file. This feature reduces the size of the final PDF output, but the PDF file may not be viewed exactly in other systems on which appropriate fonts are not installed. Use of this option is not recommended for fonts that contains unusual characters (and characters having different width from default value). Please note that glyph metric information is not written in the output PDF file for TrueType fonts without embedding. It will be treated as fixed-pitch with all widths equal to the default value (will be fixed someday). 3) Stylistic Variants Keywords ",Bold", ",Italic", and ",BoldItalic" can be used to create synthetic bold, italic, and bolditalic style variants from other font using PDF viewer's (or OS's) function. jbtmo@UKS@ UniKSCms-UCS2-H :0:!batang,Italic jbtb@Unicode@ Identity-H !batang/UCS,Bold Availability of this feature highly depends on the implementation of PDF viewers. This feature is not supported for embedded fonts in the most of PDF viewers, like Adobe Acrobat Reader and GNU Ghostscript. Notice that this option automatically disable font embedding. 8. Incompatible Changes From Dvipdfm 9. Other Improvement Over Dvipdfm 9.1. Encryption 9.2. Font 10. Font Licensing and Embedding In OpenType format, information regarding how the font should be treated when creating documents can be recorded. Dvipdfmx uses this information to decide whether embedding font into the document is permitted. This font embedding information is indicated by a flag called as "fsType" flag; each bit representing different restrictions on font embedding. If multiple flag bits are set in fsType, the least restrictive license granted takes precedence in dvipdfmx. The fsType flag bits recognized by dvipdfmx is as follows: * Installable embedding All font with this type of license can be embedded. * Editable embedding All font with this type of license can be embedded. * Embedding for Preview & Print only Dvipdfmx give the following warning message for fonts with this type of license: This document contains `Preview & Print' only licensed font For the font with this type of licensing, font embedding is allowed solely for the purpose of (on-screen) viewing and/or printing the document; further editing of the document or extracting an embedded font data for other purpose is not allowed. To ensure this condition, you must at least protect your document with non-empty password. All other flags are treated as more restrictive license than any of the above flags and treated as "No embedding allowed"; e.g., if both of the editable-embedding flag and unrecognized license flag is set, the font is treated as editable-embedding allowed, however, if only unrecognized flags are set, the font is not embedded. Embedding flags are preserved in embedded font if the font is embedded as a TrueType font or a CIDFontType 2 CIDFont. For all font embedded as a PostScript font (CFF, CIDFontType 0 CIDFont), they are not preserved. Only /Copyright and /Notice in the FontInfo dictionary are preserved in this case. Some font vendors put different embedding restrictions for different condition; e.g., font embedding might be not permitted for commercial materials unless you acquire "commercial license" separately. Please read EULA carefully before making decision on font usage. Adobe provide a font licensing FAQ and a list of embedding permissions for Adobe Type Library fonts: http://www.adobe.com/type/browser/legal/ For Japanese font in general, embedding permission tend to be somewhat restrictive. Japanese users should read the statement regarding font embedding from Japan Typography Association (in Japanese): http://www.typo.or.jp/info/morals/moral4.html