ChordPro Implementation: Fonts

TL;DR? See the examples.

ChordPro uses fonts for PDF typesetting. In the config file fonts are specified for chords, lyrics, page titles and so on. For example, in the default config file in section pdf there is a section fonts that has a specification for the page titles:

title {
        name : serif
        size : 14
}

The name designates the built-in font serif. Alternatively you can use file to designate a font file on your system, or description to find a suitable font using font families. The order of precedence is file, description, and name.

Note The use of name is strongly discouraged.

Method 1: Using a font description

A font description is a flexible and system independent way to select a font. The description is a string containing up to four identifying items: the font family, the style, the weight and the size. A font family must be provided, the other parts are optional.

For example, to select the bold version of Arial at 14 point size for the titles:

title : "arial bold 14"

which is shorthand for

title {
        description : "arial bold 14"
}

The system will then try to find a font file for this font, e.g. Arial-Bold.ttf or a suitable replacement if this exact font could not be found.

Generic family names (aliases) can be used instead of existing family names. ChordPro predefines the following font families:

sans and sans-serif, a modern sans-serif font;
serif, a modern serif font;
mono and monospace, a monospace font.

Why is using font descriptions important?

Because ChordPro allows you to use markup in all your lyrics, titles and so on. For example:

[C]winkle, twinkle <bold>little</bold> [G]star

When you designate a font family to be used for your lyrics, ChordPro can find the bold and italic members of the same font. When specifying a built-in font or a font file like "myfont.ttf" it will generally not possible to find the other family members.

How does the system find the appropriate fonts?

Most modern systems are equipped with a facility called fontconfig or fc-conf or something similar. This facility can be used to fetch font information, e.g. the font file name, for fonts installed on the system.

ChordPro also provides its own font search facility. This can be used if your system does not have fontconfig, or when you want to override the system behaviour for precise control over the fonts being used.

In the config file in section pdf there is a section fontconfig that can be used to map family names to real font files. For example:

fontconfig {
    serif {
        ""          : dejavu/DejaVuSerif-Regular.ttf
        bold        : dejavu/DejaVuSerif-Bold.ttf
        italic      : dejavu/DejaVuSerif-Italic.ttf
        bolditalic  : dejavu/DejaVuSerif-BoldItalic.ttf
  }
}

For each family name you should specify four members: a regular font (with an empty key), a bold font (key bold), an italic font (key italic), and a bold-italic font (key bolditalic). Note that ChordPro uses italic, even if the font itself uses oblique.

This is the short story. The longer story is that instead of a file name you can specify another set of key/value pairs, for example:

fontconfig {
    devanagari {
        "" {
            file    : lohit-devanagari/Lohit-Devanagari.ttf
            shaping : 1
        }
        ...
}

The property "shaping" is mandatory for typesetting languages that need special glyph and ligature processing. Note that shaping requires the perl module HarfBuzz::Shaper to be installed on the system.

Exact semantics of font properties are still under development.

Method 2: Using a font filename

A font filename can be specified with filed" and must be either an absolute filename, or a relative filename which is interpreted relative to the font path, which consists of configuration setting fontdir, the fonts resource dir, and the contents of environment variable FONTDIR. In any case, the filename should point to a valid TrueType (.ttf) or OpenType (.otf) font.

If the font file cannot be found, ChordPro will abort with an appropriate error message.

If you have quality PostScript Type1 fonts (a collection of .pfa or .pfb, with .afm and/or .pfm files) they can easily be converted to TrueType or OpenType using a tool like FontForge.

Method 3: Using a built-in font

Built-in fonts are specified with "name". For legacy reasons the following names are understood:

Courier, Courier-Bold, Courier-BoldOblique, Courier-Oblique
Same as mono.
Helvetica, Helvetica-Bold, Helvetica-BoldOblique, Helvetica-Oblique
Same as sans.
Times-Roman, Times-Bold, Times-BoldItalic, Times-Italic
Same as serif.

Examples

Note that the examples only show the fontconfig and fonts parts. These should be part of the pdf config as explained in Configuration for PDF output.

Each example consists of two parts: the mapping of font families, and associating output elements to font families. The latter part is identical in all examples but included for convenience.

Example setup using TrueType fonts (Linux)

This example is for educational purposes. ChordPro uses the GNU Free fonts by default.

  // Relative filenames are looked up in the fontdirs.
  // Note that font locations may be different on your system.

  fontdir : [
    /usr/share/fonts/gnu-free
  ]

  // "fontconfig" maps members of font families to font files.

  fontconfig {
    serif {
      ""         : FreeSerif.ttf
      bold       : FreeSerifBold.ttf
      italic     : FreeSerifItalic.ttf
      bolditalic : FreeSerifBoldItalic.ttf
    }
    "sans, sans-serif" {
      ""         : FreeSans.ttf
      bold       : FreeSansBold.ttf
      italic     : FreeSansOblique.ttf
      bolditalic : FreeSansBoldOblique.ttf
    }
    "mono, monospace" {
      ""         : FreeMono.ttf
      bold       : FreeMonoBold.ttf
      italic     : FreeMonoOblique.ttf
      bolditalic : FreeMonoBoldOblique.ttf
    }
    dingbats.    : ChordProSymbols.ttf
  }

  // "fonts" associates output elements to font families as defined in
  // "fontconfig" above.

  fonts {
	title          : "serif bold 14"
	subtitle       : "serif 11"
	text           : "serif 12"
	chord          : "sans italic 10"
	comment_italic : "sans italic 12"
	tab            : "monospace 10"
	toc            : "serif 11"
	grid           : "sans 10"
	chordfingers   : "dingbats 10"
	comment {
	  description  : "sans 12"
	  background   : #E5E5E5
	}
	comment_box {
	  description  : "sans 12"
	  frame        : 1
	}
  }

Example setup using TrueType fonts (Microsoft Windows)

  fontdir    : [ "~\\AppData\\Local\\Microsoft\\Windows\\Fonts"
                 "C:\\Windows\\Fonts" ]
  // "fontconfig" maps members of font families to font files.

  fontconfig {
	serif {
	  ""         : georgia.ttf
	  bold       : georgiab.ttf
	  italic     : georgiai.ttf
	  bolditalic : georgiaz.ttf
	}
	"sans, sans-serif" {
	  ""         : arial.ttf
	  bold       : arialbd.ttf
	  italic     : ariali.ttf
	  bolditalic : arialbi.ttf
	}
	"mono, monospace" {
	  ""         : cour.ttf
	  bold       : courbd.ttf
	  italic     : couri.ttf
	  bolditalic : courbi.ttf
	}
	dingbats.        : ZapfDingbats
  }

  // "fonts" associates output elements to font families as defined in
  // "fontconfig" above.

  fonts {
	title          : "serif bold 14"
	subtitle       : "serif 11"
	text           : "serif 12"
	chord          : "sans italic 10"
	comment_italic : "sans italic 12"
	tab            : "monospace 10"
	toc            : "serif 11"
	grid           : "sans 10"
	chordfingers   : "dingbats 10"
	comment {
	  description  : "sans 12"
	  background   : #E5E5E5
	}
	comment_box {
	  description  : "sans 12"
	  frame        : 1
	}
  }

Example setup using DejaVu fonts (Mac OS X)

Instructions to install the DejaVu fonts can be found here.

  // We assume the DejaVu fonts to be installed in the ~/Library/Fonts
  // directory. See https://dejavu-fonts.github.io/ for downloading
  // the fonts. To install, unzip the fonts bundle and double-click on
  // each of the .ttf files.

  fontdir : [ "~/Library/Fonts" ]

  // "fontconfig" maps members of font families to font files.
  fontconfig {
	serif {
	  ""         : DejaVuSerif.ttf
	  bold       : DejaVuSerif-Bold.ttf
	  bolditalic : DejaVuSerif-BoldItalic.ttf
	  italic     : DejaVuSerif-Italic.ttf
	}
	"sans, sans-serif" {
	  ""         : DejaVuSans.ttf
	  bold       : DejaVuSans-Bold.ttf
	  bolditalic : DejaVuSans-BoldOblique.ttf
	  italic     : DejaVuSans-Oblique.ttf
	}
	"mono, monospace" {
	  ""         : DejaVuSansMono.ttf
	  bold       : DejaVuSansMono-Bold.ttf
	  bolditalic : DejaVuSansMono-BoldOblique.ttf
	  italic     : DejaVuSansMono-Oblique.ttf
	}
  }

  // "fonts" associates output elements to font families as defined in
  // "fontconfig" above.

  fonts {
	title          : "serif bold 14"
	subtitle       : "serif 11"
	text           : "serif 12"
	chord          : "sans italic 10"
	comment_italic : "sans italic 12"
	tab            : "monospace 10"
	toc            : "serif 11"
	grid           : "sans 10"
	chordfingers   : "dingbats 10"
	comment {
	  description  : "sans 12"
	  background   : #E5E5E5
	}
	comment_box {
	  description  : "sans 12"
	  frame        : 1
	}
  }

Example font config using system fonts

While this will always generate good results, the results may, and will, be different when run on another system. Of after a system update.

// Explicitly disable our fontconfig, so fonts will be looked up
// by the system.
"fontconfig" : [],

// "fonts" associates output elements to font families as defined in
// "fontconfig" above.
  // "fonts" associates output elements to font families as defined in
  // "fontconfig" above.

  fonts {
	title          : "serif bold 14"
	subtitle       : "serif 11"
	text           : "serif 12"
	chord          : "sans italic 10"
	comment_italic : "sans italic 12"
	tab            : "monospace 10"
	toc            : "serif 11"
	grid           : "sans 10"
	chordfingers   : "dingbats 10"
	comment {
	  description  : "sans 12"
	  background   : #E5E5E5
	}
	comment_box {
	  description  : "sans 12"
	  frame        : 1
	}
  }

// On my system, this yields:
// dingbats      --  /usr/share/fonts/urw-base35/D050000L.otf
// monospace     --  /usr/share/fonts/dejavu/DejaVuSansMono.ttf
// sans          --  /usr/share/fonts/dejavu/DejaVuSans.ttf
// sans italic   --  /usr/share/fonts/dejavu/DejaVuSans-Oblique.ttf
// serif         --  /usr/share/fonts/dejavu/DejaVuSerif.ttf
// serif bold    --  /usr/share/fonts/dejavu/DejaVuSerif-Bold.ttf

Example setup using built-in fonts

Note This is strongly discouraged.

  // "fontconfig" maps members of font families to built-in fonts.

  fontconfig {
	serif {
	  ""         : Times-Roman
	  bold       : Times-Bold
	  italic     : Times-Italic
	  bolditalic : Times-BoldItalic
	}
	"sans, sans-serif" {
	  ""         : Helvetica
	  bold       : Helvetica-Bold
	  italic     : Helvetica-Oblique
	  bolditalic : Helvetica-BoldOblique
	}
	"mono, monospace" {
	  ""         : Courier
	  bold       : Courier-Bold
	  italic     : Courier-Italic
	  bolditalic : Courier-BoldItalic
	}
	dingbats.        : ZapfDingbats
  }

  // "fonts" associates output elements to font families as defined in
  // "fontconfig" above.
  // Not all elements need to be associated since they default to other
  // settings.

  fonts {
	title          : "serif bold 14"
	subtitle       : "serif 11"
	text           : "serif 12"
	chord          : "sans italic 10"
	comment_italic : "sans italic 12"
	tab            : "monospace 10"
	toc            : "serif 11"
	grid           : "sans 10"
	chordfingers   : "dingbats 10"
	comment {
	  description  : "sans 12"
	  background   : #E5E5E5
	}
	comment_box {
	  description  : "sans 12"
	  frame        : 1
	}
  }