Add docs for themes

Author: panglesd

docs/themes.rst

@@ -3,14 +3,69 @@
 Themes
 ========
 
-Theme support is a work in progress!
+Using a theme
+-------------
 
-In the meantime, you can add CSS (inline or via a link) directly in your
-presentation. Here is a non exhaustive list of CSS selector you might be
-interested in tweaking:
+Theme support is pretty recent in Slipshow. As a consequence, there aren't many themes to choose from... yet!
 
-* ``.slip-body`` to restyle a slip, eg to add margin, set font size and color...
-* ``.block``, ``.theorem``, ``.lemma``, ``.definition``, ``.example``,
-  ``.corollary``, ``.remark``, for admonitions (with special rules when they
-  have the attribute ``title`` defined),
-* Any non-specific elements, such as titles, paragraphs, ...
+To choose a theme, use the ``--theme`` argument. It can take the name of a builtin theme, a path to a css file, or a URL pointing to a CSS file.
+
+Example:
+
+.. code-block:: console
+
+                $ slipshow pres.md                  # Use the default theme
+                $ slipshow --theme default pres.md  # Use the default theme, explicitely
+                $ slipshow --theme none pres.md     # Do not include any theme
+                $ slipshow --theme file.css pres.md # Use file.css as the theme
+                $ # Use the linked file as the theme:
+                $ slipshow --theme https://example.org/my-theme.css pres.md
+                $ # /!\ Needs internet connection to view the presentation!
+
+If you do not want to change the theme, but to extend it, use the ``--css`` argument instead.
+
+Currently, only the default theme is builtin. However, you can write your own theme!
+
+Creating a theme
+----------------
+
+Creating a theme consists in writing a CSS file.
+
+Each theme can define any CSS rule. Once Slipshow is more stable, it will provide a list of classes with their meaning, that is guaranteed not to change (even if the engine change).
+
+Currently, the layouts may still slightly change, necessiting updates in the themes. However, these changes won't happen frequently, and will likely be easy to update!
+
+Here are some classes that may be of interest for a theme writer:
+
+- ``.slip-body`` to define the look of the content of a slip.
+- ``.block`` for the blocks, which can take a ``title="..."`` parameter. Similarly for ``.theorem``, ``.lemma``, ``.definition``, ``.example``, ``.corollary``, ``.remark``.
+- ``#slipshow-universe`` for styling the "universe", the element containing all of the presentation's elements.
+- ``#slipshow-open-window`` for styling the background color outside of the universe.
+- Titles. Make sure not to change the system UI.
+
+If you want to change the font, make sure to have a self-contained css file, by using data URLs to embed the font in the CSS file. Example:
+
+
+.. code-block:: css
+
+                @font-face {
+                  font-family: 'Dosis';
+                  src: url(data:font/truetype;charset=utf-8;base64,AAEAAA...WggBEAAA=) format('truetype-variations');
+                  font-weight: 500;
+                }
+
+where the ``AAEAA...WggBEAAA=`` string can be found with the base64 utility, for instance:
+
+.. code-block:: console
+
+                $ base64 -w 0 dosis-variable.ttf
+
+Submitting a theme
+------------------
+
+If you have written a theme, thank you! I'm happy to:
+
+- Include a link to it in this documentation,
+- Maybe, even include it as a builtin theme!
+
+This way, I can also ping you on breaking changes.

src/engine/themes/default.css

@@ -16,10 +16,6 @@ h1:not(#slipshow-toc h1) {
   text-align: center;
 }
 
-body.slipshow-drawing-mode {
-  touch-action: pinch-zoom;
-}
-
 /*************************************/
 /*    Blocks                         */
 /*************************************/

src/engine/themes/system.css

@@ -51,3 +51,8 @@
   vertical-align: middle;
   line-height: 10vh;
 }
+
+
+body.slipshow-drawing-mode {
+  touch-action: pinch-zoom;
+}

test/engine/basic.t/new_engine.md

@@ -3,25 +3,25 @@ Salut !
 
 
 
-{pause scroll}
+{pause scroll .theorem title="Hello"}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .definition}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .definition title="Yoyo"}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .corollary}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .corollary title="Coco"}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .remark}
 AAAAAAAAAAAAAA A
 
-{pause scroll}
+{pause scroll .remark title="Rere"}
 AAAAAAAAAAAAAA A
 
 {pause scroll}