Frequently Asked Questions

This file provides some tips and troubleshooting advice for term-transcript in the FAQ format.

Which template to use?

The term-transcript library and the CLI app come with two main ways to render transcripts into SVG.

Text can be embedded into SVG as an HTML fragment (i.e., using a <foreignObject>). This is motivated by the fact that SVG isn’t good at text layout, particularly for multiline text and/or text with background coloring. HTML, on the other hand, can lay out such text effortlessly. Thus, term-transcript avoids the need of layout logic by embedding pieces of HTML (essentially, <pre>-formatted <span>s) into the generated SVGs.

HTML embedding is the default approach of the CLI app; it corresponds to the new() constructor in Template. It can lead to issues with viewing the rendered SVG as described below.

Pure SVG

As the second option, pure SVG can be generated with manual text layout logic. As a consequence, unless font embedding is used, the layout logic uses a hard-coded font advance width (aka char width), which may lead to various artifacts (e.g., interrupted underlines, stretched / compressed text etc.). This is required to align background color boxes with the text.

Pure SVG is generated by the CLI app if the --pure-svg flag is set. In the library, it corresponds to the pure_svg() constructor in Template.

HTML embedding not supported error

(Applies to the default template only; consider using the pure SVG template.)

If the generated SVG file contains a single red line of text “HTML embedding not supported…”, it means that you view it using a program that does not support HTML embedding for SVG. That is, the real transcript is still there, it is just not rendered properly by a particular viewer. All modern web browsers support HTML embedding (since they support HTML rendering anyway), but some other SVG viewers, such as Inkscape, don’t.

Transcripts & Content Security Policy

A potential reason for rendering errors when the transcript SVG is viewed from a browser is Content Security Policy (CSP) set by the HTTP server. If this is the case, the developer console will contain an error mentioning the policy, e.g. “Refused to apply inline style because it violates the following Content Security Policy…”. To properly render a transcript, the CSP should contain the style-src 'unsafe-inline' permission.

As an example, GitHub does not provide sufficient CSP permissions for the files attached to issues, comments, etc. On the other hand, committed files are served with adequate permissions; they can be linked to using a URL like https://github.com/$user/$repo/raw/HEAD/path/to/snapshot.svg?sanitize=true.

Customizing fonts

It is possible to customize the font used in the transcript using font_family and additional_styles fields in TemplateOptions (when using the Rust library), or --font / --styles arguments (when using the CLI app).

For example, the Fira Mono font family can be included by setting additional styles to the following value:

@import url('https://code.cdn.mozilla.net/fonts/fira.css');

It is possible to include @font-faces directly instead, which can theoretically be used to embed the font family via data URLs:

@font-face {
  font-family: 'Fira Mono';
  src: local('Fira Mono'), url('data:font/woff;base64,...') format('woff');
  /* base64-encoded WOFF font snipped above */
  font-weight: 400;
  font-style: normal;
}

Such embedding, however, typically leads to a huge file size overhead (hundreds of kilobytes) unless the fonts are subsetted beforehand (minimized to contain only glyphs necessary to render the transcript). Which is exactly the functionality provided by the FontEmbedder interface and its FontSubsetter implementation (the latter via the font-subset feature). If using CLI, you can embed fonts with the --embed-font flag.

Beware that if a font is included from an external source and the including SVG is hosted on a website, it may be subject to CSP restrictions as described above.

Keyboard shortcuts