updated with TeX Live 2014.

[putex/putex.git] / src / dvipdfmx-pu / README

The dvipdfmx Project
====================

Copyright (C) 2002-2013 by Jin-Hwan Cho, Shunsaku Hirata, and 
Matthias Franz, the dvipdfmx project team.  This package is released
under the GNU GPL, version 2, or (at your option) any later version.

dvipdfmx is now maintained as part of TeX Live.

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