--- a/docs/intro.rst	Thu May 07 15:49:13 2026 +0200
+++ b/docs/intro.rst	Thu May 07 16:06:59 2026 +0200
@@ -26,7 +26,8 @@
 
    \END PROGRAM {The Pseudoprogram}
 
-And the same with the german variant:
+And the same with the german variant
+(using ``.. code-block:: algpseudocode-de`` as language alias):
 
 .. code-block:: algpseudocode-de
 
@@ -34,15 +35,55 @@
 
    \END PROGRAM {The Pseudoprogram}
 
-Expressions:
+A basic documentation for FrPseudocode you find on its
+:ref:`detail page <fr-pseudocode>`.
+
+The AlgPseudocode lexer and its friends AlgPseudocodeDE and AlgPseudocodeFR
+basically work in three states: `default`, `expression` and `text`.
+
+  In expressions it automatically recognizes:
+
+  - Strings (single-quote, double-quote, triple-single-quote,
+    triple-double-quote, `Python`_ style)
+  - Numbers (also `Python`_ style)
+  - (Mathematical) operators and symbols
+  - ``\TEXT{...}``
+
+    To switch in a text-mode that prohibits automatic expression
+    highlighting.
+
+    A closing curly brace can be quoted with ``\}`` to not end the
+    text mode prematurely.
+
+  - ``\NAME``, ``\CALL`` and ``\GETS``
+
+  - ``\REM`` and ``\REMARK`` for remarks (aka comments)
 
-- Strings (single-quote, double-quote, triple-single-quote, triple-double-quote)
-- Numbers (Python style)
-- ``\TEXT{...}``
+  - Names (`Name.Entity`)
+
+  - :ref:`explicit-token-types`
+
+  In the default-mode it recogzizes expressions and additionally all
+  sorts of comments and commands that are inspired by CTAN's
+  `Algpseudocodex`_.
+
+  In texts it recogzizes:
+
+  - ``\EXPR`` or ``\EXPRESSION``
 
-  The curly brace can be quoted with ``\}`` to not end the text mode
+    To switch to expression-mode.
+
+    A closing curly brace can be quoted with ``\}`` to not end the expression
+    mode prematurely.
+
+  - ``\REM`` and ``\REMARK`` for remarks (aka comments)
 
-- Names (`Name.Entity`)
+  - :ref:`explicit-token-types`
+
+
+.. rubric:: Some Examples
+
+A synthetic example with most features:
 
 .. literalinclude:: example-1.pseudocode
    :language: algpseudocode