Initial commit0.1.0

1 files changed, 43 insertions, 0 deletions

diff --git a/docs/usage/namespaces.rst b/docs/usage/namespaces.rst
new file mode 100644
index 0000000..4eacb14
--- /dev/null
+++ b/docs/usage/namespaces.rst
@@ -0,0 +1,43 @@
+Namespaces & Tags
+=================
+
+As :ref:`mentioned earlier <overview-tags>`, the use of namespaces is required
+when tagging comics. The user must also choose which namespaces a tag is
+applicable to. That means that in order for the :term:`qualified tag`
+``female:love interest`` to appear as a valid selection, the following must be
+true:
+
+1. The namespace ``female`` must exist.
+2. The tag ``love interest`` must exist.
+3. The tag ``love interest`` must specify ``female`` as a valid namespace.
+
+.. note::
+
+   Qualified tags that are subsequently rendered invalid will **not**
+   automatically be removed from comics. Whilst the qualified tag can no longer
+   be selected in the editing or filtering interface, it can still be removed
+   from the comic manually.
+
+Namespace sorting
+-----------------
+
+Namespaces may be configured with a "sort name". This name will be used when
+sorting lists of namespaces or qualified tags. If no such name is given, the
+namespace name is used for sorting instead.
+
+Tag descriptions
+----------------
+
+Tags may be annotated with a custom description that further explains how the
+tag should be used. This description will be displayed as a tooltip when
+hovering over a qualified tag.
+
+Qualified tag display
+---------------------
+
+When selecting from a list, qualified tags are displayed by combining the
+namespace and tag with a colon, like ``female:love interest``. In all other
+contexts, qualified tags are rendered as small pills that contain the tag name
+only. A small number of namespaces have special handling, however: *female*,
+*male*, *trans*, *mixed*, and *location*. These are displayed with a specific
+colour and icon.