--- a/docs/examples/example-1.pseudocode	Tue May 19 18:50:24 2026 +0200
+++ b/docs/examples/example-1.pseudocode	Tue May 19 19:01:27 2026 +0200
@@ -17,7 +17,8 @@
 
   \FUNCTION{A Function with {escaped\} text} \IS
     (1234567890 != what) or a and b xor (c in d)   \rem this is another remark
-    \block {foo bar}
+    \block {foo is not bar}
+    \block {2 + 6 = 1 (mod 7)}
 
     \IF a is nil \THEN
       \text{Set something}
@@ -34,13 +35,14 @@
 
     (* Here is a "block" of expressions.
        A block has a leading symbol. *)
-    \block {foo
-      bar}
+    \block {foo ?= bar
+      Bär >= Maus
+        and Bär != Maus}
     \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}
+      or multiply it the \ttx-ges/other/ way.}
 
     \tstate{foo bar     \rem A remark within a text statement until LF!
       nextfoo nextbar

--- a/docs/lexer-algpseudocode.rst	Tue May 19 18:50:24 2026 +0200
+++ b/docs/lexer-algpseudocode.rst	Tue May 19 19:01:27 2026 +0200
@@ -19,7 +19,7 @@
 They recognize all sorts of single- and multi-line comments in addition to
 expressions and commands that are inspired by `Algpseudocodex`_.
 
-They may be used in `Sphinx`_ by their aliases.
+They are used in `Sphinx`_ using their aliases.
 The code-block:
 
 .. code-block:: none
@@ -63,7 +63,7 @@
   - (Mathematical) operators and symbols
   - ``\TEXT{...}``
 
-    To switch in a text-mode that prohibits automatic expression
+    Used to switch to a text-mode that prohibits automatic expression
     highlighting.
 
     A closing curly brace can be quoted with ``\}`` to not end the
@@ -79,15 +79,15 @@
 
   - :ref:`explicit-token-types`
 
-  In the `default`-mode it recognizes all sorts of single- and multi-line
-  comments in addition to expressions and commands that are inspired by
-  `Algpseudocodex`_.
+  The `default`-mode is an extension of `expression`:
+  in addition to `expressions` it recognizes all sorts of single- and
+  multi-line comments and commands that are inspired by `Algpseudocodex`_.
 
-  In `texts` it recognizes:
+  In `text` context it recognizes:
 
   - ``\EXPR`` or ``\EXPRESSION``
 
-    To switch to expression-mode.
+    Use to switch to expression-mode.
 
     A closing curly brace can be quoted with ``\}`` to not end the expression
     mode prematurely.
@@ -149,7 +149,9 @@
 Comments
 ========
 
-- with the ``\REMARK`` or ``\REM`` keywords (this includes a leading symbol)
+- with the ``\REMARK`` or ``\REM`` keywords
+  (until the end of the line; the output includes a leading symbol,
+  by default ``▷``)
 - 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)
@@ -184,12 +186,13 @@
 Literals
 ========
 
-Strings and numbers as in `Python`_. String prefixes ``r``, ``f`` and ``t``
-are not supported -- ``u`` and ``b`` are.
+Strings and numbers as in `Python`_.
+String prefixes ``u`` and ``b`` are supported---prefixes
+``r``, ``f`` and ``t`` are not supported.
 
-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`.
+To have non-string-delimiting single- and double-quotes in the output you
+have to escape them using ``\'`` or ``\"``.
+This must be used to typeset something as :algpseudocode:`f\\'(x) = 0`.
 
 .. code-block:: algpseudocode
 
@@ -254,7 +257,7 @@
 
 - Start with a backslash character ``\``
 - Case-insensitive
-- Yield mostly to :py:class:`pygments.Token.Keyword`
+- Yield mostly the :py:class:`pygments.token.Token.Keyword` token type
 - Translated if a translation is found
 - Depending on the command---may have required or optional parameters
 
@@ -376,8 +379,10 @@
 ''''''''''''
 
 The separator character can be empty, a run of ASCII spaces, a run of
-TAB characters, a single underscore ``_`` or a single hyphen ``-``
-like:
+TAB characters, a single underscore ``_`` or a single hyphen ``-``.
+
+All of the following examples are equally valid and result in the
+same output:
 
   ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF``
 
@@ -411,7 +416,7 @@
    \text{\END-FORALL}                          \END-FORALL
    \text{\END-LOOP}                            \END-LOOP
 
-.. note:: The output of END-commands can be suppressed by setting the
+.. note:: The output of these END-commands can be suppressed by setting the
           lexer option ``no_end`` to :py:obj:`True`.
 
 
@@ -445,8 +450,8 @@
 Explicit Token Types
 ====================
 
-Handle keywords and operators that are not handled by default or change
-the default handling of some expressions.
+They allow to handle keywords and operators that are not recognized by default.
+And they allow the user to explicitely highlight some input text at low-level.
 
 `XX` represents a `value` in the :py:data:`pygments.token.STANDARD_TYPES`
 dict.
@@ -481,8 +486,9 @@
 
    \text{• \\tt-kc/C}      \tt-kc/C            \rem C as Keyword.Constant
    \text{• \\tt-ow/∈}      \tt-ow/∈            \rem ∈ as Operator.Word
-   \text{• \\ttx-kc{A New Constant Keyword\}}    \ttx-kc{A New Constant Keyword}  \rem As a new Keyword.Constant
-   \text{• \\ttx-nv{A New Variable Name\}}       \ttx-nv{A New Variable Name}     \rem An explicit Name.Variable
+   \text{• \\ttx-kc{A Constant Keyword\}}    \ttx-kc{A Constant Keyword}  \rem An explicit Keyword.Constant
+   \text{• \\ttx-nv{A Variable Name\}}       \ttx-nv{A Variable Name}     \rem An explicit Name.Variable
+   \text{• \\ttx-ni{An Entity*Name\}}        \ttx-ni{An Entity*Name}      \rem An explicit Name.Entity
    \text{• \\ttx-k(∈ ∌)}   \ttx-k(∈ ∌)         \rem ∈ and ∌ as (ordinary) Keywords
    \text{• \\ttx-o<∈ ∌>}   \ttx-o<∈ ∌>         \rem ∈ and ∌ as (ordinary) Operators
      /*
@@ -503,6 +509,8 @@
 
 .. note:: Explicit token types are **case-sensitive**.
 
+.. note:: Explicit token types work in all `expression` and `text` contexts.
+
 
 .. _escaping-rules:
 
@@ -584,7 +592,9 @@
 Some Examples
 =============
 
-A synthetic example with many features.
+.. rubric:: Synthetic Example
+
+The first example is a synthetic example with many features.
 
 .. only:: builder_html
 
@@ -598,13 +608,15 @@
    :language: algpseudocode
    :lines: 2-
 
-With a customized `AlgPseudocodeLexer` and its `no_end`
-option set to :py:obj:`True`.
+The highlighted output with a customized `AlgPseudocodeLexer` and its `no_end`
+option set to :py:obj:`True`:
 
 .. literalinclude:: examples/example-1.pseudocode
    :language: NoEndAlgPseudocode
    :lines: 2-
 
+.. rubric:: Dinic's Algorithm
+
 The second example is Wikipedia's description of *Dinic's Algorithm*
 (see https://en.wikipedia.org/wiki/Dinic%27s_algorithm).
 
@@ -614,12 +626,14 @@
 
 .. raw:: latex
 
-   Its source code can be found at \url{algorithm-dinic.pseudocode}
+   Its source code can be found at \url{algorithm-dinic.pseudocode}.
 
 .. literalinclude:: examples/algorithm-dinic.pseudocode
    :language: algpseudocode
    :lines: 2-
 
+.. rubric:: Ford–Fulkerson Algorithm
+
 The third example is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
 (see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm).
 
@@ -636,6 +650,8 @@
    :language: algpseudocode
    :lines: 2-
 
+.. rubric:: Edmonds–Karp Algorithm
+
 The fourth example is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
 (see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
 with a custom lexer which skips all ``ENDxxx`` keywords.