Skip to content

Latest commit

 

History

History
96 lines (72 loc) · 4.5 KB

FAQ.md

File metadata and controls

96 lines (72 loc) · 4.5 KB

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.

HTML embedding

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 and a hack to deal with background coloring (lines of text with appropriately colored █ chars placed behind the content lines). The resulting SVG is supported by more viewers than HTML embedding, but it may look incorrectly in certain corner cases. For example, if the font family used in the template does not contain █ or some chars used in the transcript, the background coloring boxes for text may be mispositioned.

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 an 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).

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.