/ 
Font-TTF-Scripts-0.16.1
River stage one • 2 direct dependents • 2 total dependents
/ scripts/ttfbuilder

TITLE

ttfbuilder - assemble a font from another font

SYNOPSIS

ttfbuilder [-a] [-h] -c config.xml [-x attach.xml] [-z out.xml] \\
    infile.ttf outfile.ttf

Builds outfile.ttf from infile.ttf according to config.xml. Also requires an attachment point database (attach.xml) and can generate out.xml.

OPTIONS

-a          initialise output font with all the glyphs of the input
            font and append new glyphs to that
-c file     Configuration file to use
-d bits     Flag bits
            0: Don't Set dates in the font to now
            1: Don't Auto-create postscript names for component glyphs
            2: Don't Hack the copyright message (if none set)
            3: Mark target font as symbol font
            4: Default to not allowing overstrikes (ensures guard
               space) on lhs
            5: Default to not allowing overstriking on rhs
            6: Disable some warnings
            7: Don't report missing glyphs
-f font     Extra font to reference [repeatable]
-h          Help
-x file     Attachment database to read [repeatable, follows correspond -f
              or occurs before -f to correspond to main font]
-z file     Attachment database to output

DESCRIPTION

ttfbuilder is a font subsetting program gone wild. Its aim is to allow a user to describe a new font in terms of the glyph pallette of a source font. Thus the new font may include ligatures of glyphs in the source font, or positional movements or whatever.

The main features of ttfbuilder are

  • Ability to create glyphs that are not in any cmap and to reference such glyphs via postscript name, glyph id or Unicode cmap entry.

  • Ability to work with an attachment points database. Thus ligatures are assembled by describing which attachment points should coincide, rather than having to give absolute locations in terms of shifting.

  • Ability to change the name of the font and change strings in the name table.

  • Ability to merge glyphs from other fonts.

ttfbuilder is controlled via a description file which describes the glyphs in the new font, in terms of glyphs in the source font. This description file is an XML file with the following key elements:

glyph

This describes a glyph and the attributes allow setting of the postscript name and Unicode id for the glyph. The glyph element has children which describe what goes into the glyph.

The overstrike attribute controls whether an attachment to a base glyph can extend beyond origin or the advance width of the base glyph. The default is to allow the diacritics to extend and even occur to the left of the origin or to the right of the advance. if overstrike is set to left for a glyph, then any diacritics may not extend to the left of the origin and the glyph will be shifted right to ensure this, if necessary. Likewise if overstrike is set to right then the advance will be increased to ensure that a diacritic does not extend beyond the advance width. values of true or 1 or both or all guard both sides of the glyph.

The default action for all glyphs is not to guard. This can be changed using the -d option with 16 setting the default left value and 32 setting the default right value.

base

A base character is a reference to a glyph in the source font (via Unicode id, postscript name, glyph id) which is used in building the parent glyph. If there is more than one base glyph in a glyph, then the base glyphs are concatenated in sequence according to their advance widths, creating a single glyph. If a glyph only contains a single base glyph with no attachments, and the base glyph has not been shifted in any way, then the resulting font will include the glyph directly rather than by reference.

The font attribute indicates that the glyph comes from another font. The attribute is a number (starting at 1) that refers to the nth font file in the list of -f command line options. Notice that any hinting associate with the glyph will be lost. The glyph will also be automatically scaled if the units per em of its source font are different from the main font.

attach

A base glyph may have attachments, which may have their own attachments in their turn. An attachment is a reference to a glyph in the source font and also the name of an attachment point on the attachment and one on its parent which are used to position the attachment so that the attachment points coincide.

The attach element takes two parameters describing the attachment point on the base (at) and the attachment point on the diacritic (with). If these are missing, then the glyphs are aligned centrally in the x direction and with no adjustment vertically.

The noaps attribute may be used to stop certain, or all, attachment points being propagated from a base or attach glyph to the glyph being defined. If noaps has the value 1, then no attachment points from this glyph will appear in the output glyph. If noaps contains a space separated listed of attachment point names, then none of those attachment points will propagate (whether or not they exist).

When referencing a <base> or <attach> glyph, in additio to being able to use glyph id, unicode id, or postscript name, it is possible to specify a font number which the glyph should be taken from. This corresponds to the -f command line option values. Thus a value of 0 is the required input font. A value of 1 is the first font referenced by a -f option and so on.

advance

It is possible to override the default value of the advance width for any glyph. Thus the advance element may occur is a child of either glyph, base or attach and it sets the value of the advance width for its parent to the value given in the width attribute. The default value of the advance width for a glyph is the widest advance width taken from each of the child glyphs (including attachments) in their position within the glyph. Thus if an attachment is positioned far enough to the right, it may well cause the advance width of the glyph to increase beyond that of the base glyph the attachment is on.

rsb

This allows the advance of a glyph to be specified in terms of the right side bearing rather than an absolute advance value.

lsb

In the case where overstrike is disallowed, sets the guard space to the left of the glyph.

shift

It is also possible to shift glyphs, at least base and attach glyphs. Shifting occurs after attachment (for obvious reasons).

string

In the names section of the description file it is possible to specify strings which cause changes to the name section of the font. The string element takes a num attribute which specifies which string to change. It is also possible to specify which platform, encoding and or language id the change should be made to.

Rather than using numbers to identify strings it is possible to use names. The following names correspond to strings 0 and following: copyright family subfamily fontid fullname version psname trademark vendor designer description vendor_url designer_url license license_url reserved preferred_family preferred_subfamily compat_full text CID_name

There is one special value for the num attribute, which is name. This causes the name of the font (string id 1) and also the full font name (string id 4) to be assembled from the font name and style (string id 2).

Within a string a name element may be used to lookup an existing value of a name string in the font for copying to the output font string being declared

font attributes

Various font attributes can be set from a TTFBuilder configuration file:

ascent      amount of space needed above the baseline for a glyph
descent     space below the baseline needed for a glyph
linegap     how much space to put between lines
cp          OS/2 codepages field (in binary)
coverage    OS/2 Unicode block coverage (in binary)

Binary values are written in hex (as in: 0003)

property

A property element is a simple name value pair that is added to the attachment point database for the glyph it is specified on

note

A note element contains text that is output to the attachment point database for the glyph it is specified on

The DTD for the configuration file is:

<!ELEMENT font (names?, glyphs)>
<!ATTLIST font
    ascent      CDATA #IMPLIED
    descent     CDATA #IMPLIED
    linegap     CDATA #IMPLIED
    cp          CDATA #IMPLIED
    coverage    CDATA #IMPLIED>

<!ELEMENT names (string)+>

<!ELEMENT string (#PCDATA|name)>
<!ATTLIST string
    num     CDATA #REQUIRED
    pid     CDATA #IMPLIED
    eid     CDATA #IMPLIED
    lid     CDATA #IMPLIED>

<!ELEMENT name EMPTY>
<!ATTLIST name
    num     CDATA #REQUIRED>

<!ELEMENT glyphs (glyph)+>

<!ELEMENT glyph (property* | note? | (advance | rsb | lsb)+ | base)+>
<!ATTLIST glyph
    PSNAme      CDATA #IMPLIED
    UID         CDATA #IMPLIED
    GID         CDATA #IMPLIED
    BID         CDATA #IMPLIED
    overstrike  (0 | false | none | 1 | true | all | both | left 
                   | right)  #IMPLIED>

<!ELEMENT base (advance | rsb | lsb | attach | shift)*>
<!ATTLIST base
    PSName  CDATA #IMPLIED
    UID     CDATA #IMPLIED
    GID     CDATA #IMPLIED
    font    CDATA #IMPLIED
    noaps   CDATA #IMPLIED>

<!ELEMENT attach (advance | rsb | lsb | shift)*>
<!ATTLIST attach
    PSName  CDATA #IMPLIED
    UID     CDATA #IMPLIED
    GID     CDATA #IMPLIED
    font    CDATA #IMPLIED
    with    CDATA #IMPLIED
    at      CDATA #IMPLIED
    noaps   CDATA #IMPLIED>

<!ELEMENT advance EMPTY>
<!ATTLIST advance
    width   CDATA #REQUIRED>

<!ELEMENT rsb EMPTY>
<!ATTLIST rsb
    width   CDATA #REQUIRED>

<!ELEMENT lsb EMPTY>
<!ATTLIST lsb
    width   CDATA #REQUIRED>

<!ELEMENT shift EMPTY>
<!ATTLIST shift
    x       CDATA #IMPLIED
    y       CDATA #IMPLIED>

<!ELEMENT property EMPTY>
<!ATTLIST property
    name    CDATA #REQUIRED
    value   CDATA #REQUIRED>

<!ELEMENT note (#PCDATA)>

From this small language, quite a lot can be done.

Attachment Points

One of the most powerful mechanisms for relating glyphs is that of attachment points. This concept is concerned with attaching diacritics to a base character and the attachment is achieved by specifying an attachment point on the base character and one on the diacritic. The attachment points are usually designed as single point paths in the glyph and their location or path number are held in a separate database. When the attaching of the diacritic to the base character occurs, then the diacritic is positioned so that the two attachment points coincide.

ttfbuilder works with attachment point databases represented in XML.

The DTD for an attachment point database is:

<!ELEMENT font (glyph)*>
<!ATTLIST font
    name    CDATA #IMPLIED
    upem    CDATA #IMPLIED

<!ELEMENT glyph (property* | (point | compound)* | note)>
<!ATTLIST glyph
    PSName  CDATA #IMPLIED
    UID     CDATA #IMPLIED
    GID     CDATA #IMPLIED>

<!ELEMENT point (location | contour)+>
<!ATTLIST point
    type    CDATA #REQUIRED>

<!ELEMENT location EMPTY>
<!ATTLIST location
    x       CDATA #REQUIRED
    y       CDATA #REQUIRED>

<!ELEMENT contour EMPTY>
<!ATTLIST contour
    num     CDATA #REQUIRED>

<!ELEMENT compound EMPTY>
<!ATTLIST compound
    bbox    CDATA #REQUIRED
    PSName  CDATA #IMPLIED
    UID     CDATA #IMPLIED
    GID     CDATA #IMPLIED>

<!ELEMENT property EMPTY>
<!ATTLIST property
    name    CDATA #REQUIRED
    value   CDATA #REQUIRED>

<!ELEMENT note (#PCDATA)>

A font contains glyphs which have attachment points. Each point has a name and either a contour (path number from 0) or a location of an attachment point (real or virtual) in terms of x and y co-ordinates in em units.

A glyph may also be a compound glyph in which case the boxes representing the location of the components of the compound are listed. Each component lists a bounding box describing the location of the component in relation to the main glyph. This is a 4 element string, separated by comma and optional whitespace. Each element is a co-ordinate in em units. The sequence of values is: xMin, yMin, xMax, yMax. The compound also indicates which glyph this component refers to.

Each glyph may also contain properties. A property is a name value pair. There may only be one property with any particular name attribute.

A glyph may have textual notes associated with it.