Font support and handling fonts in hexapdf, as well as improved documentation and "feedback" method

[rubyFeedback]

This is a bit of a "meta"-issue request.

I am using the "Hack" font a lot; I like it. Monospaced fonts are nifty for code layout and stuff but I guess Thomas knows that anyway. :)

I found this snippet from ~8 months ago:

https://gist.github.com/gettalong/5f13d27a2170e507cd890aa3a4273a43

Unfortunately this here:

require 'hexapdf/font/ttf_wrapper'

does not work. But more generally, I am wondering how to make use of other fonts, such as Hack in my case.

In my case the Hack .ttf files are under:

/usr/share/fonts/truetype/hack/

Such as: Hack-BoldItalic.ttf, Hack-Regular.ttf and so forth. But how to get to use these fonts?

I would also like to suggest to add some toplevel method to show which fonts are available; something like "Hexapdf.available_fonts?" or some other fitting method name (choose whatever name you may find appropriate here, IF you consider the use case and rationale useful; the use case is to quickly find out which fonts are available by default, so that users can use it for their pdf-creation, e. g. Times, Helvetica, Courier, ZapfDingbats. Not sure if such a method already exists. If so then perhaps the documentation could mention this more clearly. I am reading different docs, such as https://hexapdf.gettalong.org/documentation/tutorials/modifying-a-pdf-document.html and others right now. Finally updating my knowledge in how to work with hexapdf, it's a bit different to prawn. Perhaps a compatibility layer for hexapdf for ex-prawn users may be useful too, but I digress - the issue here is really about font-support in hexapdf).

By the way, you also provide 007-truetype.rb so perhaps the example gist at github should be removed or point people to 007 instead?

I got 007-truetype.rb to work by providing the full path to the Hack font.

So getting new fonts supported is actually trivial - I did not know that.

Is there perhaps also a way to make all these .ttf fonts available on startup? Or perhaps configure hexapdf permanently? Then we could load these all up once; and could use a toplevel method to feedback which fonts are supported.

Anyway.I think now knowing that I can load up any font via

font_file = '/usr/share/fonts/truetype/hack/Hack-Regular.ttf'
wrapper = doc.fonts.add(font_file)

Kind of solved most of my issues here, but perhaps some simpler API could still be added. Right now it seems as if we have to provide such a path manually, and perhaps we can eliminate this manual step somehow. I cheat in my own projects so perhaps: require 'hexapdf/extensive_font_support' or anything like that (again these are just examples for names, please adjust to whatever names or API/method calls you think fits the most, IF decided that this may be a good issue request. The idea here is to make working with fonts easier, the API names and such are just suggestions towards facilitating that goal, e. g. replacing prawn with hexapdf. Thanks for reading!)

[rubyFeedback]

Just found:

HexaPDF::FontLoader::Standard14::MAPPING

So I think that may also solve the other issue. But perhaps a toplevel method may still be nicer to read rather than having to use the hash there.

For instance:

HexaPDF::FontLoader::Standard14::MAPPING.keys # => ["Times", "Helvetica", "Courier", "Symbol", "ZapfDingbats"]

(Although the documentation may explain why these fonts are the ones shown. Is there perhaps a reason for this? E. g. why Helvetica is known? Are these non-patented fonts or something?).

[rubyFeedback]

Hmm not quite though ...

Adding the font from: /usr/share/fonts/truetype/hack/Hack-Regular.ttf

hexapdf-0.20.4/lib/hexapdf/document/fonts.rb:76:in `add': The requested font 'Hack-Regular' in variant 'none' couldn't be found. Configured fonts: Courier (none, bold, italic, bold_italic), Helvetica (none, bold, italic, bold_italic), Symbol (none), Times (none, bold, italic, bold_italic), ZapfDingbats (none) (HexaPDF::Error)

I am failing too much right now. Perhaps the API could be more convenient so we can:

a) more easily add fonts in general, including giving the path

AND

b) also then using something like 'Hack-Regular' as the name (which is as the path specified at /usr/share/fonts/truetype/hack/Hack-Regular.ttf)

The error message does not tell me that much. I don't even know how the part "variant 'none'" comes into play. From what I can see the code I am using does not specify any 'none' variant, so it seems hexapdf makes an assumption. It's ok to make assumptions, but to then show error messages based on that assumption, such as "variant 'none'" is a bit confusing to the end user.

I'll give it a try again at some later time. I guess I can use Helvetica for the time being just fine, so it's not a real showstopper, but I often have more luck trying again at some later point in time rather than incur too much frustration in one day. :)

[gettalong]

Registering Fonts

Have a look at https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/index.html and look for the option font.map. This allows you to register any TrueType font to be used with HexaPDF.

If you modify the global HexaPDF::DefaultDocumentConfiguration object, you only need to do this once in the process. Otherwise pass the font.map option as configuration option when creating a new [HexaPDF::Document](https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/index.html#method-c-new for per document settings.

I'm still in the process to adding examples to the API documentation. The drawing API (see e.g. https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Content/Canvas.html#method-i-circle) is already done but most other parts are still missing examples where useful (like for the configuration options or the whole stuff in HexaPDF::Layout).

Don't mess with the standard 14 fonts ;-) These are hard-coded by design and can't be changed without a respective change in the PDF specification (unlikely to happen).

Font Usage

You can either use a registered font, ie. one in the font.map configuration option or one of the standard 14 PDF fonts. Or pass a TrueType font file directly to e.g. HexaPDF::Content::Canvas#font. The latter uses the font loader to retrieve the actual font.

List of Fonts

See https://hexapdf.gettalong.org/documentation/reference/api/HexaPDF/Document/Fonts.html#method-i-configured_fonts