docs(examples): add examples information

examples/README.md

@@ -0,0 +1,29 @@
+# Examples
+
+This folder contains some examples of recordings and exports.
+It's intended to be used as a demonstration of features and also to track the file size.
+
+| Example                    | Description                                                                              |
+|----------------------------|------------------------------------------------------------------------------------------|
+| [256colors](256colors.svg) | script to print the 256 xterm colors as background and foreground                        |
+| [htop](htop.svg)           | running htop to see progress bars, headers and pagination                                |
+| [session](session.svg)     | simple terminal session running various commands like ls and cat                         |
+| [444816](444816.svg)       | Asciicast recording of an equilibrium pendulum to see compatibility with asciinema files |
+
+> Files are not embedded here to alleviate loading
+
+
+## Sizes
+
+This table tracks size changes between the first release of the example and the last one as examples are updated on each code change to reflect new features and optimizations.
+
+<!--SIZES_START-->
+| File          | Iterations | First Size | Current Size | Variation |
+|---------------|:----------:|------------|--------------|-----------|
+| 256colors.svg |     2      | 954,73KB   | 950,15KB     | .4800%    |
+| 444816.svg    |     6      | 3,42MB     | 2,92MB       | 15.6300%  |
+| htop.svg      |     4      | 74,15KB    | 63,35KB      | 15.7000%  |
+| session.svg   |     5      | 462,64KB   | 391,84KB     | 16.5700%  |
+
+<!--SIZES_END-->
+> Table generated using [update-filesize.sh](/scripts/update-filesize.sh) script

scripts/update-filesize.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+
+# Root folder using git
+BASE_PATH=$(git rev-parse --show-toplevel)
+
+EXAMPLES_FOLDER="$BASE_PATH/examples"
+SVG_FILES="$EXAMPLES_FOLDER/*.svg"
+
+# Markdown table header
+read -r -d '' TABLE << EOS
+| File | Iterations | First Size | Current Size | Variation |
+|------|:----------:|------------|--------------|-----------|\n
+EOS
+
+
+for filepath in $SVG_FILES; do
+    filename=$(basename $filepath)
+
+    # Get git commit hash history for file
+    blobs=$(git rev-list --all examples/$filename)
+
+    formated_sizes=()
+    raw_sizes=()
+    for blob in $blobs; do
+        # Join commit hash with file path
+        gittag="$blob:examples/$filename"
+
+        # Obtain file size history in bytes
+        bytes=$(git cat-file -s $gittag)
+        raw_sizes+=($bytes)
+
+        # Format bytes to human readable sizes
+        formated_sizes+=($(numfmt --to=si --suffix=B --format=%.2f $bytes))
+    done
+
+    first=${raw_sizes[-1]}
+    current=${raw_sizes[0]}
+
+    # Calculate variation percent using bc to suport floating point
+    variation=`echo "scale=4; (($first-$current)/(($first+$current)/2))*100" | bc`
+
+    # Append row to table
+    TABLE+="| $filename | ${#formated_sizes[@]} | ${formated_sizes[-1]} | ${formated_sizes[0]} | $variation% |\n"
+done
+
+lead='<!--SIZES_START-->'
+tail='<!--SIZES_END-->'
+
+# Replace markers with table
+new_readme=$(sed -n "/$lead/{p;:a;N;/$tail/!ba;s/.*\n/${TABLE//$'\n'/\\n}\n/};p" $EXAMPLES_FOLDER/README.md)
+echo "$new_readme" > $EXAMPLES_FOLDER/README.md