diff --git a/docker/Dockerfile b/docker/Dockerfile
index 39208fb..36fcf8c 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -33,7 +33,8 @@ RUN \
&& /opt/build/venv/bin/python -m pip install -r requirements.txt
COPY ./docs ./docs
-RUN /opt/build/venv/bin/sphinx-build -M html ./docs build
+COPY ./textoutpc ./textoutpc
+RUN /opt/build/venv/bin/sphinx-build -M html ./docs ./build
COPY ./textoutpc ./textoutpc
@@ -52,7 +53,7 @@ COPY --chmod=644 ./docker/nginx.conf /etc/nginx/nginx.conf
WORKDIR /opt/app
COPY --from=venv /opt/app/venv ./venv
COPY --from=builder --chown=app:app /opt/build/textoutpc ./textoutpc
-COPY --from=builder /opt/build/docs/_build/html /opt/app/docs
+COPY --from=builder /opt/build/build/html /opt/app/docs
EXPOSE 80
ENTRYPOINT ["/usr/bin/supervisord"]
diff --git a/docs/Makefile b/docs/Makefile
index c344aee..40c2a08 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -5,7 +5,7 @@
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= poetry run sphinx-build
-SPHINXAUTOOPTS ?= --ignore "*.kate-swp" --watch ../teal
+SPHINXAUTOOPTS ?= --ignore "*.kate-swp" --watch ../textoutpc
SPHINXAUTOBUILD ?= poetry run sphinx-autobuild
SOURCEDIR = .
BUILDDIR = _build
diff --git a/docs/_static/custom.css b/docs/_static/custom.css
new file mode 100644
index 0000000..eaff78c
--- /dev/null
+++ b/docs/_static/custom.css
@@ -0,0 +1,12 @@
+h1 img {
+ vertical-align: top;
+ width: 1.2em;
+}
+
+.sidebar-logo {
+ width: 80%;
+}
+
+.mermaid {
+ text-align: center;
+}
diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
new file mode 100644
index 0000000..af79c77
Binary files /dev/null and b/docs/_static/favicon.ico differ
diff --git a/docs/_static/favicon.png b/docs/_static/favicon.png
new file mode 100644
index 0000000..e5d438a
Binary files /dev/null and b/docs/_static/favicon.png differ
diff --git a/docs/_static/logo.svg b/docs/_static/logo.svg
new file mode 100644
index 0000000..16ec1ef
--- /dev/null
+++ b/docs/_static/logo.svg
@@ -0,0 +1,3 @@
+
+
+
diff --git a/docs/code.rst b/docs/code.rst
new file mode 100644
index 0000000..5b6a1c4
--- /dev/null
+++ b/docs/code.rst
@@ -0,0 +1,9 @@
+Code reference
+==============
+
+This section presents the code reference, by Python module.
+
+.. toctree::
+ :maxdepth: 1
+
+ code/textoutpc
diff --git a/docs/code/textoutpc.rst b/docs/code/textoutpc.rst
new file mode 100644
index 0000000..e200e6d
--- /dev/null
+++ b/docs/code/textoutpc.rst
@@ -0,0 +1,16 @@
+``textoutpc`` -- main namespace for the project
+===============================================
+
+This section presents the code reference under the ``textoutpc`` namespace.
+
+.. toctree::
+ :maxdepth: 1
+
+ textoutpc/builtin
+ textoutpc/demo
+ textoutpc/exceptions
+ textoutpc/html
+ textoutpc/lexer
+ textoutpc/nodes
+ textoutpc/parser
+ textoutpc/tags
diff --git a/docs/code/textoutpc/builtin.rst b/docs/code/textoutpc/builtin.rst
new file mode 100644
index 0000000..dc35cfc
--- /dev/null
+++ b/docs/code/textoutpc/builtin.rst
@@ -0,0 +1,4 @@
+``textoutpc.builtin`` -- built-in tags for textoutpc
+====================================================
+
+.. automodule:: textoutpc.builtin
diff --git a/docs/code/textoutpc/demo.rst b/docs/code/textoutpc/demo.rst
new file mode 100644
index 0000000..eaa5f29
--- /dev/null
+++ b/docs/code/textoutpc/demo.rst
@@ -0,0 +1,4 @@
+``textoutpc.demo`` -- demonstration web app for textoutpc
+=========================================================
+
+.. automodule:: textoutpc.demo
diff --git a/docs/code/textoutpc/exceptions.rst b/docs/code/textoutpc/exceptions.rst
new file mode 100644
index 0000000..3770990
--- /dev/null
+++ b/docs/code/textoutpc/exceptions.rst
@@ -0,0 +1,4 @@
+``textoutpc.exceptions`` -- exceptions for textoutpc
+====================================================
+
+.. automodule:: textoutpc.exceptions
diff --git a/docs/code/textoutpc/html.rst b/docs/code/textoutpc/html.rst
new file mode 100644
index 0000000..0cc65c3
--- /dev/null
+++ b/docs/code/textoutpc/html.rst
@@ -0,0 +1,4 @@
+``textoutpc.html`` -- HTML writer for textoutpc
+===============================================
+
+.. automodule:: textoutpc.html
diff --git a/docs/code/textoutpc/lexer.rst b/docs/code/textoutpc/lexer.rst
new file mode 100644
index 0000000..21e3d71
--- /dev/null
+++ b/docs/code/textoutpc/lexer.rst
@@ -0,0 +1,4 @@
+``textoutpc.lexer`` -- lexer for textoutpc
+==========================================
+
+.. automodule:: textoutpc.lexer
diff --git a/docs/code/textoutpc/nodes.rst b/docs/code/textoutpc/nodes.rst
new file mode 100644
index 0000000..815b762
--- /dev/null
+++ b/docs/code/textoutpc/nodes.rst
@@ -0,0 +1,4 @@
+``textoutpc.nodes`` -- docutils nodes specific to textoutpc
+===========================================================
+
+.. automodule:: textoutpc.nodes
diff --git a/docs/code/textoutpc/parser.rst b/docs/code/textoutpc/parser.rst
new file mode 100644
index 0000000..e186097
--- /dev/null
+++ b/docs/code/textoutpc/parser.rst
@@ -0,0 +1,4 @@
+``textoutpc.parser`` -- docutils parser for textoutpc
+=====================================================
+
+.. automodule:: textoutpc.parser
diff --git a/docs/code/textoutpc/tags.rst b/docs/code/textoutpc/tags.rst
new file mode 100644
index 0000000..43b6868
--- /dev/null
+++ b/docs/code/textoutpc/tags.rst
@@ -0,0 +1,4 @@
+``textoutpc.tags`` -- tag definitions for textoutpc
+===================================================
+
+.. automodule:: textoutpc.tags
diff --git a/docs/conf.py b/docs/conf.py
index 74c3721..3e92d9f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -37,6 +37,8 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
html_theme = "furo"
html_static_path = ["_static"]
html_title = f"textoutpc {version}"
+html_favicon = "_static/favicon.png"
+html_logo = "_static/logo.svg"
html_use_index = False
html_copy_source = False
html_show_sourcelink = False
@@ -45,9 +47,7 @@ html_css_files = ["custom.css"]
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
- "fastapi": ("https://fastapi.tiangolo.com/", None),
- "pydantic": ("https://docs.pydantic.dev/2.4/", None),
- "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
+ "docutils": ("https://sphinx-docutils.readthedocs.io/en/latest/", None),
}
todo_include_todos = True
diff --git a/docs/guides.rst b/docs/guides.rst
new file mode 100644
index 0000000..ed72aed
--- /dev/null
+++ b/docs/guides.rst
@@ -0,0 +1,5 @@
+Guides
+======
+
+This section contains the guides, i.e. concrete steps to accomplish given
+tasks with textoutpc.
diff --git a/docs/index.rst b/docs/index.rst
index 8e1c9c6..74fe6ab 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,31 +1,21 @@
-Welcome to textoutpc's documentation!
-=====================================
+textoutpc |version|
+===================
-textoutpc is a BBcode markup language translator project for `Planète Casio`_.
+This project is a set of docutils_ utilities for parsing and rendering the
+`Planète Casio`_ flavour of BBCode.
-BBcode has been invented in the 90s/2000s for bulletin board systems.
-It has been implemented in `Planète Casio`_ during its first years (although
-some research has to be made on how that choice was done…).
+.. note::
-On `Planète Casio`_, which is coded in PHP at the time I'm writing this,
-we have our own custom version of BBcode, which we pass through an internal
-utility named ``textout()``.
-
-I, Thomas “Cakeisalie5” Touhey, rewrote it recently, and it works pretty well
-while being secure, but as the next version of `Planète Casio`_ (the ”v5”)
-will be written from scratch, I figured out I could rewrite the ``textout()``
-utility in Python, and improve the language parsing to be more practical and
-add features that are in the original BBcode markup language.
-
-As this is a rewrite, the vulnerabilities and bug will not be common to this
-project and the online version of the transcoder.
+ The flavour is named "textout", because that is the name of the original
+ function in the PHP code of the website.
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ :maxdepth: 2
- language
- usage
- tags
+ guides
+ language
+ code
+.. _docutils: https://www.docutils.org/
+.. _BBCode: https://en.wikipedia.org/wiki/BBCode
.. _Planète Casio: https://www.planet-casio.com/Fr/
diff --git a/docs/language.rst b/docs/language.rst
index 48e2cf8..fe8058a 100644
--- a/docs/language.rst
+++ b/docs/language.rst
@@ -1,5 +1,5 @@
-The textout BBcode markup language
-==================================
+Markup language reference
+=========================
The BBcode markup language mainly uses tags, which the starting mark looks
like ``[xxx]`` and the ending mark looks like ``[/xxx]``. You can add an
@@ -10,287 +10,8 @@ It cannot be used with all tags, so when it is used in the examples below,
suppose you can use it, otherwise, it might not be possible (or not
implemented yet).
---------------
-Align the text
---------------
+.. toctree::
-To align the text, you can use either ``[]`` or
-``[align=]`` with any of the following modes:
-
-- ``left``: the text is left-aligned;
-- ``right``: the text is right-aligned;
-- ``center``: the text is aligned at the horizontal middle of the document;
-- ``justify``: the text is justified, i.e. the text spaces are optimized for
- the right'n'word to end at the right of the line.
-
-For example, to right-align some text, you could do something like this:
-
-.. code::
-
- [right]some text[/]
-
-----------------
-Inserting titles
-----------------
-
-Do you want to include titles or subtitles to your message, integrated with
-the website's design? Use the ``[title]`` and ``[subtitle]`` tags for that:
-
-.. code::
-
- [title]Just do it![/]
- [subtitle]Don't let your dreams be dreams![/]
-
-Notice that this tag cannot embed another tag.
-
-----------------
-Styling the text
-----------------
-
-You can add some basic text style by using the following tags:
-
-- ``[b]`` for **bold** text;
-- ``[i]`` for *italic* text;
-- ``[u]`` for underlined text;
-- ``[o]`` for overlined text;
-- ``[s]`` or ``[strike]`` for striked text.
-
-They can all be ended with the generic ending mark ``[/]``.
-
-----------------------
-Changing the text font
-----------------------
-
-You can change the font of the text by using the ``[font=xxx]`` (or ``[xxx]``
-directly, where ``xxx`` represents the font identifier) tag. The following
-fonts are available:
-
-- ``arial`` represents Arial;
-- ``comic`` represents Comic MS;
-- ``tahoma`` represents Tahoma;
-- ``courier`` represents Courier;
-- ``haettenschweiler`` represents Haettenschweiler;
-- ``mono`` and ``monospace`` represents the basic monospace font.
-
-They can be ended with the generic ending mark ``[/]`` as well.
-
------------------------
-Changing the text color
------------------------
-
-You can change the color of the text using the ``[color=xxx]`` (or ``[xxx]``
-directly for simple colors, where ``xxx`` represents the color) tag. This
-tag accepts several types of values:
-
-- simple color names (`inspired from CSS `_) such as
- ``red``, ``blue``, ``green``, ``transparent``;
-- color hex codes using a hash (``#``) followed by hex digits, e.g.
- ``#01020F``, where the first group of hex digits represents the
- red component from 0 to 255, the second group of hex digits represents
- the green component from 0 to 255, and the third group of hex digits
- represents the blue component from 0 to 255.
- Incomplete composites will be filled by zero on the left (e.g. ``#0000F``
- is equivalent to ``#00000F``), invalid characters such as ``A`` will be
- replaced by 0s;
-- three hex digits codes using ``#`` followed by three hex digits, e.g.
- ``#123`` which will be translated to ``#112233``;
-- ``rgb(, , )``, where the red, green and blue components
- are represented using decimal digits and are between 0 and 255 included;
-- ``rgba(, , , )``, where the red, green and blue
- components are expressed as said before and the alpha component is either
- expressed as a percentage (e.g. ``12.34%``) or as a proportion between
- ``0.0`` and ``1.0``;
-- ``hsl(, , )`` or
- ``hls(, ,)``;
-- ``hsl(, , , )`` or
- ``hls(, , , )``;
-- ``hwb(, , )``.
-
-Here are some examples:
-
-.. code::
-
- [blue]I'm blue![/]
- [color=#ff69b4]That color is called “Cuisse de Nymphe émue”![/]
- [color=rgb(255, 255,255,0.4)]I'm black![/]
- [color=hsl(0,100%, 0.5)]I'm red![/]
-
---------------------
-Inserting hyperlinks
---------------------
-
-Creating hyperlinks on a bunch of text is possible through the ``[url]`` tag.
-The URL has to be either absolute, relative, or related to an anchor. It has
-to be passed to the tag either through the argument (which allows the content
-to be the displayed title of the link) or through the content if there is
-no argument. By default, if there is no content and an argument, the argument
-will be taken as the link title.
-
-Here are examples:
-
-.. code::
-
- [url]https://planet-casio.com[/]
- [url=https://planet-casio.com]Planète Casio[/]
- [url=/relative/url.html][/]
-
-For links to profiles, the ``[profil]`` and ``[profile]`` tags can be used.
-They take no attribute but take a content which is the user whose the profile
-is to be linked's name. For example:
-
-.. code::
-
- [profil]Cakeisalie5[/]
-
-For links to topics and tutorials, the ``[topic]`` and ``[tutorial]``
-tags can be used. They take no attribute but take a content which is the
-identifier of the topic or tutorial to which to link to.
-For example:
-
-.. code::
-
- [topic]234[/]
- [tutorial]32[/]
-
-For links to programs, the ``[program]`` and ``[prog]`` tags can be used.
-They take no attribute but take a content which is the identifier of the
-program to which to link to. For example:
-
-.. code::
-
- [program]3598[/program]
-
----------------
-Quoting someone
----------------
-
-To quote someone visually, you can use the ``[quote]`` tag, which takes the
-name of the person you're quoting as the attribute and the quote as the
-content. A quote can contain another one, of course. If there is no name,
-the display will just be generalistic.
-
-Here are examples:
-
-.. code::
-
- [quote]Someone said that.[/]
- [quote=Cakeisalie5]Ever realized that my name contained “Cake”?[/]
-
--------------------------
-Spoilers/Content Warnings
--------------------------
-
-To hide something behind a deliberate action of your user, usually to avoid
-hurting people or to hide the solution to a problem, you can use the
-``[spoiler]`` tag.
-
-.. code::
-
- [spoiler]This is hidden![/]
- [spoiler=Uncover the dark secrets of the night]Boo![/]
- [spoiler=Uncover this!|Cover this quick!!]BOOO![/]
-
----------------
-Presenting code
----------------
-
-There are two code tags:
-
-- ``[code]``, which is supposed to be used as a block for multiline code or
- to isolate the code from the text;
-- ``[inlinecode]`` or the *backquotes* to include code in the text.
-
-For example:
-
-.. code::
-
- [code]Some multiline code, with [center]tags shown as they are[/center].
- Incredible, heh?[/code]
- [inlinecode]Some inline code.[/inlinecode]
- `Some more inline code.`
-
-------------------
-Inserting an image
-------------------
-
-In order to insert an image, you will have to use the ``[img]`` tag. It will
-make a new paragraph containing the image which the URL is given in the
-tag content. The tag can be bundled with some attributes, separated with
-the pipe (``|``) character:
-
-- ``x``: set the dimensions to the image. If the width isn't
- given (i.e. if this attribute starts with ``x``), the height will be set
- automatically. If the height isn't given (i.e. no ``x`` or nothing after
- the ``x``), the width will be set automatically;
-- ``left``, ``right``, ``center``: align the image accordingly;
-- ``float``: make the image float, i.e. let the text be where the image isn't.
-
-For example:
-
-.. code::
-
- [img=right|float|x24]https://example.org/image.jpg[/]
-
-is a right-aligned image, floating (which means text will be allowed on
-the left of the image), and with a height of 24 pixels and an automatic
-width.
-
-Planète Casio admins can use the ``[adimg]`` tag which is equivalent to the
-``[img]`` tag but adds the special admin image folder prefix to the image
-URLs, so this is possible:
-
-.. code::
-
- [adimg]incredible.jpg[/]
-
------------------
-Inserting a video
------------------
-
-This BBcode translator has the ability to integrate videos from some online
-platforms into your message, as a block. To do this, you can use the
-``[video]`` and ``[video tiny]`` tags. For example:
-
-.. code::
-
- [video]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
- [video tiny]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
-
-------------------------
-Inserting a progress bar
-------------------------
-
-Do you want to present how your project is evolving using a simple graph,
-the progress bar? This is possible using the ``[progress]`` tag, which takes
-the percentage (between 0 and 100 included) of the advancement as its
-attribute. For example:
-
-.. code::
-
- [progress=50]Building a great wall…[/]
- [progress=100][/]
-
-----------------------------
-Inserting labels and targets
-----------------------------
-
-Is your message in several parts and you only want to link one without using
-an entire separate page for the section? This is the tag you might want
-to use. To link to a point in your message:
-
-- first, define the label using the ``[label]`` tag, with the name of the
- label as the attribute;
-- then link to the label using the ``[target]`` tag.
-
-You are not obliged to terminate the ``[label]`` tag (the original version of
-it didn't support the ``[label]`` tag termination, in fact). For example:
-
-.. code::
-
- [label=sometag][subtitle]Some chapter[/subtitle]
-
- ...
-
- [target=sometag]Go back to the beginning of the chapter[/]
-
-.. _CSS named colors: https://drafts.csswg.org/css-color/#named-colors
+ language/document
+ language/style
+ language/multimedia
diff --git a/docs/language/document.rst b/docs/language/document.rst
new file mode 100644
index 0000000..f10b173
--- /dev/null
+++ b/docs/language/document.rst
@@ -0,0 +1,84 @@
+Document structure
+==================
+
+These tags can be used to represent the document structure.
+
+.. _markup-title:
+
+Titles and subtitles
+--------------------
+
+In order to represent titles and subtitles integrated with the website's
+design, the ``[title]`` and ``[subtitles]`` tags can be used::
+
+ [title]Just do it![/]
+ [subtitle]Don't let your dreams be dreams![/]
+
+.. note::
+
+ These tags cannot embed other tags.
+
+.. _markup-label:
+
+Labels and targets
+------------------
+
+Internal references can be defined using labels and targets:
+
+* Labels place an anchor on a part of the message. They are defined using
+ the ``[label=]`` tag.
+* Targets make a link to a label in another part of the message. They are
+ defined using the ``[target=]`` tag.
+
+.. note::
+
+ The ``[label]`` tag does not need to be terminated; in fact, the original
+ version of the tag did not support termination.
+
+An example usage of these tags is the following::
+
+ [label=sometag][subtitle]Some chapter[/subtitle]
+
+ ...
+
+ [target=sometag]Go back to the beginning of the chapter[/]
+
+.. _markup-url:
+
+Hyperlinks
+----------
+
+Hyperlinks, i.e. reference to other documents available on the World Wide Web,
+can be inserted using the ``[url]`` tag. The URL can be provided:
+
+* As the tag value, e.g. ``[url=https://example.org/]My name[/url]``.
+ This is mostly useful in order to place a label.
+* As the tag contents, e.g. ``[url]https://example.org/[/url]``.
+
+The URL itself can be either absolute, relative, or related to an anchor.
+
+Example uses are the following::
+
+ [url]https://planet-casio.com[/]
+ [url=https://planet-casio.com]Planète Casio[/]
+ [url=/relative/url.html][/]
+
+For links to profiles, the ``[profil]`` and ``[profile]`` tags can be used.
+They take no attribute but take a content which is the user whose the profile
+is to be linked's name. For example::
+
+ [profil]Cakeisalie5[/]
+
+For links to topics and tutorials, the ``[topic]`` and ``[tutorial]``
+tags can be used. They take no attribute but take a content which is the
+identifier of the topic or tutorial to which to link to.
+For example::
+
+ [topic]234[/]
+ [tutorial]32[/]
+
+For links to programs, the ``[program]`` and ``[prog]`` tags can be used.
+They take no attribute but take a content which is the identifier of the
+program to which to link to. For example::
+
+ [program]3598[/program]
diff --git a/docs/language/multimedia.rst b/docs/language/multimedia.rst
new file mode 100644
index 0000000..f79cf10
--- /dev/null
+++ b/docs/language/multimedia.rst
@@ -0,0 +1,103 @@
+Multimedia elements
+===================
+
+The following tags can be used to add complex elements.
+
+.. _markup-quote:
+
+Quotes
+------
+
+To quote someone visually, one can use the ``[quote]`` tag.
+This tag takes an optional value being the person or entity being quoted.
+
+Some examples are::
+
+ [quote]Someone said that.[/]
+ [quote=Cakeisalie5]Ever realized that my name contained “Cake”?[/]
+
+.. _markup-code:
+
+Code blocks or spans
+--------------------
+
+There are two tags suitable for presenting code:
+
+``[code]``
+ Block to present multiline code or isolate the code from the text.
+
+``[inlinecode]`` *(or backquotes)*
+ Inline code markup.
+
+Example uses are::
+
+ [code]Some multiline code, with [center]tags shown as they are[/center].
+ Incredible, heh?[/code]
+ [inlinecode]Some inline code.[/inlinecode]
+ `Some more inline code.`
+
+.. _markup-image:
+
+Images
+------
+
+In order to insert an image, the ``[img]`` tag can be used.
+It will make a new paragraph containing the image which the URL is given in the
+tag content. The tag can be bundled with some attributes, separated with
+the pipe (``|``) character:
+
+* ``x``: set the dimensions to the image. If the width isn't
+ given (i.e. if this attribute starts with ``x``), the height will be set
+ automatically. If the height isn't given (i.e. no ``x`` or nothing after
+ the ``x``), the width will be set automatically;
+* ``left``, ``right``, ``center``: align the image accordingly;
+* ``float``: make the image float, i.e. let the text be where the image isn't.
+
+The following example is a right-aligned image, floating (which means text
+will be allowed on the left of the image), and with a height of 24 pixels and
+an automatic width::
+
+ [img=right|float|x24]https://example.org/image.jpg[/]
+
+Planète Casio administrators can use the ``[adimg]`` tag which is equivalent to
+the ``[img]`` tag but adds the special admin image folder prefix to the image
+URLs, so this is possible::
+
+ [adimg]incredible.jpg[/]
+
+Videos
+------
+
+Videos can be inserted as blocks using the ``[video]`` or ``[video tiny]``
+tag. For example::
+
+ [video]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
+ [video tiny]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
+
+.. _markup-progress-bar:
+
+Progress bars
+-------------
+
+In order to insert a progress bar, the ``[progress]`` tag can be used.
+This tag takes an integer value between 0 and 100 included representing
+the advancement.
+
+For example::
+
+ [progress=50]Building a great wall…[/]
+ [progress=100][/]
+
+.. _markup-spoiler:
+
+Spoilers / Content Warnings
+---------------------------
+
+In order to hide something behind a deliberate action of the user,
+the ``[spoiler]`` tag can be used.
+
+For example::
+
+ [spoiler]This is hidden![/]
+ [spoiler=Uncover the dark secrets of the night]Boo![/]
+ [spoiler=Uncover this!|Cover this quick!!]BOOO![/]
diff --git a/docs/language/style.rst b/docs/language/style.rst
new file mode 100644
index 0000000..fd5364f
--- /dev/null
+++ b/docs/language/style.rst
@@ -0,0 +1,145 @@
+Text styling
+============
+
+The following tags can be used to style the textual content of the messages.
+
+.. _markup-align:
+
+Alignment
+---------
+
+In order to align text, one can either use ``[]`` or
+``[align=]`` with any of the following modes:
+
+``left``
+ The text is left-aligned.
+
+``right``
+ The text is right-aligned.
+
+``center``
+ The text is aligned at the horizontal middle of the document;
+
+``justify``
+ The text is justified, i.e. the text spaces are optimized for
+ the right'n'word to end at the right of the line.
+
+For example, to right-align some text, one can do the following::
+
+ [right]some text[/]
+ [align=right]some more text[/]
+
+.. _markup-strong:
+
+Font weight
+-----------
+
+In order to have text with more weight, the ``[b]`` tag can be used.
+For example::
+
+ [b]Some bold text[/]
+
+.. _markup-italic:
+
+Font style
+----------
+
+In order to set the font as italic, the ``[i]`` tag can be used.
+For example::
+
+ [i]Some italic text[/]
+
+.. _markup-decoration:
+
+Font decoration
+---------------
+
+The following decorations can be applied to text using the following tags:
+
+``[u]``
+ The text will be underlined.
+
+``[o]``
+ The text will be overlined.
+
+``[s]`` or ``[strike]``
+ The text will have a line through.
+
+For example::
+
+ [u]This text is underlined.[/]
+ [o]This text is overlined.[/]
+ [s]This text is striked through.[/]
+
+.. _markup-font:
+
+Text font
+---------
+
+The text font can be set using the ``[font=xxx]`` (or ``[xxx]``
+directly, where ``xxx`` represents the font identifier) tag.
+The following fonts are available:
+
+``arial``
+ Arial.
+
+``comic``
+ Comic MS.
+
+``tahoma``
+ Tahoma.
+
+``courier``
+ Courier.
+
+``haettenschweiler``
+ Haettenschweiler.
+
+``mono`` or ``monospace``
+ Monospace.
+
+For example::
+
+ [comic]This text is in comic font![/]
+
+.. _markup-color:
+
+Text color
+----------
+
+The color of the text can be set using the ``[color=xxx]`` (or ``[xxx]``
+directly for simple colors, where ``xxx`` represents the color) tag. This
+tag accepts several types of values:
+
+- Simple color names (`inspired from CSS `_) such as
+ ``red``, ``blue``, ``green``, ``transparent``;
+- Color hex codes using a hash (``#``) followed by hex digits, e.g.
+ ``#01020F``, where the first group of hex digits represents the
+ red component from 0 to 255, the second group of hex digits represents
+ the green component from 0 to 255, and the third group of hex digits
+ represents the blue component from 0 to 255.
+ Incomplete composites will be filled by zero on the left (e.g. ``#0000F``
+ is equivalent to ``#00000F``), invalid characters such as ``A`` will be
+ replaced by 0s;
+- Three hex digits codes using ``#`` followed by three hex digits, e.g.
+ ``#123`` which will be translated to ``#112233``;
+- ``rgb(, , )``, where the red, green and blue components
+ are represented using decimal digits and are between 0 and 255 included;
+- ``rgba(, , , )``, where the red, green and blue
+ components are expressed as said before and the alpha component is either
+ expressed as a percentage (e.g. ``12.34%``) or as a proportion between
+ ``0.0`` and ``1.0``;
+- ``hsl(, , )`` or
+ ``hls(, ,)``;
+- ``hsl(, , , )`` or
+ ``hls(, , , )``;
+- ``hwb(, , )``.
+
+Some examples are::
+
+ [blue]I'm blue![/]
+ [color=#ff69b4]That color is called “Cuisse de Nymphe émue”![/]
+ [color=rgb(255, 255,255,0.4)]I'm black![/]
+ [color=hsl(0,100%, 0.5)]I'm red![/]
+
+.. _CSS named colors: https://drafts.csswg.org/css-color/#named-colors
diff --git a/docs/tags.rst b/docs/tags.rst
deleted file mode 100644
index 17a9d05..0000000
--- a/docs/tags.rst
+++ /dev/null
@@ -1,124 +0,0 @@
-Defining tags for textoutpc
-===========================
-
-A tag is a class defined in the ``textoutpc.Tags`` submodule and referenced
-in the `_tags` array in ``textoutpc.Tags.__init__``. It usually takes a name
-that starts with ``Textout`` and an uppercase character, and finishes by
-``Tag``, and shall inherit one of the base classes defined in
-``textoutpc.Tags.__base__`` depending on how the tag will be used:
-
-- ``TextoutInlineTag``: tag to be used inside a paragraph,
- e.g. text formatting;
-- ``TextoutBlockTag``: tag to be used at paragraph level, e.g. video.
-
-There are a few public members you can define as a tag:
-
-- ``aliases``: the array of names this tag can be accessed as.
- Basic tags (the ones with brackets ``[]``) are defined as ``[]``
- (e.g. ``[hello]``) and special characters are defined with their symbol,
- e.g. `````;
-- ``raw``: the tag's content shall not be interpreted, which is generally
- only useful when the content is preprocessed (see below). The default
- is ``False`` if there is no preprocess method, and `True` otherwise;
-- ``noinline``: for raw tags, forbid inline tags (declared outside of the
- tag) within the tag (*only works with ``raw = True``*!);
-- ``generic``: the tag can be ended using the generic tag ending mark ``[/]``.
- It is defined as ``True`` by default for all tags;
-- ``notempty``: ignore the tag when its content is empty. By default, this
- value is `False`;
-- ``superblock``: is a super-block (for blocks) which means it adds a block
- level, and adds a paragraph tag implicitely;
-- ``inlined``: if is a block, transforms automatically the surrounding block
- into a superblock while it's there;
-- ``procvalue``: process the value as normal text before passing it;
-- ``not_within_itself``: make that if a tag is opened within itself (depth
- included), the tag above and all tags below are closed first;
-- ``only_in``: allow the tag to only be beneath certain tags;
-- ``allowed_tags``: allowed tags right beneath the current one;
-- ``no_text``: disable raw text within the tag;
-- ``expect_child``: make that all content below (without depth) that isn't
- within the specified tags is ignored.
-
-So for example, if I want to make the inline tag ``[hello]`` as an example,
-with the alternate name ``[hai]``, I'd start off by writing:
-
-.. code-block:: python
-
- from textoutpc import InlineTag as _InlineTag
-
- class TextoutHelloTag(_InlineTag):
- """ The [hello] tag, which does things.
- Example uses:
-
- [hello]world[/hello]
- [hai=something]world[/hai] """
-
- aliases = ('[hello]', '[hai]')
-
- # ...
-
----------------------
-Getting the arguments
----------------------
-
-There are two methods the tag can define to get various parts of the user
-input:
-
-- ``prepare(name, value)``: the tag has been called, but the content has not
- yet been read — this method uses the name and the value to define the tag's
- behaviour. By default, when prepared, the tag does nothing;
-- ``preprocess(content)``: the content has been read and the tag wants to know
- about it — this method uses the content to define the tag's behaviour.
- By default, the tag prints its content while reading it (instead of
- storing it for this method);
-- ``default()``: the content is empty and the tag wants to know about it (this
- method is only called when ``preprocess()`` is not defined).
-
-Both methods can raise an exception (whatever the exception is) if the tag
-is called with invalid arguments; when this is the case, the tag is just
-printed as is, e.g. in ``[color=;;]test[/color]``, the ``TextoutColorTag``
-will return an exception at preparation, and the tag will be printed as is.
-
-The ``prepare()`` and ``preprocess()`` method can be defined for given output
-types (languages, e.g. ``html`` or ``lightscript``) by setting up
-``_