Asciidoctor-pdf: rendering callouts

[gliptak]

Trying to render callout like:

:doctype: book
:source-highlighter: pygments

[source,ruby]
----
print 'hello' # <1>
----
<1> first callout

Rendering with built-in fonts I see:

The following text could not be fully converted to the Windows-1252 character set:
| ①

and the PDF doesn't show the right symbol.

Overwrote theme (using http://font.ubuntu.com/) :

base:
  font_family: Ubuntu

font:
  catalog:
    Ubuntu:
      normal: Ubuntu-R.ttf
      bold: Ubuntu-B.ttf
      italic: Ubuntu-RI.ttf
      bold_italic: Ubuntu-BI.ttf
  fallbacks: [Ubuntu]

but still saw the same warning and PDF still incorrect.

Added the override for code section (why is this needed when base already set?):

code:
  font_family: $base_font_family

Now the warning is gone, but the PDF is still incorrect (shows empty rectangle for the callout).

Is there a way to force UTF-8 used? Am I to use different fonts to get this work?

Thanks

[mojavelinux]

If you ever get this message:

The following text could not be fully converted to the Windows-1252 character set:

It means for a certain chunk of text, Prawn is not using a TTF font. Prawn only supports UTF-8 when you are using a TTF font. The built-in fonts in PDF do not support UTF-8. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#fonts for details.

Overwrote theme using Ubuntu. Now the warning is gone, but the PDF is still incorrect (shows empty rectangle for the callout).

Callouts numbers are special because they require UTF-8 glyphs that most fonts do not have (including Ubuntu). In the default theme, we have included these glpyhs in the subsetted font file for M+ 1mn, as indicated by this line: https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml#L11.

You have three choices right now.

1) You can either use the M+ 1mn font that we made:

• https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/fonts/mplus1mn-regular-ascii-conums.ttf

2) You can use a tool like fontforge to add the conum glpyhs to the font file you want to use (copying them from some other font, such as M+ 1mn).

The Unicode range for the conums is U+2460 - U+2473.

3) You can define a fallback font that has the necessary glyphs (a good choice is VLGothic).

The reason this is complicated traces back to the fact that PDF has a "bring your own font" policy. If you don't provide the font that contains all the glyphs the content needs, you get a square box (or some other placeholder). PDF does not reach into the system fonts to resolve glyphs like a web browser. We take this for granted since most systems provide a fallback font that has every known glyph, which the browser makes use of.

One of the things we are planning to do is make the range of conums glyphs configurable. See #133.

[gliptak]

Based on your directions, I configured M+ 1mn for code and conum. Thanks

I still have my initial question, why did the out-of-configuration fail formatting the callouts?

[mojavelinux]

I still have my initial question, why did the out-of-configuration fail formatting the callouts?

Are you sure you were using the default theme at the time?

[gliptak]

I did have a custom theme configured with title and footer configurations, but without font, code or conum overrides.

[mojavelinux]

The problem is, if you have a custom theme, you have to specify everything. Otherwise, it defaults to using the PDF fonts (which are just useless). We're still sorting out how to make this easier (that's why we're still in alpha).

In short, the recommendation right now is to either use the built-in theme or develop a full theme with fonts included. It does take a bit of effort to setup, but once you create our own theme, then you really get a chance to fine tune a lot of things.

[mojavelinux]

The problem is, if you have a custom theme, you have to specify everything.

...well, mostly everything. We do have a very basic theme that provides some framing, but it does not provide fonts.

[mojavelinux]

For now, I think we could do a better job explaining this in the theming guide.

[gliptak]

Could fonts be defaulted to "standard theme" fonts when using a custom theme (instead of the PDF fonts)?

https://github.com/asciidoctor/asciidoctor-pdf/pull/410

[mojavelinux]

Unfortunately, not really. That's kind of what the default theme is for. The "bring your own font" requirement of PDF means we have to carry around a full set of fonts (or at least one for sans-serif and one for monospace).

I think the real solution here is theme inheritance. This lets you inherit from either the base theme or the default theme, then start building from there. See #367.

[mojavelinux]

Btw, it is possible to refer to the fonts provided by the default theme without having to copy them to your project. The tricky part is when you specify your own fonts because there can only be one font directory right now. As soon as you add a single font, you have to provide them all.

[mojavelinux]

We'll address how to use callouts with a custom monospaced font in #377 and #133.