--- a/docs/conf.py	Thu May 07 15:49:13 2026 +0200
+++ b/docs/conf.py	Thu May 07 16:06:59 2026 +0200
@@ -57,6 +57,7 @@
 .. _Pygments: https://pygments.org/
 .. _Sphinx: https://www.sphinx-doc.org
 .. _Python: https://www.python.org/
+.. _Algpseudocodex: https://ctan.org/pkg/algpseudocodex
 """
 
 

--- a/docs/details-algpseudocode.rst	Thu May 07 15:49:13 2026 +0200
+++ b/docs/details-algpseudocode.rst	Thu May 07 16:06:59 2026 +0200
@@ -43,21 +43,97 @@
 Comments
 ========
 
-- with the ``\REMARK`` or ``\REM`` keywords
+- with the ``\REMARK`` or ``\REM`` keywords (this includes a leading symbol)
 - multi-line comments with ``/* ... */``; they can be **nested**
 - multi-line comments with ``(* ... *)``; they can be **nested**
 - single-line comments with ``//`` or ``#`` (until the end of the line)
 
+.. code-block:: algpseudocode
+
+   /*
+    * A single multiline comment
+    */
+
+   /*
+    * A multiline comment
+    *
+    * /* This is a nested multi-line comment */
+    *
+    */
+
+   (*
+    * A multiline comment
+    *
+    * (* This is a nested multi-line comment *)
+    *
+    *)
+
+   // A single-line comment
+
+   # A single-line comment
+
+   \REM A remark has a leading symbol
+
 
 Literals
 ========
 
-Strings and numbers as in `Python`_.
+Strings and numbers as in `Python`_. String prefixes ``r``, ``f`` and ``t``
+are not supported -- ``u`` and ``b`` are.
 
 To yield non-string-delimiting single- and double-quotes you have to escape them
 using ``\'`` or ``\"``. This must be used to typeset something as
 :algpseudocode:`f\\'(x) = 0`.
 
+.. code-block:: algpseudocode
+
+   0  0xdead 0b100001 0o720  2.7 2.7e-54
+
+   "A string with an escaped double-quote \" "
+
+   'Another string with an escaped single-quote \' '
+
+   """A multiline
+   string
+   """
+
+   '''Another multiline string
+
+   '''
+
+   b"A \x20 byte string"
+
+   u'An explicit Unicode \u1234 string'
+
+   \"  a non string
+
+   \'  a non string also
+
+
+(Mathematical) Symbols and Operators
+====================================
+
+Some ASCII symbol combinations are recognized and replaced by a
+Unicode symbol:
+
+.. code-block:: algpseudocode
+
+   \TEXT{<=>}    <=>
+   \TEXT{<->}    <->
+   \TEXT{<-}     <-
+   \TEXT{->}     ->
+   \TEXT{=>}     =>
+   \TEXT{<=}     <=
+   \TEXT{>=}     >=
+   \TEXT{<>}     <>
+   \TEXT{!=}     !=
+   \TEXT{:=}     :=
+   \TEXT{=:}     =:
+   \TEXT{?=}     ?=
+
+Unicode codepoints with property ``Sm`` are recognized as mathematical symbol
+and highlighted accordingly.
+
 
 Keywords
 ========
@@ -109,6 +185,8 @@
 
    \TEXT{\CALL{a function\}(p1, p2)}                  \CALL{a function}(p1, p2)
 
+   \TEXT{\NAME{an entity name\}}                      \NAME{an entity name}
+
 
 With Optional Parameters
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -164,11 +242,13 @@
    \TEXT{\IS}                                \IS
    \TEXT{\WITH}                              \WITH
 
-   \TEXT{\\REMARK   or   \\REM}                \REMARK A comment with a sigil
+   \TEXT{\GETS}                              \GETS
+
+   \TEXT{\\REMARK   or   \\REM}                \REMARK A comment with a leading symbol
 
 ``\REMARK`` or ``\REM`` is special: all characters to the end of the
-line are taken as comment; curly braces are not needed -- in fact:
-they are interpreted as part of the comment.
+line are taken as comment; curly braces are not needed---in fact:
+they are interpreted to be part of the comment.
 
 
 END-Keywords
@@ -210,6 +290,32 @@
    \text{\END-LOOP}                            \END-LOOP
 
 
+Names and Entities
+==================
+
+In an expression context all other words are interpreted as entity
+names (token type ``Token.Name.Entity``).
+
+Allowed characters in the words follow the corresponding `Python`_ rules.
+As such, many Unicode characters are allowed.
+
+To highlight entity names with whitespace or other "special" characters in it
+use the ``NAME`` command.
+
+.. code-block:: algpseudocode
+
+   \TEXT{entity_name_1}          entity_name_1
+
+   \TEXT{entity_name_2}          entity_name_2
+
+   \TEXT{\NAME{entity-name 3\}}   \NAME{entity-name 3}
+
+   \TEXT{München}                München
+
+   \TEXT{Genève}                 Genève
+
+.. _explicit-token-types:
+
 Explicit Token Types
 ====================
 
@@ -254,12 +360,12 @@
    \text{• \\ttx-o<∈ ∌>}   \ttx-o<∈ ∌>         \rem ∈ and ∌ as (ordinary) Operators
      /*
       * The line below has ∈_∌ as (peculiar) function name.
-      * Their params are automatic.
+      * Their params are automatic (i.e. a normal expression).
       */
    \text{• \\ttx-nf<∈_∌>(p1, p2)}                \ttx-nf<∈_∌>(p1, p2)
      /*
       * The line below has ∈_∌ as (peculiar) decorator name (as used in Python).
-      * Their params are automatic.
+      * Their params are automatic (i.e. a normal expression).
       */
    \text{• \\ttx-nd[∈_∌](p1, p2)}                \ttx-nd[∈_∌](p1, p2)
      /*

--- a/docs/details-frpseudocode.rst	Thu May 07 15:49:13 2026 +0200
+++ b/docs/details-frpseudocode.rst	Thu May 07 16:06:59 2026 +0200
@@ -1,5 +1,7 @@
 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
 
+.. _fr-pseudocode:   
+
 **************
  FrPseudocode
 **************

--- a/docs/example-1.pseudocode	Thu May 07 15:49:13 2026 +0200
+++ b/docs/example-1.pseudocode	Thu May 07 16:06:59 2026 +0200
@@ -4,12 +4,12 @@
   /*
    * The program is here, but it also could be an \ALGORITHM
    *
-   * /* YES! Nested multiline comments work! */
+   * /* YES! Nested multi-line comments work! */
    */
 
   \PROC {A Procedure name} \IS
     \TBLOCK {A text block 1}
-    \TBLOCK {A text block 2 with an expression: \expr{flag is FALSE}}
+    \TBLOCK {A text block 2 with a nested expression: \expr{flag is FALSE}}
     \BLOCK {
         \REMARK  A remark on its own line within a "BLOCK"
     }
@@ -31,9 +31,14 @@
     a and b xor (c in d)      \rem this is another remark
 
     # This is another one-line comment
+
+    (* Here is a "block" of expressions.
+       A block has a leading symbol. *)
     \block {foo
       bar}
     \block{a 1.2 {x in X\} c}
+    (* Analogous there is a variant that is in text-mode by default.
+       It has an other leading symbol. *)
     \tstate{We will compute next \expr{a xor b or (\text{set} X is Empty)} \rem without c!
       or multiply it the other way round}
 

--- 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

--- a/docs/lexerlist.rst	Thu May 07 15:49:13 2026 +0200
+++ b/docs/lexerlist.rst	Thu May 07 16:06:59 2026 +0200
@@ -13,7 +13,7 @@
      - Lexer Class
 
    * - AlgPseudocode
-     - Pseudocode lexer heavily inspired by CTAN's "Algpseudocodex"
+     - Pseudocode lexer heavily inspired by CTAN's `Algpseudocodex`_
      - \*.algpseudocode, \*.algpseudo
      - algpseudocode, algpseudo
      - AlgPseudocodeLexer