$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 <[email protected]>

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:[email protected]:/home/cvsroot login
    cvs -d:pserver:[email protected]:/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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.