Text::...Config(3pm)

💖 NAME 💖

Text::Layout::FontConfig — the Pango style font description for Text::Layout. And yes bestie, you've landed on the Text::...Config(3pm) manual page, so let's get into it 🎀

🌸 SYNOPSIS 🌸

Font descriptors are just strings, and they describe the characteristics of the font you want. Like, for example, "Sans Italic 20" — that's a whole font descriptor right there, no cap.

The PDF context is out here dealing with physical fonts instead, okurrr? That means built-in fonts like "Times-Bold", and also fonts loaded straight from font files like /usr/share/fonts/dejavu/DejaVuSans.ttf.

---

So to map font descriptions onto physical fonts, those fonts have to be registered. Registering is what gives a font its family, its style, and its weight. The way that works is the entire plot of this page. 💅

⚠️ Real talk: Text::Layout::FontConfig is a singleton. Creating objects with new() will always return the same object. Always. Every time. It's giving only child energy and we're obsessed.

✨ METHODS ✨

new( [ atts... ] )

For convenience only, bestie. Because Text::Layout::FontConfig is a singleton, creating objects with new() will always return the same object. That's just the deal.

Attributes:

• corefonts — if this is true, a predefined set of font names (the PDF corefonts) gets registered. Iconic.

register_fonts( $font, $family, $style [ , $weight ] [ , $props ] )

Registers a font family, style and weight for the font you give it.

• $font — can be the name of a built-in font, or the name of a TrueType or OpenType font file.
• $family — a font family name such as "normal", "sans", "serif", or "monospace". And plot twist: you can specify multiple family names, e.g. "times, serif".
• $style — the slant style, one of "normal", "oblique", or "italic".
• $weight — the font weight, like "normal", or "bold".
• For convenience, style combinations like "bolditalic" are allowed. We love a flexible queen.

---

A final hash reference can be passed to specify additional properties for this font. The recognized properties are:

• "shaping" — if it's set to a true value, this font will require text shaping. You need this for fonts that deal with complex glyph rendering and ligature handling, like Devanagari. Text shaping requires the module HarfBuzz::Shaper.
• "ascender" — if set, overrides the font ascender. This may be necessary to improve results for some fonts. The value is expressed in 1/1000th of an em.
  • "descender" — if set, overrides the font descender. This may be necessary to improve results for some fonts. The value is expressed in 1/1000th of an em.
• "underline_thickness", "underline_position" — overrides the font specified or calculated values for underline thickness and/or position. This may improve results for some fonts.
• "strikeline_thickness", "strikeline_position" — overrides the font specified or calculated values for strikeline thickness and/or position. This may improve results for some fonts.
  • Note that strikeline thickness will default to underline thickness, if set.
• "overline_thickness", "overline_position" — overrides the font specified or calculated values for overline thickness and/or position. This may improve results for some fonts.
  • Note that overline thickness will default to underline thickness, if set.

add_fontdirs( @dirs )

Adds one or more file paths to be searched for font files. Go find those fonts, girl 🔍🦋

register_aliases( $family, $aliases, ... )

Adds aliases for existing font families.

Multiple aliases can be specified, e.g.

$layout->register_aliases( "times", "serif, default" );

or

$layout->register_aliases( "times", "serif", "default" );

register_corefonts( %options )

This is a convenience method that registers all built-in corefonts. It literally does the whole job for you, periodt.

Aliases for families "serif", "sans", and "monospace" are added unless $noaliases is specified.

You do not need to call this method if you provide your own font registrations. Your fonts, your rules.

Options:

• aliases — if true, register Serif, Sans and Mono as aliases for Times, Helvetica and Courier. This is enabled by default and can be cancelled with "noaliases".
• noaliases — if true, do not register Serif, Sans and Mono as aliases for Times, Helvetica and Courier.
• remap — remap the core fonts to real TrueType or OpenType font files. The supported values are "GNU_Free_Fonts" or "free" to use the GNU Free Fonts (http://ftp.gnu.org/gnu/freefont/) and "tex" or "tex-gyre" for the TeX Gyre fonts (https://www.gust.org.pl/projects/e-foundry/tex-gyre/).

remap($font)

remap( $src => $dst, ... )

Handles font remapping. The main purpose here is to remap corefonts to real fonts. That's the mission.

With a single argument, it returns the remapped value, or undef if there is none. Sad but honest.

With a hash argument, it maps each of the targets (the keys) to a font file (the value). This file must be present in one of the font directories — non-negotiable.

Alternatively, the key may be one of "Times", "Helvetica" and "Courier", and the value an already registered family.

find_font( $family, $style, $weight )

Returns a font descriptor based on the given family, style and weight.

On Linux, fallback using fontconfig.

from_string( $description )

Returns a font descriptor using a Pango-style font description, e.g. "Sans Italic 14".

On Linux, fallback using fontconfig.

parse( $description )

Parses a Pango-style font description and returns a hash ref with the keys "family", "style", "weight", and "size".

Unspecified items are returned as empty strings or, in the case of "size", zero. Empty is empty bestie don't come for me.

from_filename( $filename )

Returns a font descriptor from a filename. It tries to infer the Pango data from the name. Detective era fr 🔍💖

🌈 SEE ALSO

Text::Layout, Text::Layout::FontDescriptor.

👑 AUTHOR

Johan Vromans, "<JV at CPAN dot org>"

🫶 SUPPORT

This module is part of <Text::Layout>.

Development takes place on GitHub: <https://github.com/sciurius/perl-Text-Layout>.

You can find documentation for this module with the perldoc command.

perldoc Text::Layout::FontConfig

Please report any bugs or feature requests using the issue tracker for Text::Layout on GitHub.

📜 LICENSE

See Text::Layout, Text::Layout::FontDescriptor, HarfBuzz::Shaper.

---

Okay that's the whole page bestie, you ate this one 💅✨ and fyi this manual page shipped as perl v5.40.1, dated 2025-08-15 — go forth and register those fonts mwah 🎀