/usr/bin/ttfbuilder

NAME
    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 palette 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).

    scale
        Scaling a glyph allows for stretching given the x & y values may be
        different. The x position is multiplied by the x scale and the y
        position is multiplied by the y scale. There is no cross
        multiplication allowing for rotation.

    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 | scale)*>
        <!ATTLIST base
            PSName  CDATA #IMPLIED
            UID     CDATA #IMPLIED
            GID     CDATA #IMPLIED
            font    CDATA #IMPLIED
            noaps   CDATA #IMPLIED>

        <!ELEMENT attach (advance | rsb | lsb | shift | scale)*>
        <!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 scale EMPTY>
        <!ATTLIST scale
            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
            producer    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.

AUTHOR
    Martin Hosken <http://scripts.sil.org/FontUtils>. (see CONTRIBUTORS for
    other authors).

LICENSING
    Copyright (c) 1998-2016, SIL International (http://www.sil.org)

    This script is released under the terms of the Artistic License 2.0. For
    details, see the full text of the license in the file LICENSE.