.\" Automatically generated by Pandoc 2.4
.\"
.TH "TERMTOSVG\-TEMPLATES" "5" "November 2018" "" ""
.hy
.SS DESCRIPTION
.PP
templates are SVG files in which termtosvg embeds animations.
Using templates makes it possible to:
.IP \[bu] 2
Have user defined terminal color themes and fonts
.IP \[bu] 2
Add a terminal UI or window frame to the animation
.IP \[bu] 2
Have interactive animations (for example play/pause buttons)
.PP
See here (https://nbedos.github.io/termtosvg/pages/templates.html) for a
gallery of the templates included with termtosvg
.SS TEMPLATE STRUCTURE
.PP
Here is the basic structure of a template:
.IP
.nf
\f[C]
<?xml version=\[dq]1.0\[dq] encoding=\[dq]utf\-8\[dq]?>
<svg id=\[dq]terminal\[dq] baseProfile=\[dq]full\[dq] viewBox=\[dq]0 0 656 325\[dq] width=\[dq]656\[dq] version=\[dq]1.1\[dq]
     xmlns=\[dq]http://www.w3.org/2000/svg\[dq] xmlns:xlink=\[dq]http://www.w3.org/1999/xlink\[dq]>
    <defs>
        <termtosvg:template_settings xmlns:termtosvg=\[dq]https://github.com/nbedos/termtosvg\[dq]>
            <termtosvg:screen_geometry columns=\[dq]82\[dq] rows=\[dq]19\[dq]/>
        </termtosvg:template_settings>
        <style type=\[dq]text/css\[dq] id=\[dq]generated\-style\[dq]>
            <!\-\- [snip!] \-\->
        </style>
        <style type=\[dq]text/css\[dq] id=\[dq]user\-style\[dq]>
            <!\-\- [snip!] \-\->
        </style>
    </defs>
    <svg id=\[dq]screen\[dq] width=\[dq]656\[dq] viewBox=\[dq]0 0 656 323\[dq] preserveAspectRatio=\[dq]xMidYMin meet\[dq]>
        <!\-\- [snip!] \-\->
    </svg>
</svg>
\f[R]
.fi
.PP
Overall, one can identify:
.IP \[bu] 2
An \f[C]svg\f[R] element with id \[lq]terminal\[rq]
.IP \[bu] 2
A \f[C]defs\f[R] element which includes:
.RS 2
.IP \[bu] 2
A termtosvg specific \f[C]template_settings\f[R] element used to specify
the terminal size (number of columns and rows) for which the template is
made
.IP \[bu] 2
A \f[C]style\f[R] element with id \[lq]generated\-style\[rq] that will
be overwritten by termtosvg
.IP \[bu] 2
Another \f[C]style\f[R] element with id \[lq]user\-style\[rq] that
should contain at least the terminal color theme.
This element is defined by the template creator and won\[cq]t be
overwritten by termtosvg
.RE
.IP \[bu] 2
An inner \f[C]svg\f[R] element with id \[lq]screen\[rq] which will
contain the animation produced by termtosvg
.SS TEMPLATE CUSTOMIZATION
.PP
The basic idea behind template customization is that termtosvg will
preserve elements of the template that it does not modify.
Hence it is possible to
.IP \[bu] 2
Customize the style of the animation by modifying the content of the
\f[C]style\f[R] element with id \[lq]user\-style\[rq]
.IP \[bu] 2
Add a new \f[C]script\f[R] element to embed JavaScript code in the
animation
.IP \[bu] 2
Add other SVG elements, as long as they are not children of the
\f[C]svg\f[R] element with id \[lq]screen\[rq]
.PP
I hope that the information provided here together with the code for the
default templates (../termtosvg/data/templates) is enough to get started
with template customization, but feel free to open an
issue (https://github.com/nbedos/termtosvg/issues/new) if you need some
help.
.SS Custom color theme or font
.PP
Terminal color themes must be specified in the \f[C]style\f[R] element
with id \[lq]user\-style\[rq] and must define all the following classes:
\f[C]foreground\f[R], \f[C]background\f[R], \f[C]color0\f[R],
\f[C]color1\f[R], \&..., \f[C]color15\f[R].
Font related attributes can also be specified together with the color
theme.
See below for an example.
.IP
.nf
\f[C]
<svg xmlns=\[dq]http://www.w3.org/2000/svg\[dq] xmlns:xlink=\[dq]http://www.w3.org/1999/xlink\[dq] id=\[dq]terminal\[dq] baseProfile=\[dq]full\[dq] viewBox=\[dq]0 0 656 325\[dq] width=\[dq]656\[dq] version=\[dq]1.1\[dq]>
    <defs>
        <termtosvg:template_settings xmlns:termtosvg=\[dq]https://github.com/nbedos/termtosvg\[dq]>
            <termtosvg:screen_geometry columns=\[dq]82\[dq] rows=\[dq]19\[dq]/>
        </termtosvg:template_settings>
        <style type=\[dq]text/css\[dq] id=\[dq]generated\-style\[dq]>
            /* ... Snip! ... */
        </style>
        <style type=\[dq]text/css\[dq] id=\[dq]user\-style\[dq]>
            .foreground {fill: #c5c5c5;}
            .background {fill: #1c1c1c;}
            .color0 {fill: #1c1c1c;}
            .color1 {fill: #ff005b;}
            /* ... Snip! ... */
            .color15 {fill: #e5e5e5;}

            font\-family: Monaco, monospace;
        </style>
    </defs>
    <svg id=\[dq]screen\[dq] width=\[dq]656\[dq] viewBox=\[dq]0 0 656 323\[dq] preserveAspectRatio=\[dq]xMidYMin meet\[dq]>
    </svg>
</svg>
\f[R]
.fi
.PP
Complete example here: gjm8.svg (../termtosvg/data/templates/gjm8.svg)
.SS Custom terminal UI
.PP
Complete example here:
window_frame.svg (../termtosvg/data/templates/window_frame.svg)
.SS Embedding JavaScript
.PP
Just add your code in a new \f[C]script\f[R] element.
.PP
Complete example here:
window_frame_js (../termtosvg/data/templates/window_frame_js.svg)
.SS termtosvg internal template usage
.PP
In order to produce the final animation, termtosvg will modify the
template in a number of ways.
.SS Template scaling
.PP
The first step is to scale the template to the right size based on the
size of the terminal being recorded and the size of the template
specified by the \f[C]screen_geometry\f[R] element.
For this, termtosvg will update the \f[C]viewBox\f[R], \f[C]width\f[R]
and \f[C]height\f[R] attributes of the \f[C]svg\f[R] elements with ids
\[lq]terminal\[rq] and \[lq]screen\[rq].
The \f[C]height\f[R] and \f[C]width\f[R] attributes of these elements
must use pixel units.
.PP
termtosvg will also update the \f[C]columns\f[R] and \f[C]rows\f[R]
attributes of the \f[C]screen_geometry\f[R] to match the values of the
current terminal session and keep things consistent.
.SS Style update
.PP
Next, termtosvg will override the content of the \f[C]style\f[R] element
with id \[lq]generated\-style\[rq] with its own style sheet.
This sheet exposes a CSS variable containing the duration of the
animation in milliseconds, and specifies a few text related attributes.
See example below.
.IP
.nf
\f[C]
<style type=\[dq]text/css\[dq] id=\[dq]generated\-style\[dq]><![CDATA[
    :root {
        \-\-animation\-duration: 36544ms;
    }
    #screen {
        font\-family: \[aq]DejaVu Sans Mono\[aq], monospace;
        font\-style: normal;
        font\-size: 14px;
    }

    text {
        dominant\-baseline: text\-before\-edge;
    }]]>
</style>
\f[R]
.fi
.SS Animation update
.PP
Finally, termtosvg will overwrite the content of the element
\f[C]svg\f[R] with id \[lq]screen\[rq] with the code produced by
rendering the terminal session.
.PP
In the end, the animation produced by termtosvg has the same structure
as the initial template which make it possible to use an animation as a
template (provided the animation was created with termtosvg >= 0.5.0).
.SH AUTHORS
Nicolas Bedos.