From 954422e1cf75a820f409f491d24c441c62b78766 Mon Sep 17 00:00:00 2001 From: patrick96 Date: Tue, 24 Mar 2020 10:33:23 +0100 Subject: [PATCH] Update Font debugging guide --- Fonts.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/Fonts.md b/Fonts.md index c98dbfd..b25dd1b 100644 --- a/Fonts.md +++ b/Fonts.md @@ -33,19 +33,21 @@ When using icon fonts, you normally won't have to specify a font index because t ## Debugging Font Issues -If you have any issues with characters/icons not displaying correctly or **`Dropping unmatched character`** warnings, follow these steps before opening an issue: +If you have any issues with characters/icons not displaying correctly or **`Dropping unmatched character`** warnings, follow these steps before opening an issue, you will get referred back to them if you don't. + +Follow these steps very carefully and in the order they are given and do not skip any! + + 1. **Confirm all fonts are loaded properly:** -To do that, follow the instructions in the [Freetype Fonts](#freetype-fonts) section. +To do that, follow the instructions in the [Finding Font Names](#finding-font-names) section. 2. **Check that all the icons you use are available in the fonts used:** Use `gucharmap` to search (`Ctrl-F`) for the dropped characters (copy them from the terminal output), then switch to each font in your config, using the dropdown in the top left. For each font hold down right click on the highlighted character to show which font it's from. If that never shows any font from your config, you'll need to add the font for that character to your config. 3. **Check font order:** If you have no more **`Dropping unmatched character`** warnings but the wrong icons are displayed, you may have a font conflict where two fonts provide a font icon in the same position (codepoint). Make sure that none of the fonts in the font list, before the font that the icon is from, have a character at the same position. You can do that by changing the order in which you define the fonts, although this can lead to conflicts in the other direction. The safest way is to use the `-font` property or the `%{T}` tag to specify which font to use, as described at the beginning of this page. -4. **Try using `size` instead of `pixelsize`**: some fonts will **not** display if you try setting their size using the `pixelsize` property; try setting it with `size` instead, for example: `font-0: Inconsolata for Powerline:size=12;0` -5. **Try adding a property to the font name**. Some fonts may not properly respect a specified property (like Font Awesome 5 with `style`). Instead, you may have some luck appending the property to the name of the font to force a desired match (i.e. `FontAwesome5FreeSolid` instead of `FontAwesome5Free` will cause the font to match using the `solid` style). Also see [known issues](https://github.com/polybar/polybar/wiki/Known-Issues) for more help. -## Freetype Fonts +## Finding Font Names Polybar uses fontconfig to match font descriptions to a specific font. To get the name for a font, use `fc-list` to list all fonts and their names installed on your system. For example one line in the output could look like this: @@ -60,7 +62,17 @@ If we wanted to add that font to polybar we would need to set: font-0 = Noto Sans Mono:style=Regular ``` -You need to make sure that you copy the exact name (everything after the file path) otherwise polybar may not be able to match it. +You need to make sure that you copy the **exact** name (everything after the file path) otherwise polybar may not be able to match it. + +**Note:** For some fonts you may need to provide multiple font names, for example the output of `fc-list | grep -i awesome` gives three FontAwesome5 fonts: + +``` +/usr/share/fonts/TTF/fa-brands-400.ttf: Font Awesome 5 Brands,Font Awesome 5 Brands Regular:style=Regular +/usr/share/fonts/TTF/fa-solid-900.ttf: Font Awesome 5 Free,Font Awesome 5 Free Solid:style=Solid +/usr/share/fonts/TTF/fa-regular-400.ttf: Font Awesome 5 Free,Font Awesome 5 Free Regular:style=Regular +``` + +You will likely need all of them. To make sure that the correct font gets loaded, run polybar with the `-l info` argument (add `-l info` before that bar name when you run the `polybar` command): In the output on all the lines that start with `Loaded font` check that the font name in brackets matches the font name before the brackets, if they don't match you either don't have the given font installed or there is something wrong with the name you used. @@ -82,7 +94,6 @@ For debug purposes, you can make fontconfig output the font results when launchi $ FC_DEBUG=1 polybar mybar ... ~~~ - ### Anti-aliasing You might get better results for some fonts if you turn off antialiasing: @@ -97,7 +108,9 @@ Icons can be provided in the form of text characters. Popular icon fonts include - [IcoMoon](https://icomoon.io/app/#/select/library) - Custom/Mixed Licenses - [Nerd Patched Fonts](https://github.com/ryanoasis/nerd-fonts) - Mixed Licenses -Most icon fonts make use of the Private Use Area unicode block and can conflict. Setting system priority via FontConfig may be preferable. After defining a font as explained above, [formatting tags](https://github.com/polybar/polybar/wiki/Formatting#format-tags) can be used. Order of font definitions can also affect precedence. +Most icon fonts make use of the Private Use Area unicode block and can conflict. +After defining a font as explained above, [formatting tags](https://github.com/polybar/polybar/wiki/Formatting#format-tags) can be used. +Order of font definitions can also affect precedence. ### [GNOME Character Map](https://en.wikipedia.org/wiki/GNOME_Character_Map) `gucharmap` is a convenient utility for browsing selected fonts. Filter `View > By Unicode Block + Show only glyphs from this font` and navigate to Private Use Area. @@ -136,7 +149,7 @@ Usage: `perl test-fonts.pl "😀"` /usr/share/fonts/TTF/DejaVuSans.ttf: DejaVu Sans:style=Book /usr/share/fonts/TTF/DejaVuSans-Bold.ttf: DejaVu Sans:style=Bold ``` -Note: maybe you need to install "Font::FreeType" module for the Script +Note: maybe you need to install "Font::FreeType" module for the Script to work: ``` $ perl -MCPAN -e 'install Font::FreeType' ```