summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/man/man1/cmap2enc.1
blob: b57fc021fd1373d76b7d2bbf65d278cd4f846c7a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
.\" Automatically generated by Pod::Man version 1.15
.\" Thu Feb  8 11:04:39 2007
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "CMAP2ENC 1"
.TH CMAP2ENC 1 "fontools" "2007-02-08" "fontools"
.UC
.SH "NAME"
cmap2enc \- convert glyph indices in a TrueType-flavored OpenType font to
Adobe glyph names
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
cmap2enc [options] \fIfontfile\fR \fIencoding\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Many TrueType-flavored OpenType fonts contain no glyph names.
When creating an \fIafm\fR file with \fIttf2afm\fR, this causes all glyphs to be 
named something
like \f(CW\*(C`index0x01E7\*(C'\fR, which makes the \fIafm\fR file almost useless for use with 
\&\fIfontinst\fR or \fIafm2tfm\fR.
.PP
\&\fBcmap2enc\fR uses the font's `cmap' table to map glyph indices to
Unicode values, and Adobe's \fIglyphlist.txt\fR file to map these to glyph names.
.PP
\&\fBcmap2enc\fR creates a new encoding file (for downloading with the font file) 
and a \fImtx\fR file (for use with \fIfontinst\fR). The encoding file contains the 
same glyphs as the original one, but has all glyph names replaced with 
the corresponding glyph indices; the \fImtx\fR file maps these glyph indices back 
to the original glyph names (it consists of many commands of the form
\&\f(CW\*(C`\erenameGlyph{index0x01E7}{Euro}\*(C'\fR, plus a definition of that 
\&\f(CW\*(C`\erenameGlyph\*(C'\fR command).
.PP
Some of the glyph substitution features of OpenType fonts are supported; 
e.g. when the `smcp' (Small Caps) feature is specified, the glyph names 
of the lowercase glyphs will be mapped to the glyph indices of the 
small capitals.
.PP
A list of features supported by the font can be generated using the \fB\-p\fR
option, see below.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\s-1NOTE:\s0 the \fIexamples/\fR subdirectory in the \fIfontools\fR distribution contains 
several complete examples of the use of \fBcmap2enc\fR and other tools from
the \fIfontools\fR collection.
.Ip "\fB-\fR" 2
.IX Item "-"
To display all scripts, languages and features supported by Linotype Palatino:
.Sp
.Vb 1
\&    cmap2enc -p pala.ttf
.Ve
.Ip "\fB-\fR" 2
.IX Item "-"
To install Linotype Palatino in T1 encoding, with oldstyle figures:
.RS 2
.Ip "\fB1.\fR" 3
.IX Item "1."
Generate an encoding file \fIt1\-tosf-pala.enc\fR and a metrics file 
\&\fIresetpala-t1\-osf.mtx\fR:
.Sp
.Vb 1
\&    cmap2enc -f onum pala.ttf t1.enc
.Ve
.Ip "\fB2.\fR" 3
.IX Item "2."
Create an \fIafm\fR file for the font; this is done best using \fIfont2afm\fR 
(also in the \fIfontools\fR collection):
.Sp
.Vb 1
\&    font2afm pala.ttf
.Ve
.Ip "\fB3.\fR" 3
.IX Item "3."
Reencode the \fIafm\fR file using the \fIt1\-tosf-pala.enc\fR encoding to create 
a `raw' font \fIrlplrj9d\fR, with either \fIafm2afm\fR (also in the \fIfontools\fR 
collection) or \fIfontinst\fR (but be warned that \fIfontinst\fR might take a long
time, and can even crash if the \fIafm\fR is really big):
.Sp
.Vb 1
\&    afm2afm -e t1-tosf-pala.enc -o rlplrj9d.afm pala.afm
.Ve
or
.Sp
.Vb 1
\&    \etransformfont{rlplrj9d}{\ereencodefont{t1-tosf-pala}{\efromafm{pala}}}
.Ve
.Ip "\fB4.\fR" 3
.IX Item "4."
Create a `value-added' \fIvpl\fR file from this raw font by adding 
ligatures, faking missing glyphs etc. with \fIfontinst\fR:
.Sp
.Vb 2
\&    \einstallfont{lplrj9d}{rlplrj9d,resetpala-t1-tosf,newlatin}
\&        {t1}{T1}{lplj}{m}{n}{}
.Ve
.RE
.RS 2
.RE
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBcmap2enc\fR supports the following command-line options:
.Ip "\fB\-p\fR" 4
.IX Item "-p"
Print some info about the font, plus a list of all scripts, languages and 
features contained in this font's \s-1GSUB\s0 table; then exit. (When using
this option, the \fIencoding\fR need not be specified.)
.Ip "\fB\-f\fR \fIfeature\fR[,\fIfeature\fR]*" 4
.IX Item "-f feature[,feature]*"
Use the specified features when matching glyph indices to glyph names. 
Multiple features can be specified as a comma-separated list, 
\&\fBwithout\fR spaces between the items.
.Ip "\fB\-x\fR \fIextra\fR" 4
.IX Item "-x extra"
Use the user-specified substitutions from \fIextra\fR (see below).
.Ip "\fB\-l\fR \fIlanguage\fR" 4
.IX Item "-l language"
Select the specified language. The default is `\s-1DFLT\s0' (surprise!).
.Ip "\fB\-s\fR \fIscript\fR" 4
.IX Item "-s script"
Select the specified script. The default is `latn'.
.SH "FILES"
.IX Header "FILES"
All input files are searched using \fBkpsewhich\fR or \fBfindtexmf\fR when these 
commands are available; otherwise only the current working directory 
is searched.
.Ip "\fIfontfile\fR" 4
.IX Item "fontfile"
The font file can be any OpenType font, though \fBcmap2enc\fR is probably only 
useful for the TrueType-flavored variant (PostScript-flavored ones always 
contain glyph names in the `\s-1CFF\s0' table).
.Ip "\fIencoding\fR" 4
.IX Item "encoding"
The encoding files read and written by \fBcmap2enc\fR are in standard \fIdvips\fR 
format. The name of the output encoding file is 
\&\f(CW\*(C`<encoding>\-<suffix>\-<font>.enc\*(C'\fR, 
.Sp
where
.RS 4
.Ip "\fBencoding\fR" 10
.IX Item "encoding"
is the name of the input encoding file (without the extension `.enc');
.Ip "\fBsuffix\fR" 10
.IX Item "suffix"
names the OpenType features you specified:
.RS 10
.Ip "\fItlf\fR" 10
.IX Item "tlf"
for tabular lining figures (when neither the `onum' nor the `pnum' features
have been chosen)
.Ip "\fIlf\fR" 10
.IX Item "lf"
for proportional width lining figures (when you've specified `pnum', 
but not `onum')
.Ip "\fItosf\fR" 10
.IX Item "tosf"
for tabular oldstyle figures (when you've specified `onum', but not `pnum')
.Ip "\fIosf\fR" 10
.IX Item "osf"
for proportional width oldstyle figures (when both `onum' and `pnum' have been 
chosen)
.Ip "\fIsc\fR" 10
.IX Item "sc"
for small caps (`smcp' feature)
.Ip "\fIswash\fR" 10
.IX Item "swash"
for swash (`swsh' feature)
.Ip "\fItitling\fR" 10
.IX Item "titling"
for a titling font (`titl' feature)
.Ip "\fIsup\fR" 10
.IX Item "sup"
for superior figures and (some) letters (`sups' feature)
.Ip "\fIorn\fR" 10
.IX Item "orn"
for ornaments (`ornm' feature)
.RE
.RS 10
.Sp
When several features have been specified, the \fBsuffix\fR is a combination
of the appropriate items; e.g., when you specify \-f onum,pnum,swsh (for a 
swash font with proportional oldstyle figures) the \fBsuffix\fR is
\&\f(CW\*(C`osf\-swash\*(C'\fR.
.RE
.Ip "\fBfont\fR" 10
.IX Item "font"
is the name of the input font file, without the `.ttf' or `.otf' extension.
.RE
.RS 4
.RE
.Ip "\fImtx\fR" 4
.IX Item "mtx"
The output \fImtx\fR file is in standard \fIfontinst\fR format. The name of this file 
is \f(CW\*(C`reset<font>\-<encoding>\-<suffix>.mtx\*(C'\fR, 
.Sp
where \fIfont\fR, \fIencoding\fR and \fIsuffix\fR have the same meaning as above.
.Ip "\fIextra\fR" 4
.IX Item "extra"
The option \fB\-x\fR can be used to name a file containing extra substitutions 
that complement or override the ones specified by the selected features. 
It consists of one substitution per line; each is either of the form 
\&\f(CW\*(C`<from>;<to>\*(C'\fR, where \fIfrom\fR and \fIto\fR are both glyph indices
(specified as four hexadecimal digits), or of the form 
\&\f(CW\*(C`<glyph name>;<glyph index>\*(C'\fR, where \fIglyph name\fR is any glyph name
and \fIglyph index\fR the glyph index (again, four hex digits) that is to be
mapped to the specified glyph name. The \fIexamples/\fR subdirectory in the 
\&\fIfontools\fR distribution contains some examples of user-defined 
substitution files.
.SH "CAVEATS"
.IX Header "CAVEATS"
.Ip "\fB-\fR" 2
.IX Item "-"
Most OpenType fonts contain several tables in the `cmap' table, 
for different platforms and different encodings. 
\&\fBcmap2enc\fR only reads the first table that implements Unicode, that is, 
the first table with either platformID = 0 and encodingID = 3 or 4 
or platformID = 3 and encodingID = 1 or 10.
At least one of those will probably always be present, and (afaik) it doesn't
matter which of these is used.
.Sp
The fact that only tableFormat = 4 is supported might be more of a restriction, 
though I haven't yet found any font that used a different tableFormat.
.Ip "\fB-\fR" 2
.IX Item "-"
OpenType fonts implement features using so-called `Lookup Tables'. 
\&\fBcmap2enc\fR supports only features from the `\s-1GSUB\s0' table that have
LookupType = 1 (single substitution).
.Sp
Some features are implemented as a combination of lookups from both 
the `\s-1GSUB\s0' and the `\s-1GPOS\s0' tables; these features are (currently?)
not supported. An example of this are the `sinf' (Scientific Inferiors) and 
\&'subs' (Subscripts) features of Linotype Palatino; these are implemented 
by first replacing the standard numerals with smaller ones and then 
adjusting their position.
.Ip "\fB-\fR" 2
.IX Item "-"
Some of the font's features may yield surprising results. E.g., Linotype
Palatino doesn't have small-caps forms of dotlessi, germandbls and the
standard f-ligatures, so it will give you the lowercase forms of these glyphs
even when the `smcp' feature is specified. 
(The \fIexamples/palatinox\fR subdirectory contains a file \fIunsetSCaps.mtx\fR 
that deletes these lowercase forms; \fIfontinst\fR's \fInewlatin.mtx\fR file 
will then create fake small-caps forms of these glyphs.)
.Ip "\fB-\fR" 2
.IX Item "-"
If the user-defined substitution file substitutes glyph1 with glyph2, 
\&\fBcmap2enc\fR will also substitute glyph2 with glyph2; this may seem silly,
but it means that any selected feature that would substitute glyph2 with glyph3
gets overridden.
.Ip "\fB-\fR" 2
.IX Item "-"
The glyph names are independent of the features selected, e.g., when using 
features like `smcp' or `onum', glyph names still come out as `a' and `zero'
rather than `Asmall' and `zerooldstyle'. When installing the font with
\&\fIfontinst\fR, you should therefore always use \fIt1.etx\fR rather than \fIt1c.etx\fR
or \fIt1j.etx\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The other programs in the \fIfontools\fR bundle: \fIafm2afm\fR, \fIautoinst\fR, 
\&\fIfont2afm\fR, \fIot2kpx\fR, \fIpfm2kpx\fR, \fIshowglyphs\fR.
.PP
A good free (as in beer) Perl-implementation for Windows (and Linux)
is ActivePerl, available from \fIhttp://www.activestate.com\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marc Penninga <marc@penninga.info>
.PP
If you're sending a bug report, please give as much information as possible.
Also be sure to mention the name \fIfontools\fR somewhere in the subject line,
or risk being caught by my spam filter.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005, 2006 Marc Penninga. 
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of version 2 of the \s-1GNU\s0 General Public License 
as published by the Free Software Foundation.
.PP
A copy of the \s-1GNU\s0 General Public License is included with the \fIfontools\fR 
collection; see the file \fIGPLv2.txt\fR.
.SH "DISCLAIMER"
.IX Header "DISCLAIMER"
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the
\&\s-1GNU\s0 General Public License for more details.
.SH "HISTORY"
.IX Header "HISTORY"
.Ip "\fI2006\-01\-17\fR" 12
.IX Item "2006-01-17"
Changed the names of the generated output files; extended the documentation.
.Ip "\fI2005\-08\-01\fR" 12
.IX Item "2005-08-01"
Removed some warning messages that didn't convey any useful information; 
added contents of \fIglyphlist.txt\fR to the program itself and removed
the file from the \fIfontools\fR collection; 
expanded the example in the documentation
.Ip "\fI2005\-04\-29\fR" 12
.IX Item "2005-04-29"
Improved the documentation
.Ip "\fI2005\-03\-21\fR" 12
.IX Item "2005-03-21"
Fixed somed bugs; added `titl' feature
.Ip "\fI2005\-03\-15\fR" 12
.IX Item "2005-03-15"
Input files searched using \fBkpsewhich\fR or \fBfindtexmf\fR
.Ip "\fI2005\-03\-08\fR" 12
.IX Item "2005-03-08"
Input files searched via \fBkpsewhich\fR (where available)
.Ip "\fI2005\-02\-18\fR" 12
.IX Item "2005-02-18"
Rewrote some of the code, fixed a few bugs
.Ip "\fI2005\-01\-10\fR" 12
.IX Item "2005-01-10"
First version