Powerlevel9k: Misleading Font Installation Documentation

[varunagrawal]

When following the documentation for installing the fonts needed for powerlevel9k it seems that the 4 different options are not independent.
To be precise, I need to install the powerline font irrespective of the other options as a base before I can go ahead and install the other fonts such as the FontAwesome icons.

This can be misleading and a clean up of the documentation would be nice especially for newbies to ZSH.

[dritter]

Hi @varunagrawal ! Thanks for the report.

Actually these methods are independent, but which one you have to choose depends on your configuration and personal preference ;)
This is a pretty confusing topic. I'll try to elaborate more (in a general way, so that we can copy & paste it to the wiki; so you might already know a lot of things I describe here).

------------8<-------------------

General informations about fonts

First off:
This theme uses special characters that require to use special fonts. To use these fonts properly, you have to install them (see below) and to set it in your terminal emulator.

So, basically there are two* different methods how to use fonts:

1. Use a font that already contains all necessary characters. That is called using a "patched" font. The advantage is, you just need to install one font. Disadvantage is that you are limited to the icons of that font.
2. Use a method of falling back from one font to another, if the character you want to display is not contained. This requires the use of an additional program ( e.g. "fontcache"). The advantage is flexibility. You can basically configure every font you want. Disadvantage is that the setup is more complicated.

Some terminal emulators (like iTerm2) allow it to configure *text and non-ASCII fonts separately. If you want this is a third way.

Examples of icons in P9K

The most basic form of a powerline optic looks like this:

So, you can see there are only the segment separators (the triangles) and a git-branch icon present.

But there are fonts out there that contain a lot of icons, like Nerd-Fonts or Awesome-Terminal-Fonts. Here is a demonstration of Awesome-Terminal-Fonts in a prompt:

Choosing a default icon set in P9K

If you prefer such a look for your prompt, you need to install such a font and set the appropriate POWERLEVEL9K_MODE, which pre configures a set of default icons for the according font. Remember to set the POWERLEVEL9K_MODE before you apply/specify the theme in your ~/.zshrc.

The different POWERLEVEL9K_MODEs are for:

default | awesome-fontconfig | awesome-patched | nerdfont-fontconfig
------- | ---------------------- | ----------------- | ----------------------
regular powerline optic | Awesome Terminal Fonts (fontconfig variant) | Awesome Terminal Fonts (pre patched) | Nerd-Font (fontconfig)

Actual installation of font

Pre patched font

Installing a pre patched font is fairly easy. Just download the desired font and double click it. A dialog should pop up, guiding you through the installation process.
After you installed the font, you have to configure your terminal emulator to use that font.

Setup fontconfig

A good installation instruction that topic can be found in the Awesome-Terminal-Fonts README for Linux and in the wiki for OSX.
There is a speciality with Awesome-Terminal-Fonts: They do not come with Powerline icons included. If you do not use a base font that has them already included, you have to include them by yourself. One possibility is to copy the original powerline font into ~/.fonts (and to configure it in your fontconfig-configuration, of course).

------------8<-------------------

I did not go into detail into why there are different variant of the fonts (even within one font), and did not explain what code points, glyphs and double-width glyphs are. I am planning to write a separate wiki page for that.

What do you think? Is that explanation clearer than the original wiki page? It is a quite complicated and confusing topic..

[varunagrawal]

Hi @dritter. Thanks for the awesome response!

However my problem is that in order to get Option 3: FontAwesome to work, I had to also install Option 1: Powerline fonts as well. Thus saying that I can pick and choose which option I wanted based on my preferences didn't seem to sit well with me. If I only install FontAwesome font then I don't get the powerline triangles in my shell and it looks terrible. Installing the powerline font fixes that immediately.

I am on Ubuntu Linux 16.04.

I assumed it was an issue with patching that @V1rgul had worked on and fixed and which was going to be released in the next version. Hence I thought if the documentation needed to be updated, I'd be more than glad to submit a PR for it.

[varunagrawal]

So this should help explain my issue.

If I don't install the PowerlineSymbols.otf font as detailed here, then I get the below terminal prompt:

If I download and move the PowerlineSymbols.otf file to the ~/.fonts directory, the terminal prompt automatically fixes to this:

Nowhere in the Awesome-Terminal font installation README does it mention to install the Powerline Symbols font. Maybe I am missing something here, but the Awesome-Terminal font is option 3 and the Powerline Symbols font is option 2 and hence my confusion.

[dritter]

Yes, that is because you need one text font and add the special icon fonts to it. Some of the text fonts (especially the terminal/developer facing fonts like PragmataPro and SourceCodePro) already include powerline icons (they are pretty popular among the users of that fonts). There a few traces that @gabrielelana used PragmataPro as base font. That is IMHO the reason why he did it that way.
He could have included a font that only has the powerline icons in it (like the one included in powerline itself). Btw. even the official powerline/font repo offers just pre patched fonts..

[dritter]

Btw. Just a wording thing: FontAwesome is a special icon font that is included in Awesome-Terminal-Fonts.

[dritter]

Btw. I just updated the description in my comment to clarify that a user has to download the powerline icons if Awesome-Terminal-Font was used, but no powerline-enabled base font.

[gabrielelana]

@dritter you are right, I use PragmataPro, I strongly suggest to everyone to use a font that already has the powerline glyphs as a base font because it's really hard to patch a pre existing font with those glyphs in a way that looks right, I'm pretty obsessive for this kind of thing, a shift of few pixels for me is unacceptable 😅

@varunagrawal I should also clarify things better on my side

[varunagrawal]

@dritter and @gabrielelana thank you for the clarification. I'll close this issue.

[bhilburn]

Just used @dritter's awesome response in this thread to create a new wiki page!

https://github.com/bhilburn/powerlevel9k/wiki/About-Fonts