-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  X TrueType Server Version 1.4.2 [Charles's Wain]

  Installation Manual

  (C)1998,1999 X TrueType Server Project  All rights reserved.
  (C)2003 After X-TT Project  All rights reserved.
                          Time-stamp: <2003-10-15 18:12:18 cyamauch>
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

 This file describes how to install X-TT.

 Currently, X-TT is released as a patch for XFree86 4.3.0.  The
 procedure below explains how to install X from the source tree.

----------------
1. Preparation
----------------

 1.1 Files needed
 ----------------
  You need the following:

   * This package; xtt-1.4.1.tar.gz.
   * The XFree86 source: X430src-1.tgz, X430src-2.tgz and X430src-3.tgz.
     For full installation, X430src-4.tgz, X430src-5.tgz, X430src-6.tgz and
     X430src-7.tgz are also needed.
   * TrueType fonts.
   * GNU patch. (One of Ver2.5 or later is ***mandatory***)

 1.2 Apply X-TT patches to XFree86
 -----------------------------------
  This package (xtt-1.4.1.tar.gz) contains the following files:

    * xtt-1.4.1-xf430-changes.patch and xtt-1.4.1_to_1.4.2.patch (mandatory)
        Patches to use new X-TT with XFree86.

    * X430-ServersOnly.patch (optional)
        Patch for building X server only.
        
  Then apply the patch.

  1.2.1 Building X server only
  ----------------------------
   If you only need to build the X server, you do not need the entire XFree86
   source.  Obtain the file X430src-1.tgz from any XFree86 distribution, then
   apply the patch.

   *** Example ***
    ----------------------------------------------------------------------
    % tar zxvf **SOMEWHERE**/X430src-1.tgz
    % tar zxvf **SOMEWHERE**/X430src-2.tgz
    % tar zxvf **SOMEWHERE**/X430src-3.tgz
    % patch -p0 < **SOMEWHERE**/X430-ServersOnly.patch
    % patch -p0 < **SOMEWHERE**/xtt-1.4.1-xf430-changes.patch
    % patch -p0 < **SOMEWHERE**/xtt-1.4.1_to_1.4.2.patch
    ----------------------------------------------------------------------

  1.2.2 Full install from sources
  -------------------------------
   You need to obtain the following files:
   X430src-1.tgz, X430src-2.tgz, X430src-3.tgz, 
   X430src-4.tgz, X430src-5.tgz, X430src-6.tgz and X430src-7.tgz.

    ---------------------------------------------------------------------
    % tar zxvf **SOMEWHERE**/X430src-1.tgz
    % tar zxvf **SOMEWHERE**/X430src-2.tgz
    % tar zxvf **SOMEWHERE**/X430src-3.tgz
    % tar zxvf **SOMEWHERE**/X430src-4.tgz
    % tar zxvf **SOMEWHERE**/X430src-5.tgz
    % tar zxvf **SOMEWHERE**/X430src-6.tgz
    % tar zxvf **SOMEWHERE**/X430src-7.tgz
    % patch -p0 < **SOMEWHERE**/xtt-1.4.1-xf430-changes.patch
    % patch -p0 < **SOMEWHERE**/xtt-1.4.1_to_1.4.2.patch
    ---------------------------------------------------------------------


 1.3 Configure the build options of XFree86
 ------------------------------------------
  To use the basic features of X-TT, all you need to do is to apply 
  the above patches and install the files.  However, you
  can customize X-TT by setting the following macros appropriately:

  Macro name              Description
  -------------------------------------------------------------------------
  BuildXTrueType          Set 'NO' if you need not to use TrueType
                          font by using X-TT. If you want to use X-TT,
                          you must not set 'NO'.
                          (Default : YES)


  Typically, these options are described in file 'xc/config/cf/xf86site.def'.
  Refer to the comments in xf86site.def for futher information.


 1.4 Compile and Install
 -----------------------

 1.5.1 Those who want to install all XFree86 4.3.0 files at the same time
 ------------------------------------------------------------------------
       or, install X server only
       -------------------------------------------
  If xf86site.def is set appropriately, simply type:

   % cd xc
   % make World
   # make install


----------------------
2. SETTING UP FONTS
----------------------

 2.1 Preparing the directory for fonts
 -------------------------------------
  Designate a directory for font files.  Then, put the files into that
  directory.  If you have Windows font files for MS-DOS file systems,
  making symbolic links to them might be helpful.


 2.2 Preparing fonts.dir file
 ----------------------------
  Create a 'fonts.dir' file in the fonts directory. The format of the
  file should be:

     First line: the number of fonts which are contained in 
                 fonts.dir.
     the rest:   pairs consist of the name of the font file and
                 corresponding XLFD (X Logical Font Descriptor).
                 Each of the pair is in the following form.

       FILENAME   FOUNDRY-FAMILY-WEIGHT-SLANT-WIDTH--0-0-0-0-SPACING-0-CHARSET

  Note: you must define at least one XLFD for each font.

  XLFD can either be written manually, or generated by a
  perl script "mkttfdir.pl".  For obtain mkttfdir.pl, please refer to the
  following URI:

    http://www.io.com/~kazushi/xtt/

  With X-TT installed, the syntax of fonts.dir file for TrueType fonts
  is extended with the facility called "TTCap".  This extension
  enables users to control TrueType specific properties, such as
  transformation of glyphs. For TTCap, please refer to the
  section 3 of this document.

  The following describes the meaning for each fields in XLFD, as well
  as how to specify them.

  2.2.1 FOUNDRY and FAMILY fields
  -------------------------------
   - FOUNDRY: Font provider name
   - FAMILY:  Font family name

   You can arbitrary set the above fields.

   Netscape Navigator users should note that the name of the font is
   denoted in the form:

     "FOUNDRY(FAMILY)"

   in the font selection dialog.


  2.2.2 WEIGHT field
  ------------------
   - WEIGHT:  Indicates the looks of the glyph. Appropriate value
              is either 'normal' or 'bold'.

   This field should be set to match the glyph of the font.


  2.2.3 SLANT field
  -----------------
   - SLANT:   Indicates the looks of the glyph. Valid value is
              either:

                'r' :  for regular (upright) fonts,
                'i' :  for italic fonts,
                'ri':  for reverse italic fonts,
                'o' :  for oblique upright fonts, or
                'ro':  for reverse oblique upright fonts.


  2.2.4 WIDTH field
  -----------------
   - WIDTH:   Indicates the width.  Typically set to `normal'.


  2.2.5 SPACING field
  -------------------
   - SPACING: Indicates the spacing of the glyphs.  Valid value is
              either:

                p: proportionally spaced,
                m: mono spacing, or
                c: constantly spaced.

              For TrueType fonts, this field's value alters how X-TT
              calculates the bounding boxes.

              If 'p' is set, the bounding boxes are calculated for
              each glyphs when requested for the metric
              information.  If the font metric differs by each character,
              this causes the font to be proportional.
              MAX/MIN values are determined by comparing all the
              bounding boxes.

              If 'm' is set, the boundary of each glyphs are
              calculated as in the case of 'p', though the MAX/MIN
              value is determined as in the case of 'c'.

              If 'c' is set, the parameters on the glyphs are obtained
              from the property of the font, obtained in the header.

    It takes an unbeliveably long time to initialize a large charset font like
    CJK when you specify 'p' here.  It is similar to specifying
    'm' with xfs for CJK.  On the other hand, for
    small charset such like iso8859-1, 'p' would be appropriate.

    TTCap enables flexible specifications.


  2.2.6 CHARSET field
  -------------------
   - CHARSET:  Indicate the character set of the font.

   Examples of CHARSETS:

      jisx0201.1976-0
      jisx0208.1983-0
      iso8859-1
      unicode-0
      iso10646-0

   Extracting multiple character sets becomes possible for some TrueType fonts
   (if available) by specifying this field.

   Examples of multiple charset extracting:

   Original font            Charsets extracted
   -------------------------------------------
   ascii                    ascii.
   iso8859-1                ascii, iso8859-1.

   Shift-JIS                ascii,
                            iso8859-1(*2),
                            jisx0201, jisx0208.

   Unicode                  ascii, iso8859-1, unicode,
                            jisx0201, jisx0208, and others...

----
(*2) In the strictest sense, this is not the correct thing to do.  Though the
     most part of iso8859-1 is included in jisx0201, it is not a
     proper inclusion.  Nonetheless, X-TT does not treat this as an error,
     by convention.


 2.3 Example of fonts.dir file
 -----------------------------

  Example of fonts.dir is following:
   ========================================================================
   8
   dfhsmw3.ttc -dynalab-mincho-medium-r-normal--0-0-0-0-c-0-jisx0208.1983-0
   dfhsmw9.ttc -dynalab-mincho-bold-r-normal--0-0-0-0-c-0-jisx0208.1983-0
   dfhsgw3.ttc -dynalab-gothic-medium-r-normal--0-0-0-0-c-0-jisx0208.1983-0
   dfhsgw9.ttc -dynalab-gothic-bold-r-normal--0-0-0-0-c-0-jisx0208.1983-0
   arial.ttf   -ms-arial-medium-r-normal--0-0-0-0-p-0-iso8859-1
   ariali.ttf  -ms-arial-medium-i-normal--0-0-0-0-p-0-iso8859-1
   arialbd.ttf -ms-arial-bold-r-normal--0-0-0-0-p-0-iso8859-1
   arialbi.ttf -ms-arial-bold-i-normal--0-0-0-0-p-0-iso8859-1
   ========================================================================

  The '8' in the top line indicates that there are 8 XLFD entries defined in
  this file.

  Each 'dfhs*.ttc' font file is from DynaLab.  "dfhsmw" and "dfhsgw"
  stands for "DynaLab Font Heisei Mincho for Windows", and "DynaLab
  Font Heisei Gothic for Windows" respectively.  "arial.ttf",
  "ariali.ttf", "arialbd.ttf" and "arialbi.ttf" are fonts from
  Microsoft Windows, named 'Arial'.


 2.4 Setting up /etc/X11/XF86Config and the Fontpath (X Server standalone)
 -------------------------------------------------------------------------
  For XFree86 servers, set up /etc/X11/XF86Config to use "xtt" module and
  to set the Fontpath.
  See XF86Config(5x) or XF86Config-4(5x) for details.

  Example for XF86Config:
   ========================================================================
   Section "Module"
   .....
   Load       "xtt"
   .....
   EndSection
   .....
   Section "Files"
   .....
   FontPath   "/usr/X11R6/lib/X11/fonts/TrueType"
   .....
   EndSection
   ========================================================================

  It is also possible to use xset fp+ or command line option.

  Example:
   ========================================================================
   % xset fp+ /usr/X11R6/lib/X11/fonts/TrueType
   % xset fp rehash
   ========================================================================

  See xset(1) for details.


-----------
3.  TTCap
-----------
 TTCap allows users to have control over the appearance of TrueType
 fonts.

 3.1 Syntax of TTCap
 -------------------
  The syntax of fonts.dir is extended for TTCap use.  Refer to the following
  example.

   -----------------
   ai=0.4:sb=0.6:cyberbit.ttf -cyberbit-fixed-medium-i-normal--0-0-0-0-c-jisx0201.1976-0
   -----------------

  The heading "ai=0.4:sb=0.6:" is the part extended by X-TT.  In this
  example, for the Cyberbit's font named "cyberbit.ttf", ANK part will
  be used as fixed width fonts.  Also, the glyphs are italicized.

  The options list is in the paired form "KEYWORD=VALUE," separated by a
  colon, and is placed in front of the fontname.


 3.2 Options for TTCap
 ---------------------
  Available options are the followings:

  * fn=INTEGER
    -- This option specifies the face number for TrueType Collection
       (*.ttc) file.
       (fn : Face Number)

  * ai=REAL_NUMBER
    -- This option specifies how the glyph is slanted.
       (ai : Automatic Italic)

  * fp=[yn]
    -- This option specifies how the font metrics are calculated.
       Setting this y makes the font treated as proportional.  Conversely n
       makes the font treated as fixed width.  If this option is not
       specified, the SPACING field of XLFD is used.  You should not
       use this option, since 'fs' makes this option obsolete.
       (fp : Force Proportional)

  * fs=[pmc]
    -- This option specifies how the font metrics are calculated.
       Font metric is calculated with regarding SPACING field of XLFD
       as specifying VALUE.  If this option is not specified, the
       SPACING field of XLFD is used.
       (fs : Force Spacing)

  * fc=Range    (This option available in Ver1.4.0beta1 or later versions.)
    -- Specify code range for forcing "xtt" to use constant spacing.
       The "Range" is specified as the one of following:
         number
         number-number
         -number
         number-
       Each "numbers" can be specified in octal, decimal, or hexadecimal. 
       Use the prefix '0' for octal, and similarly the prefix '0x' for 
       hexadecimal, to distinguish from decimal numbers. 
       In Ver1.4.0rc1 or later versions, a reverse
       number specificaton, e.g. `fc=0xaa00-0xa0ff', means
       specifying the range of 0x0000-0xa0ff and 0xaa00-0xffff.
       This option is available only for proportional spacing in "xtt", 
       and calculations of metrics on the specified code range are not 
       performed because they are handled as "-c-" spacing. This option
       is useful to achieve *extremely* fast loading of huge Japanese,
       GB18030 or unicode fonts with "-p-" in the XLFD.
       When using unicode, this and the "vl" option are literally
       indispensable. 
       (fc : Force Constant spacing code range).

  * fm=Code or fm=REAL_NUMBER,REAL_NUMBER,REAL_NUMBER
    (This option available in Ver1.4.0beta1 or later versions.)
    -- Set metrics in the range specified by "fc" Option.
       If the "fm" option is not set, the metrics in the range of "fc"
       specification become the bounding box of header information. But
       this is not always convenient; instead, you can specify the metrics
       by "Code" or "magnification ratio".
       If "Code" (e.g. fm=0x5a00) is set, upon loading the font, "xtt" 
       calculates the metrics of "Code" this first, and copies the metric to all
       glyphs in the "fc" specification.  On the other hand, when 
       "magnification ratio" (e.g. fm=0.5,0,0.5) is set, all glyphs in the
       "fc" obey this setting.  The numbers after "fm=" correspond to width,
       left side bearing and right side bearing, and is the magnification
       ratio to the width of bounding box of header information.
       (fm : Force constant spacing Metrics).

  * bw=REAL_NUMBER[;INTEGER,INTEGER,INTEGER]
    (Enhanced option in Ver1.4.0beta1 or later versions.)
    -- This option specifies the magnification ratio of the spacing 
       adjustment in pixel units to the bounding box width. 
       If this option is applied together with the following option 'sw',
       then bw scaling is done after the sw scaling.  If this option
       is not specified, the ratio is set to 1.
       Using a set of three additional integer parameters, you can set the
       adjustment value of width, left side bearing and right side bearing
       to each integer parameter in pixel units.  Some metrics calculation
       errors with the "vl=y" option can be corrected with this parameter.
       It is also useful in adjusting font spacing which can be too narrow
       or wide when small fonts are used. 
       (bw : Bounding box Width)

  * sw=REAL_NUMBER
    -- This option specifies the magnification ratio to the width of the
       glyph.  If this option is not specified, the ratio is set to 1.
       (sw : Scale Width)

  * ds=[ymn][b][;INTEGER]    (Enhanced option in Ver1.4.0beta1 or later versions.)
    -- Set this option y or m if you want double-strike boldfacing.
       When font size is small, conventional double striking may render the 
       fonts unreadable. Using "ds=m", the process leaves the edge of 
       bitmaps as is, which improves readability. (We have named this 
       process "mkbold method").
       To automatically adjust the bounding box, specify "ds=yb" or "ds=mb";
       In this case, the width of bounding box is increased by 1 pixel.  
       The last option INTEGER is the pixel size of the application limit 
       of "mkbold method".  When specified, the process is applied only when
       the font size is smaller than the specified pixel size.
       (ds : Double Strike)

  * vl=[yn]    (This option available in Ver1.1pl01 or later versions.)
    -- If you set this option to y, the font metrics is calculated by
       using the very lazy method, derived from the font
       header in the case of Proportional or Monospaced font.
       This is efficient if you want to use the proportional fonts
       which contain huge numbers of glyphs, e.g. MS P Gothic Japanese
       Font. (The use of such fonts is impractical if
       strict metrics calculation is employed.)
       Quick-and-dirty metric calculations improve response time;
       on the other hand, the metric information is not precise.
       (Such inprecision is unlikely to cause any serious problems.)
       For this reason, this option is undesirable for
       the fonts which contain only a few glyphs, such as the alphabetical
       fonts.
       If this option does not exist, the metric is calculated 
       using the strict method, which is derived from the outline
       datas.
       (vl : Very Lazy metrics calculation method)

  * eo=String
    -- Specifies options which are sent to code conversion module.  The
       string to be specified depends on the code converter module.
       (eo : Encoding Options)

  * hi=[yn]
    -- If you set this option to n, the FreeType renderer will not use
       the hint information in the font file.
       (hi : HInting)

  * cr=Range[,Range,...]
    -- Restrict code range of font.  Each of "Range" is specified
       in one of the following formats:
         number
         number-number
         -number
         number-
       You can specify fragmented ranges by separating each range
       with a comma; however X-TT would treat it as a single contiguous
       (i.e., not fragmented) range.  Each "numbers" can be specified 
       in octal, decimal, or hexadecimal.  Used the prefix '0' for octal,
       and similarly the prefix '0x' for hexadecimal, to distinguish from
       decimal numbers.
       This option is useful if you only need a portion of the glyph,
       especially in the Unicode font.  It differs from XLFD range 
       specification in a sense that, from the client, it would appear as
       having glyphs only within the specified range.
       (cr : Code Range)

  * eb=[yn]    (This option available in Ver1.1pl01 or later versions.)
    -- If you set this option to y, the FreeType renderer will try to
       use embedded bitmaps. However, the font file would need the 
       embedded bitmap data.
       You can use this option with "vl=y". But in the new version (1.4) 
       of X-TT, the "vl=y" specification without "bs" option is ignored when
       using embedded bitmap which has exclusive metrics.  If you want to use 
       "vl=y" calculation for embedded bitmap, basically you need to 
       use the "bs" option, since the bounding box value for embedded 
       bitmap is often different from the outlines.  
       In X-TT 1.4, embedded bitmaps are used when Auto Italic ("ai" option)
       is set when "eb=y".  If you don't want to use embedded bitmaps when
       Auto Italic is set, set "eb=n" to TTCap.  If "eb" is not set, 
       embedded bitmaps are used when Auto Italic is not set. 
       (eb : Embedded Bitmap)

  * bs=REAL_NUMBER
    -- If you specify this option concurrently with both "vl" and "eb",
       the bounding box which is generated from the embedded bitmaps is scaled
       to this value.  It does not affect the glyphs which are generated
       from outlines.
       In X-TT 1.4, if the embedded bitmap has exclusive metrics, the "vl=y"
       specification without "bs" option is not used for embedded bitmap
       ("vl=y" is used only for outlines).  Therefore, you do not
       need the "bs" option in this case.

  Note: all options are case insensitive.

----------------
4. bitmap cache
----------------
  From X-TT Ver1.3, users can limit the memory resource for bitmap cache.

  4.1 terms
  ---------
    * balance value
        It indicates the distribution of the memory pool.  X-TT bitmap cache
        has two kind of memory pools, which is chosen by the difference
        of bitmap size.  The total size of the cache is predetermined, and
        it is shared between both of the memory pools.  The balance
        value indicates this memory balance ratio.
    * hi-mark value
        It indicates the upper bound of the cache size.
    * low-mark value
        It indicates the lower bound of the cache size.
        If the cache overflows, the contents of the cache will be
        disposed of until the memory usage becomes under this value.

  4.2 adjusting the cache
  --------------------

   4.2.1 X server
   --------------
    For the X server, cache can be adjusted using xset that has been 
    compiled with the font cache extension.  Syntax is as follows:
      xset fc himark lowmark balance
    Here, himark and lowmark is specified in kBytes, and balance is in
    percent.  For instance, if you want to specify the himark to 1MBytes,
    lowmark to 500kBytes, and balance to 50%, then use the following command:
      xset fc 1000 500 50

# end of file
