$Header: /cvsroot/dvipdfmx/README,v 1.22 2004/04/11 05:37:58 hirata Exp $

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

Last modified: April 2, 2004


Copyright (C) 2002 by Jin-Hwan Cho and Shunsaku Hirata,
the dvipdfmx project team <dvipdfmx@project.ktug.or.kr>

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

4. Features

   4.1. Double-byte Encoding/Font Support
   4.2. CID-keyed Font
   4.3. Options for CID-keyed Font
   4.4. Advanced Typographic Features
   4.5. Unicode Support for Single-Byte Font

5. New PDF Specials

   5.1. tounicode
   5.2. literal
   5.3. fstream

6. Fontmap Examples

7. Incompatible Changes From Dvipdfm

8. Other Improvement Over Dvipdfm

   8.1. Encryption
   8.2. Graphics Support
   8.3. Font

9. Bugs

10. Font Licensing and Embedding

11. References



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 by using
   CID-keyed font technology. 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 the document from dvipdfm distribution for detailed
   instruction on how to install or how to use dvipdfm.

   The latest snapshot of the dvipdfmx is available at:

     http://project.ktug.or.kr/dvipdfmx/snapshot/

   The CVS repository for this project can be checked out through anonymous
   CVS 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 for anonymous, simply press the Enter key.

   The kpathsea library is required to compile and install dvipdfmx in UNIX
   or UNIX-like platforms. It is a part of common TeX distributions, for
   example, teTeX. See `INSTALL' for more details. If you already installed
   dvipdfm (the original) by yourself, you should already have a kpathsea
   library and it's headers installed on your system.

   The typical installation step for teTeX might look like:

     % ./configure --prefix=/usr/local/teTeX --with-png=/usr/local
     % make && make install

   If you are using libpaper to handle paper sizes for various program, it
   is highly recommended to use them. The location of libpaper library can
   be specified with the configure script option

     --with-paper=DIR

   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 libpaper
   installed on your system and using it, otherwise please edit the source
   code "dvipdfmx.c".


   In addition to the original dvipdfm, the following resources are used by
   dvipdfmx (not always required).


 1) CMap PostScript Resources

   Dvipdfmx uses CIDs to identify each glyphs for double-byte fonts (instead
   of glyph names used for single-byte fonts). And it uses CMap PostScript
   resources (like enc files in single-byte fonts) to convert DVI input text
   from DVI-internal encodings to a sequence of CIDs.

   All CJK (CID-keyed font) supporting features requires CMap resources.
   Please install CMap resource files under the directory (*1)

     ${TEXMF}/dvipdfm/CMap

   , or specify the directory containing CMap resource files with the
   variable CMAPINPUTS (*2) in your kpathsea configuration file

     ${TEXMF}/web2c/texmf.cnf

   The directory "data/CMap" in dvipdfmx source distribution contains a few
   CMap files written by the dvipdfmx project team. Adobe's "CMaps for PDF
   1.4 CJK Fonts" are available at:

     http://partners.adobe.com/asn/developer/technotes/acrobatpdf.html

   Standard CMap files for CJK-languages are also available at:

     ftp://ftp.oreilly.com/pub/examples/nutshell/cjkv/adobe/


   *1)  If you are using very recent version of teTeX (beta), please install
    Adobe's CMaps to ${TEXMF}/fonts/cmap/adobe and move all CMap's installed
    by dvipdfmx to ${TEXMF}/fonts/cmap/dvipdfmx or somewhere under directory
    ${TEXMF}/fonts/cmap.

   *2)  CMAPFONTS if your kpathsea library recognizes CMap files.


 2) SubFont Definition Files

   CJK fonts usually contains more than thousands of glyphs. To use them
   within TeX only capable of handling 7 or 8-bit encodings, they must be
   split into multiple smaller fonts (subfonts). And CJK-LaTeX and HLaTeX
   indeed employs this approach. However, dvipdfmx want a single font rather
   than multiple subfonts for various reason, and it provide a way to bundle
   up subfonts originated from a single font. This mapping is done through
   subfont definition (SFD) file.

   The subfont definition file describes how fonts are split into a set
   of subfonts, and is used by ttf2pk program. Please refer documents from
   ttf2pk program for detailed information on SFD file format.

   The SubFont Definition files must be installed under the directory(*2)
   
     ${TEXMF}/ttf2pk

   or

     ${TEXMF}/ttf2tfm

   to use the subfont related features required for CJK-LaTeX and HLaTeX
   packages.

   *2)  ${TEXMF}/fonts/sfd or use environment variable SFDFONTS in kpathsea
   configuration file if SFD files are installed in non-standard places for
   teTeX-beta-20040208 


 3) Glyph List File

   The (Adobe) glyph list (AGL) file describes the mapping between PostScript
   glyph names (e.g., AE, Aacute, ...) and it's corresponding Unicode values.
   Most features described in the section "Unicode Support For Single-Byte
   Font" requires this file.

   Dvipdfmx looks for a file "glyphlist.txt" when conversion from PostScript
   glyph names to Unicode is necessary. This conversion is done in various
   situations; creating ToUnicode CMap for simple (single-byte) fonts, and
   searching glyph description from Unicode TrueType fonts when the TrueType
   font itself does not provide the mapping from PostScript glyph names to
   glyph indices (version 2.0 "post" table).

   The content of this file should look like:

     # comment
     A;0041
     AE;00C6

   Each lines (not starting with '#') describe a mapping, first PostScript
   glyph name (without '/'), a semicolon delimiting each fields, and the
   corresponding Unicode values in uppercase hexadecimal notion.

   The "glyphlist.txt" file written by Adobe is found at

     http://partners.adobe.com/asn/tech/type/glyphlist.txt

   You must place the "glyphlist.txt" in a directory shown by

     kpsewhich --progname=dvipdfm --show-path="other text files"

   Please check that kpathsearch library can find this file by "kpsewhich"
   command:

     kpsewhich --progname=dvipdfm --format="other text files" glyphlist.txt

   The argument for --progname option is not dvipdfmx but dvipdfm, dvipdfmx
   pretends to be dvipdfm for some reasons (might be changed someday).


4. Features

4.1. Double-Byte Encoding/Font Support

   At present, Omega level-0/level-1 font metric (OFM) format and JFM TeX
   font metric format, which is an extended TeX font metric format used by
   ASCII pTeX, are supported for double-byte TeX font metric file.


 1) CMap

   The minimal set of CMaps required for each TeX variants/packages are:

    * ASCII pTeX: H and V

      ASCII pTeX always uses JIS encoding in their DVI output regardless of
      the input encoding (input encoding for TeX) you use. The appropriate
      CMaps are "H" (for horizontal writing) and "V" (for vertical writing).

    * CJK-LaTeX and HLaTeX: Depend on language and your setting.

      CMap file must be consistent with SFD file and font you are using.
      Which CMap is appropriate for your setting may be determined from
      CMap name, CMap files usually follows a naming convention:

       [Character Set]-[Encoding]-[Writing Mode]

      where the [Writing Mode] is H for horizontal and V for vertical.
      For example, UniCNS in [Character Set] indicates traditional Chinese
      (actually Adobe-CNS1) subset of Unicode, likewise, UniGB for Chinese
      in simplified forms (Adobe-GB1), UniKS for Korean (Adobe-Korea1), and
      UniJIS for Japanese (Adobe-Japan1). The [Character Set] field often
      contains a string that implies extension made by some hardware or
      software vendors; "90ms" means JIS X 0208:1990 with Microsoft Windows
      extension, "ETen" for ETen extension to Big five.
      The [Encoding] field is usually the name of character encoding, e.g.,
      UTF8, EUC, RKSJ (Roman-Kana Shift-JIS).


   See, section 4.2.3 for additional requirement on using TrueType fonts.


 2) Subfont Support

   Dvipdfmx has a capability of mapping a set of single-byte (TeX) fonts
   to a single double-byte font without relying on virtual fonts. Support
   for CJK-LaTeX and HLaTeX packages is realized by this function. You can
   do this mapping with SFD file. For example,

     gcr@UKS@  UniKS-UCS2-H GulimChe

   maps a set of single-byte fonts, gcr01, gcr02, ..., to an intermediate
   double-byte font gcr@UKS@ (KSC subset of Unicode, UCS-2 encoding used)
   according to the content of SFD file "UKS.sfd", and then maps it to a
   Type0 font "GulimChe-UniKS-UCS2-H" having an Adobe-Korea1 CID-keyed font
   "GulimChe" as a descendant CID-keyed font. (The encoding "Identity-H" is
   actually used in the output PDF file for all Type0 font, dvipdfmx does
   re-encode text.)


 3) Other Features

   Dvipdfmx allows users to have an access to the dvipdfmx's character code
   converter within TeX source. You can tell dvipdfmx to do conversion of
   PDF text strings appears in the pdf special command. For this feature a
   new PDF special command, pdf:tounicode is implemented. After this command,
   some of text string in PDF outlines, annotations, and document information
   will be converted according to the given CMap file. To do this, put one of
   the following code in the preamble of your LaTeX document source: 

     \AtBeginDvi{\special{pdf:tounicode GBK-EUC-UCS2}}

     \AtBeginDvi{\special{pdf:tounicode 90ms-RKSJ-UCS2}}

     \AtBeginDvi{\special{pdf:tounicode KSCms-UHC-UCS2}}

   In this examples, PDF strings are converted from CJK encodings to UCS-2.
   This feature is useful for including CJK characters in PDF outlines,
   annotations, and document information.(*1)

   There is a bug in pdf:tounicode, backslash '\' in PDF literal string is
   sometimes not treated as escape if pdf:tounicode feature is enabled.
   This can't be fixed for backward compatibility. Using hexadecimal notion
   <...> is recommended for multi-byte encodings.


   *1) Actually UTF-16BE... What dvipdfmx doing is, convert input text
   and add Unicode BOM for UTF-16BE at the begenning of resulting string.


4.2. CID-keyed Fonts

   There are three kinds of CID-keyed font supported by dvipdfmx.


 1) "Basic" CID-keyed Font

   The following CID-keyed fonts are defined in "src/cid_basefont.h".
   Those fonts can be used without having font itself.

     ---------------------------------------------------------
     Language     CSI              Font Name
     ---------------------------------------------------------
     Chinese(T)   Adobe-CNS1-0     MHei-Medium-Acro
                                   MSung-Light-Acro
                  Adobe-CNS1-4     AdobeMingStd-Light-Acro
     ---------------------------------------------------------
     Chinese(S)   Adobe-GB1-2      STSong-Light-Acro
                  Adobe-GB1-4      AdobeSongStd-Light-Acro
     ---------------------------------------------------------
     Japanese     Adobe-Japan1-2   HeiseiMin-W3-Acro
                                   HeiseiKakuGo-W5-Acro
                                   Ryumin-Light
                                   GothicBBB-Medium
                  Adobe-Japan1-4   KozMinPro-Regular-Acro
                                   KozGoPro-Medium-Acro
     ---------------------------------------------------------
     Korean       Adobe-Korea1-0   HYGoThic-Medium-Acro
                                   HYSMyeongJo-Medium-Acro
                  Adobe-Korea1-2   AdobeMyungjoStd-Medium-Acro
     ---------------------------------------------------------
     * "-Acro" can be omitted.


   For those fonts, minimal font information usually required by PDF viewers
   are available from the dvipdfmx's built-in data. However, they does not
   contain any glyph (outline or bitmap) data required to draw actual shape
   of each glyphs. Hence, PDF viewers must replace those fonts with suitable
   one available from the system.

   This means that the reproducibility of document layout, when the document
   is opened on the recipient's system, is not guaranteed at all, however,
   it works quite well for CJK text if you do not use special glyphs in your
   document. Please use those fonts if you are sure that all peoples who
   receives your documents have suitable fonts installed on their system and
   if your interest is only the file size.

   Some of those fonts are available from Adobe as a part of Acrobat Reader
   Asian Font Packs for use with Acrobat Reader.

   Please do not confuse them with PostScript Standard fonts. This feature is
   provided only for convenience. Do not expect you can always obtain correct
   result since font substitution is dependent on ability of PDF viewers.
   Note that proportional glyphs are not supported for those fonts.
   Basically, only glyphs of which widths are determined solely from their
   CID and character collection they belong to (but do not differ among
   different font) are supported; i.e., full-, half-, quarter-, and third-
   width forms.


 2) CFF/OpenType Font

   OpenType CID-keyed font is supported. Those fonts are embedded by default
   when editable-, installable-, or preview and print- embedding fsType flag
   is set in the OS/2 OpenType table. Always subsetted.

   There are few differences in OpenType (CIDFont) support between dvipdfmx
   and other software regarding the treatment of "OpenType" fonts:
   In dvipdfmx generated PDF, embedded CID fonts inherit all glyph metric
   information from the original OpenType font's hmtx, vmtx, and VORG tables
   in their CIDFont dictionary entries W and W2. This difference especially
   affects when you are using pre-rotated forms of proportional glyphs; The
   W2 metrics of CIDFont may contain proportional vertical displacement in
   the case of dvipdfmx, while other converter like Distiller may treat them
   like fixed-pitch font, and place each glyphs with position adjustment for
   compensating the difference from OpenType vertical metrics.
   You should prepare TeX font metrics using information from vmtx and VORG
   for vertical typesetting.

   For the position vector (it describes displacement from the origin used
   for horizontal writing to the origin used for vertical writing), the
   vertical component of position vector is taken from VORG table whenever
   available, otherwise, all vertical component of the position vector is
   set to sTypoAscender value in OS/2 table, and the horizontal component
   is estimated from the horizontal advance width wx as wx/2.
   Currently, dvipdfmx does not make use of BASE table.

   Please note that dvipdfmx does not really treat them as OpenType fonts,
   they are treated much like a CIDFont; glyphs are accessed by their CIDs,
   but not via Unicode --[OpenType cmap]--> GID route.


 3) Using TrueType Font as CIDFontType2 CIDFont

   When a valid CMap is specified in the encoding field of the font mapping
   and the font is mapped to a TrueType font, then dvipdfmx will treat that
   TrueType font as a CIDFontType2 CIDFont. In this case, dvipdfmx requires
   extra information and resources to handle TrueType font as CIDFont.

   The first one is the name of character collection to be used. This tells
   dvipdfmx information about glyph set covered by that font and ordering
   of them, and is specified by appending a '/' and the string denoting it
   immediately after the font name as follows:

     mincho UniJIS-UCS2-H ttmincho/AJ14

   In the above example, the "ttmincho" is converted to a CIDFont with
   Adobe-Japan1-4 character collection. (AJ1 is an alias for Adobe-Japan1
   that dvipdfmx recognizes and the integer 4 is the value of Supplement)
   It is not mandatory if you are not using Identity CMaps; dvipdfmx will
   use the information available from CMaps applied to TrueType font; The
   following font map entry

     mincho UniJIS-UCS2-H ttmincho

   implies Adobe-Japan1-4 since the CMap "UniJIS-UCS2-H" is a mapping from
   character codes in UCS-2 to CIDs in Adobe-Japan1-4 character collection.

   However,
   
     ommincho Identity-H ttmincho

   does not suggest any useful information since Identity CMap is generic
   CMap that does not implies any specific character collection.
   Abbreviation AK1, AC1, AG1 can be used for Adobe-Korea1, Adobe-CNS1, and
   Adobe-GB1, respectively.

   The next one is ToCode mapping CMap file. This CMap resource is always
   required for embedding a TrueType font as a CID-keyed font. (Except the
   case that Identity-H CMap is used together with /UCS option and TrueType
   font has a Unicode TrueType cmap table. The ToCode mapping is identity
   mapping in this case.)

   This file describes the mapping between CID numbers and the corresponding
   character codes in the encoding supported by TrueType cmap (character to
   glyph index mapping) table, the inverse mapping of usual CMaps.
   For example, in order to embed Japanese TrueType fonts supporting Unicode
   encoding as Adobe-Japan1 CIDFonts, the CMap file "Adobe-Japan1-UCS2" is
   required, this file describes mapping from CID numbers of Adobe-Japan1
   character collection to the corresponding Unicode values.

   Here is a list of required CMaps for each TrueType encodings supported
   by dvipdfmx and for Adobe's character collections:

     ----------------------------------------------------------------
     Encoding        PID  EID   CSI            ToCode CMap
     ----------------------------------------------------------------
     Unicode         3    1     Adobe-GB1      Adobe-GB1-UCS2
                                Adobe-CNS2     Adobe-CNS1-UCS2
                                Adobe-Japan1   Adobe-Japan1-UCS2
                                Adobe-Korea1   Adobe-Korea1-UCS2
     ----------------------------------------------------------------
     RPC     (WIN)   3    3     Adobe-GB1      Adobe-GB1-GBK-EUC
             (MAC)   1   25                    Adobe-GB1-GBpc-EUC
     ----------------------------------------------------------------
     Big5    (WIN)   3    4     Adobe-CNS1     Adobe-CNS1-ETen-B5
             (MAC)   1    2                    Adobe-CNS1-B5pc
     ----------------------------------------------------------------
     SJIS    (WIN)   3    2     Adobe-Japan1   Adobe-Japan1-90ms-RKSJ
             (MAC)   1    1                    Adobe-Japan1-90pv-RKSJ
     ----------------------------------------------------------------
     Wansung (WIN)   3    5     Adobe-Korea1   Adobe-Korea1-KSCms-UHC
             (MAC)   1    3                    Adobe-Korea1-KSCpc-EUC
     ----------------------------------------------------------------
     PID: Platform ID, EID: Platform-Specific Encoding ID


   Those CMaps are available from Adobe. You may already have those files
   somewhere on your hard-disk if you have installed Acrobat (Reader) or
   GhostScript.

   TrueType font support is implemented through some compatibility layer to
   CID-keyed font:


     |  Usual Multi-Byte Font Support | TrueType-CIDFont Compatibility  |

            +--<SFD>-> [SFD Encoding]
            |              |
     [Input Encoding] --<CMap>--> [CID] --<ToCode CMap>
                                    |           |
           +----> [PDF Output] <----+           +--> [TrueType Encoding]
           |                        |                         |        
           |                        |                         |
           +---- [Glyph Desc.] <----+----(TrueType cmap)------+


   All the above extra-information/resources are related to this.


4.3. Options for CID-keyed 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.


 4) Map Option

   This option is usually not necessary. It it still available but use of
   this option is not recommended because it is not compatible with dvipdfm.
   Dvipdfm (the original) will fail to read fontmap file if this option is
   present.


4.4. Advanced Typographic Features

   Experimental support for single glyph substitution for selecting vertical
   representation forms from TrueType fonts (vert/vert2) is available.


 1) Vertical Typesetting

   Dvipdfmx supports "vertical text mode" and "vertical direction mode".
   The vertical text mode is automatically enabled when the current CMap's
   /WMode is 1. All double-byte characters are rotated 90 degrees in the
   counter-clockwise direction in the horizontal direction mode, when the
   current text mode is vertical. This might be useful for pseudo vertical
   typesetting: typeset horizontally, rotate CJK text (use -V CMaps), and
   rotate all pages in the opposite direction with:

     \special{pdf:put @pages << /Rotate 90 >>}

   The direction mode is switched by DVI command "dir" (opcode 255). This is
   an extension made by ASCII pTeX and not supported by TeX and others. The
   argument of "dir" command is an unsigned byte; value 0 changes direction
   mode to horizontal, and value 1 changes it to vertical. All "horizontal"
   text and graphics object such as rules and images are rotated 90 degrees
   in the clockwise direction in the vertical direction mode.


4.5. Unicode Support For Single-Byte Font

   At present, dvipdfmx does not support Unicode.


 1) ToUnicode CMap Support

   Dvipdfmx will automatically create ToUnicode CMaps for fonts using
   encodings other than the "WinAnsiEncoding", "MacRomanEncoding", and
   "MacExpertEncoding".

   Dvipdfmx read mapping data necessary for converting PostScript glyph
   names to Unicode from the file "glyphlist.txt". And ToUnicode CMap is
   created for each encodings. If 10% of glyph names cannot be converted
   to Unicode, ToUnicode CMap is not embedded for that encoding.
   Please use "-v" option to find out which encodings dvipdfmx failed to
   embed ToUnicode CMap, and "-vvv" to outputs all glyphs that the mapping
   to the corresponding Unicode value is not available.

   This feature is not available for PK font.


5. New PDF Specials


5.1 tounicode


5.2 literal


5.3 fstream

   You can create PDF stream object from an existing file with pdf:fstream
   special command.

     \special{pdf: fstream @objname (filename) [DICT]}


   Example 1: File Attachment Annotation

   The following example will embed LaTeX source file into PDF, and
   create an PDF annotation with PushPin icon:

     \documentclass{article}
     \AtBeginDvi{
     \special{pdf:fstream @file_source (\jobname.tex)
        <<
          /Type /EmbeddedFile
        >>
     }
     \special{pdf:object @fspec_source
        <<
           /Type /Filespec
           /F (\jobname.tex)
           /EF << /F @file_source >>
        >>
     }
     }
     \begin{document}
     \makebox[10pt][l]{
     \special{pdf:ann width 10pt height 8pt depth 2pt
       <<
         /Type /Annot
         /Subtype /FileAttachment
         /Name /PushPin
         /C [0.8 0.4 0.4]
         /T (Author of This Document)
         /M (D:20031207000000)
         /Contents (TeX source file of this document.)
         /F 4
         /FS @fspec_source
       >>
     }}
     \end{document}

   Acrobat Reader for Linux does not support FileAttachment annotation.


   Example 2: Document Level XML Metadata

   There are no generic (object-level) metadata support and the only way
   to attach XML metadata is to use pdf specials (pdf:fstream for static
   content or pdf:object) and include raw XML packet.

   For document level metadata (metadata is placed in document catalog),
   you can attach XMP metadata stored in external file via:

     \special{pdf:fstream @meta (copyright.xmp)
       <<
         /Type /Metadata
         /Subtype /XML
       >>
     }
     \special{pdf:put @catalog << /Metadata @meta >>}

   Please note that no validation is made against embedded file stream.
   The included data may be compressed, in that case, simple metadata
   scanner may fail to extract embedded metadata.

   See, Adobe's XMP specification for XMP metadata format.


6. Fontmap Examples
   ----------------

   See, file "cid-x.map".


7. Incompatible Changes From Dvipdfm
   ---------------------------------

   Thumbnail support removed. The special command pdf:uxobj cannot be used
   for images read from external files. Font mapping entries always override
   previously declared one: This behavior is opposite of dvipdfm.


8. Other Improvement Over Dvipdfm
   ------------------------------


8.1. Encryption



8.2. Graphics Support


 1) Raster Images and Colors

    Embedded ICC profiles are supported for PNG and JPEG (JFIF) images.
    For PNG images with both gAMA (gamma) and cHRM (primary chromaticities)
    chunks, dvipdfmx uses calibrated color space (CalRGB and CalGray).
    For PNG images with sRGB chunk, an approximate CalRGB color space is
    used with parameters derived from CIE x, y values of white point and
    chromaticities of RGB primaries listed in PNG spec., v. 1.2., 4.2.2.3
    and the gamma value 2.2. (gAMA and cHRM is ignored in this case)
    Please note that dvipdfmx simply ignores gamma values if the PNG image
    only has gAMA but not cHRM.

    8-bit indexed color is supported for PNG. Bitdepth 16 gray or 48 RGB
    images are not supported, they are strip down to the maximum bitdepths
    supported by dvipdfmx (8 and 32).


  2) Transparency

    Transparency support is available for PNG images. Both alpha channels
    and tRNS chunks are supported. Soft mask is always used for PNG images
    with alpha channels, and color-key mask or soft-mask is selected for
    images with tRNS chunk.

    However, there are no generic PDF transparent imaging model support.


8.3. Font


  1) TrueType

    Dvipdfm embed whole TrueType font into PDF document, but in dvipdfmx,
    they are embedded as a font subset.

    TrueType font support is implemented through some compatibility layer
    to PostScript font:


      |  Usual Single-Byte Font Support | TrueType-PS Font Compatibility  |

      [Input Encoding] -<ENC>--> [Glyph Name] ---+--<AGL>---> [Unicode]
             |                         |         |                |
             |                         |  (TrueType post)  (TrueType cmap)
             |                         |         |                |
             |                   [Glyph Desc.] <-+----------------+
             |                         |
             +----> [PDF Output] <-----+


    There are few restrictions in TrueType support, but all characters
    found in Unicode BMP can be accessed using proper glyph names.


  2) CFF (OpenType)

    There are no difference between PostScript Type 1 font support; just
    prepare TFM and .enc files, and specify OpenType font file in fontmap
    instead of Type 1. PostScript CFF fontset resource and "raw" CFF font
    is not supported.


  3) Type 1

    Converted to CFF (Type 1C). Please report any problems.


9. Bugs
   ----

   See BUGS.


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



11. References
    ----------

  1) Font Licensing

     Adobe Technical Note #5147,
     "Font Embedding Guidelines for Adobe Third-party Developers"

  2) Adobe Solution Network | Adobe PDF

     http://partners.adobe.com/asn/tech/pdf/index.jsp


  3) Adobe Solution Network | Type Technology - CID-Keyed Fonts

     http://partners.adobe.com/asn/tech/type/cidfonts.jsp


  4) Microsoft Typography

     http://www.microsoft.com/typography/default.mspx


  5) PDF Techniques for Web Content Accessibility Guidelines

     http://www.w3.org/WAI/GL/2000/12/pdf.html

     Dvipdfmx does not produce PDFs compliant with this guideline.
     (This can't be done with dvipdfmx alone)
