mkfontdir/mkfontdir.man

   1 .\" Copyright 1993, 1994, 1998  The Open Group
   2 .\"
   3 .\" Permission to use, copy, modify, distribute, and sell this software and its
   4 .\" documentation for any purpose is hereby granted without fee, provided that
   5 .\" the above copyright notice appear in all copies and that both that
   6 .\" copyright notice and this permission notice appear in supporting
   7 .\" documentation.
   8 .\"
   9 .\" The above copyright notice and this permission notice shall be included
  10 .\" in all copies or substantial portions of the Software.
  11 .\"
  12 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  13 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  14 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  15 .\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
  16 .\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
  17 .\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  18 .\" OTHER DEALINGS IN THE SOFTWARE.
  19 .\"
  20 .\" Except as contained in this notice, the name of The Open Group shall
  21 .\" not be used in advertising or otherwise to promote the sale, use or
  22 .\" other dealings in this Software without prior written authorization
  23 .\" from The Open Group.
  24 .\"
  25 .TH MKFONTDIR __appmansuffix__ __xorgversion__
  26 .SH NAME
  27 mkfontdir \- create an index of X font files in a directory
  28 .SH SYNOPSIS
  29 .B "mkfontdir"
  30 .RB [ \-n ]
  31 .RB [ \-x
  32 .IR suffix ]
  33 .RB [ \-r ]
  34 .RB [ \-p
  35 .IR prefix ]
  36 .RB [ \-e
  37 .IR encoding-directory-name ]
  38 \&\|.\|.\|.
  39 .RB [ \-\- ]
  40 .RI [ directory-name
  41 \&\|.\|.\|. ]
  42 .SH DESCRIPTION
  43 For each directory argument,
  44 .I mkfontdir
  45 reads all of the font files in the
  46 directory searching for properties named "FONT", or (failing that) the name
  47 of the file stripped of its suffix.  These are converted to lower case and
  48 used as font names, and,
  49 along with the name of the font file, are
  50 written out to the file "fonts.dir" in the directory.
  51 The X server and font server use "fonts.dir" to find font files.
  52 .PP
  53 The kinds of font files read by
  54 .I mkfontdir
  55 depend on configuration
  56 parameters, but typically include PCF (suffix ".pcf"), SNF (suffix ".snf")
  57 and BDF (suffix ".bdf").  If a font exists in multiple formats,
  58 .I mkfontdir
  59 will first choose PCF, then SNF and finally BDF.
  60 .PP
  61 The first line of fonts.dir gives the number of fonts in the file.
  62 The remaining lines list the fonts themselves, one per line, in two
  63 fields.  First is the name of the font file, followed by a space and
  64 the name of the font.
  65 .SH "SCALABLE FONTS"
  66 Because scalable font files do not usually include the X font name, the
  67 file "fonts.scale" can be used to name the scalable fonts in the
  68 directory.
  69 The fonts listed in it are copied to fonts.dir by
  70 .IR mkfontdir .
  71 "fonts.scale" has the same format as the "fonts.dir" file, and can be
  72 created with the
  73 .IR mkfontscale (__appmansuffix__)
  74 program.
  75 .SH "FONT NAME ALIASES"
  76 The file "fonts.alias", which can be put in any directory of the font-path, is
  77 used to map new names to existing fonts, and should be edited by hand.  The
  78 format is two white-space separated columns, the
  79 first containing aliases and the second containing font-name patterns.
  80 Lines beginning with "!" are comment lines and are ignored.
  81 .PP
  82 If neither the alias nor the value specifies the size fields of the
  83 font name, this is a scalable alias.  A font name of any size that
  84 matches this alias will be mapped to the same size of the font that
  85 the alias resolves to.
  86 .PP
  87 When a font alias is used, the name it references is searched for in the normal
  88 manner, looking through each font directory in turn.  This means that the
  89 aliases need not mention fonts in the same directory as the alias file.
  90 .PP
  91 To embed white space in either name, simply enclose it in double-quote
  92 marks; to embed double-quote marks (or any other character), precede them
  93 with back-slash:
  94 .PP
  95 .nf
  96 "magic-alias with spaces"       "\\"font name\\" with quotes"
  97 regular-alias                   fixed
  98 .fi
  99 .PP
 100 If the string "FILE_NAMES_ALIASES" stands alone on a line, each file-name
 101 in the directory (stripped of its suffix) will be used as an alias for
 102 that font.
 103 .SH ENCODING FILES
 104 The option
 105 .B -e
 106 can be used to specify a directory with encoding files.  Every such
 107 directory is scanned for encoding files, the list of which is then
 108 written to an "encodings.dir" file in every font directory.  The
 109 "encodings.dir" file is used by the server to find encoding
 110 information.
 111 .PP
 112 The "encodings.dir" file has the same format as "fonts.dir".
 113 It maps encoding names (strings of the form
 114 .BI CHARSET_REGISTRY \- CHARSET_ENCODING
 115 ) to encoding file names.
 116 .SH OPTIONS
 117 The following options are supported:
 118 .TP
 119 .B \-e
 120 Specify a directory containing encoding files.  The
 121 .B \-e
 122 option may be specified multiple times, and all the specified
 123 directories will be read.  The order of the entries is significant, as
 124 encodings found in earlier directories override those in later ones;
 125 encoding files in the same directory are discriminated by preferring
 126 compressed versions.
 127 .TP
 128 .B \-n
 129 do not scan for fonts, do not write font directory files.  This option
 130 is useful when generating encoding directories only.
 131 .TP
 132 .B \-p
 133 Specify a prefix that is prepended to the encoding file path names
 134 when they are written to the "encodings.dir" file.  The prefix is
 135 prepended as-is.  If a `/' is required between the prefix and the path
 136 names, it must be supplied explicitly as part of the prefix.
 137 .TP
 138 .B \-r
 139 Keep non-absolute encoding directories in their relative form when
 140 writing the "encodings.dir" file.  The default is to convert relative
 141 encoding directories to absolute directories by prepending the current
 142 directory.  The positioning of this options is significant, as this
 143 option only applies to subsequent
 144 .B \-e
 145 options.
 146 .TP
 147 .BI "\-x " suffix
 148 Ignore fonts files of type
 149 .IR suffix .
 150 .TP
 151 .B \-\-
 152 End options.
 153 .SH FILES
 154 .TP 15
 155 .B fonts.dir
 156 List of fonts in the directory and the files they are stored in.
 157 Created by \fImkfontdir\fP.  Read by the X server and font server each
 158 time the font path is set (see xset(__appmansuffix__)).
 159 .TP 15
 160 .B fonts.scale
 161 List of scalable fonts in the directory.  Contents are copied to
 162 fonts.dir by \fImkfontdir\fP.   Can be created with
 163 .IR mkfontscale (__appmansuffix__).
 164 .TP 15
 165 .B fonts.alias
 166 List of font name aliases.
 167 Read by the X server and font server each
 168 time the font path is set (see xset(__appmansuffix__)).
 169 .TP 15
 170 .B encodings.dir
 171 List of known encodings and the files they are stored in.
 172 Created by \fImkfontdir\fP.  Read by the X server and font server each
 173 time a font with an unknown charset is opened.
 174 .SH "SEE ALSO"
 175 X(__miscmansuffix__), Xserver(__appmansuffix__), mkfontscale(__appmansuffix__), xfs(__appmansuffix__), xset(__appmansuffix__)