Move template manual to section 5 (#80)

Makefile

@@ -48,7 +48,7 @@ venv_dev: setup.py
 man: venv_dev
 	$(VENV_ACTIVATE) && \
 	    pandoc man/termtosvg.md -s -t man > man/termtosvg.man.1 && \
-	    pandoc man/termtosvg-templates.md -s -t man > man/termtosvg-templates.man.1
+	    pandoc man/termtosvg-templates.md -s -t man > man/termtosvg-templates.man.5
 
 static: man
 	(test -d $(VENV_PATH) || python -m venv $(VENV_PATH))

man/termtosvg-templates.man.5

@@ -0,0 +1,189 @@
+.\" 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.

man/termtosvg-templates.md

@@ -1,4 +1,4 @@
-% TERMTOSVG-TEMPLATES(1)
+% TERMTOSVG-TEMPLATES(5)
 % Nicolas Bedos
 % November 2018