tx -h

tx -h

tx Help
=======
[Note: brief usage is available with -u (usage) option.]

tx (Type eXchange) is a test harness for the CoreType libraries but also
provides many useful font conversion and analysis facilities. These facilities
are built around the Abstract Font Format (ABF) which is used to exchange font
data between the various library components. Further details of ABF may be
found in afdko/c/public/lib/api/absfont.h.

Input
-----
Font data is read from input, converted to ABF, which is then converted for
output. On input, the font technology type and format is automatically detected
by analyzing the first few bytes of input data. The appropriate library
component and input filter are then selected to perform the conversion to ABF.
The output conversion is performed by another library component that is
selected by a program mode option. A full list of options, including those for
selecting program modes, is available via the -u option.

フォントデータは入力から読み取られ、
ABFに変換されてから、出力用に変換されます。

入力時には、入力データの最初の数バイトを分析することにより、
フォント技術のタイプとフォーマットが自動的に検出されます。

次に、適切なライブラリコンポーネントと入力フィルターを選択して、
ABFへの変換を実行します。

出力変換は、プログラムモードオプションで選択された
別のライブラリコンポーネントによって実行されます。

プログラムモードを選択するためのオプションを含む
オプションの完全なリストは、-uオプションを介して利用できます。

Input conversion of the following font technologies is supported: 
Type 1 single master, 
Type 1 multiple master, 
Type 1 CID-keyed,
CFF single master, 
CFF CID-keyed, 
and 
TrueType. 

Conversion of font data represented in the following
formats is supported: 
PFA, 
PFB, 
LWFN-POST, 
FFIL-sfnt, 
OTF, 
TTF, 
TTC, 
and
AppleSingle/Double-sfnt. 

sfnt-formatted fonts with header versions of the
following kinds are supported: 
1.0,
 true,
 ttcf,
 typ1,
 CID,
 and 
OTTO.

Note that OCF is not supported by tx.

Multiple master fonts are always snapshot during input conversion. The snapshot
instance may be specified as a user design vector with -U (user design vector)
option, e.g -U 365,500. If the -U option is not specified the default instance
recorded within the font is used.

If the input font is an FFIL or a TTC containing multiple sfnts, a contents
list is displayed from which a specific sfnt may be selected using the -i
(index) option or every font may be selected using the -y (every) option in a
subsequent run of tx. The resource map of an FFIL may also be viewed with the
-r (resource) option or the entry descriptors in an AppleSingle/Double format
file may be viewed with the -R option.

By default, curve segments in TrueType glyph paths are converted from quadratic
to cubic Beziers using an optimization algorithm that coalesces adjacent curve
segments. 

However, an exact conversion may be specified with the -x (exact)
option. Also, the optimized and exact paths may be generated simultaneously for
comparison purposes with the -X (exact and optimized) option.


The parsing of Type 1 fonts, which are PostScript based and often encrypted,
can present the greatest challenges when the font is malformed. The -t (tokens)
option addresses this problem by dumping the PostScript token stream to
standard output as the font is parsed. The point of failure generally occurs
shortly after the last dumped token.

The Type 1 PostScript download formats generated by xcf and CoolType are also
supported. Generally, the download font will have to be excised from the
PostScript file using a text editor before it can be submitted to tx and
incremental portions of the font, occurring later in the file, will have to be
pasted back into the charstrings of the initial font. Also, be sure to add a
initial line of "%!", if one is not already present, to ensure that tx detects
the format correctly and selects the appropriate input library.

Subsetting
----------
An important aspect of tx is its ability to subset fonts by specifying a glyph
subset with the -g (glyphs) option. The argument to this option consists of a
comma-separated list of glyph identifiers which may be either a tag, glyph
name, or CID.

A tag specifies the glyph in a technology-specific way. The tag is incremented
for each glyph processed, starting from zero. Thus, the last glyph processed is
assigned a tag value that is one less than the number of glyphs in the font.
For sfnt-based fonts that tag is the same as the glyph index. For a naked-CID
font it is derived by counting non-empty intervals in the CIDMap, starting from
CID 0. For a Type 1 font it is the order number of the charstring in the
CharStrings dictionary, starting from 0.

Glyph names may be used with non-CID fonts, including TrueType fonts. CIDs may
only be used with CID-keyed fonts. A tag is specified as a positive integer,
e.g. 17. A CID is specified by a positive integer preceded by a / (slash)
character, e.g. /17. A glyph name is specified by a sequence of characters,
e.g. zero. Tags and CIDs may also be specified as a range by separating the
smallest and largest members of the range by a - (hyphen), e.g. 34-59.

(Note: the type tools convention for printing a CID is to precede it with a \
(backslash) character. However, / is used with the -g option because \ has a
special interpretation in most command shells.)

A CID-keyed font may also be subset by font dictionary with the -fd (font dict)
option. This option takes a single positive integer argument which specifies
the zero-based index of the font dictionary. Only glyphs that are rendered with
this dictionary are selected from the input font. It is considered a fatal
error to use this option with non-CID fonts or to specify an index that is
outside the range supported by the font.

A random subset can be generated by the -p or -P (percent) options. These
options take a single argument that specifies the subset size as a percentage
of the number of glyphs in the source font, and is thus a real value in the
range 0-100. If this calculation yields an empty subset the subset will be
forced to contain one glyph. The -p option produces repeatably random subsets
for a given source font whereas the -P option produces different random subsets
for each run.

The command line is conventionally specified by input options (described
above), followed by mode options (described by the -u (usage) option), and
finally by file options (which must be last). Each mode has its own options
which must follow the mode selection option. Mode-specific help is available by
specifying the -h (help) option after the mode selection option.

File options
------------
The file options provide a very flexible and powerful way of processing
multiple input and output files which are described briefly by the -u option.
Some of the file options are described more fully here.

The source font path is constructed by concatenating root, directory, and
filename components. The root and directory components are empty by default,
but may be specified with the -sr (source root) and -sd (source directory)
options, respectively. This allows some economy in specifying file paths and
becomes especially important when used in conjunction with the -s (script)
option, described below.

The destination font path is constructed by concatenating directory and
filename components. The directory component is empty by default, but may be
specified with the -dd (destination directory) option. Note: tx will not create
directories so you must ensure that the destination directory exists before
running tx.

The -a (automatic) option takes one or more filename arguments. Each argument
is processed in turn and a source filename is constructed from the root,
directory, and filename components. The destination filename is constructed by
concatenating the destination directory component with the source filename less
its extension, if any, and a . (period) followed by the mode name. For example,
on Unix the command:

    tx -cff -dd /tmp/cff -a *.pfb

will convert all the .pfb files in the current directory into correspondingly
named .cff files in the directory /tmp/cff.

The -A option is similar to the -a option except that the destination filename
is assembled from the FontName of the source font and a . (period) followed by
the mode name.

Scripting
---------
The -s (script) option provides a way of specifying commonly used options and
filenames in a text file. The file is parsed into a sequence of whitespace-
delimited arguments which are then presented to tx as though they came from the
command line. Newlines are treated as whitespace and can be used to improve the
readability of the script file. If an argument must contain one or more spaces
it may be enclosed by a pair of " (double quote) characters. Comments, which
are ignored by the parser, may be introduced into the file by the # (hash)
character and extend to the end of the current line. Script files are not
recursive and therefore cannot include the -s option. The -s option must be the
last option given on the command line.

The following shows the beginning of a script file that specifies pfb versions
of the testset fonts on the the Unix server quad.

--- filename: disks-testset-pfb -----------
# PFB test fonts

-sr /disks/quad/u020/vol1/pc/shipping

# Serif Text Family
-sd 351-400/352
rdr_____.pfb    # BernhardModern-Roman
rdb_____.pfb    # BernhardModern-Bold
rdi_____.pfb    # BernhardModern-Italic
rdbi____.pfb    # BernhardModern-BoldItalic

# Sans Text Family
-sd 351-400/357
owbk____.pfb    # OfficinaSans-Book
owb_____.pfb    # OfficinaSans-Bold
owwi____.pfb    # OfficinaSans-BookItalic
owbi____.pfb    # OfficinaSans-BoldItalic
...
-------------------------------------------

Script files are a good way to specify a large number of source fonts, e.g. all
those on the Font Folio CD, using -sr, -sd, and filename arguments. These fonts
can then be processed according to the mode option specified on the command
line before the -s option. For example, the above script file can be used to
dump the testset fonts to a PostScript printer with the following command line:

    tx -ps -f -s disks-testset-pfb

Miscellaneous
-------------
The -v (version) option shows the versions of all the library components
linked into tx.

The -m (memory) option simulates a memory allocation failure. First, the -m
option with an argument of 0, should be added to the tx configuration under
examination. This will report the total number of memory allocations for that
configuration (call this M). tx should then be run again but this time using M
as the argument to the -m option rather than 0. This will cause a failure of
the memory allocator in one of the first M calls, selected randomly. The
failing call will be reported (call this N). If it is desired to repeat the
same failure, tx should be run again but this time with -N (a hyphen followed
by N) as the argument to the -m option.