--- a/docs/lexer-algpseudocode.rst	Mon May 11 01:31:12 2026 +0200
+++ b/docs/lexer-algpseudocode.rst	Mon May 11 10:39:39 2026 +0200
@@ -36,6 +36,10 @@
 
    \END PROGRAM {The Pseudoprogram}
 
+
+States
+======
+
 The AlgPseudocode lexer and its language variants AlgPseudocodeDE and
 AlgPseudocodeFR basically work in three states: `default`,
 `expression` and `text`.
@@ -80,60 +84,6 @@
   - :ref:`explicit-token-types`
 
 
-.. rubric:: Some Examples
-
-A synthetic example with many features:
-
-.. literalinclude:: examples/example-1.pseudocode
-   :language: algpseudocode
-   :lines: 2-
-
-With a customized `AlgPseudocodeLexer` and its `no_end`
-option set to ``True``.
-
-.. literalinclude:: examples/example-1.pseudocode
-   :language: NoEndAlgPseudocode
-   :lines: 2-
-
-This is Wikipedia's description of *Dinic's Algorithm*
-(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):
-
-.. literalinclude:: examples/algorithm-dinic.description
-   :language: algpseudocode
-   :lines: 2-
-
-This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
-(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):
-
-.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
-   :language: algpseudocode
-   :lines: 2-
-
-This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
-(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
-with a custom lexer that skip all ``ENDxxx`` keywords:
-
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-   :language: NoEndAlgPseudocode
-   :lines: 2-
-
-And now the *Edmonds–Karp Algorithm* with french keywords:
-
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-   :language: algpseudocode-fr
-   :lines: 2-
-
-And again the *Edmonds–Karp Algorithm* with german keywords:
-
-.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
-   :language: algpseudocode-de
-   :lines: 2-
-
-More details you will find :ref:`here <details-algpseudocode>`.
-
-
-.. _details-algpseudocode:
-
 Lexer Options
 =============
 
@@ -156,7 +106,7 @@
      **Default:** `False`
 
      If ``True`` all the ``\ENDxxx`` commands will be skipped and yield
-     nothing.
+     no output.
 
   .. describe:: gets
 
@@ -284,31 +234,32 @@
 They are not replaced by corresponding Unicode symbols.
 
 
-Keywords
+Commands
 ========
 
-Explicit Keywords
------------------
-
 - Start with a backslash character ``\``
 - Case-insensitive
+- Yield mostly to :py:class:`pygments.Token.Keyword`
 - Translated if a translation is found
+- Depending on the command---may have required or optional parameters
 
-Parameter handling is as follows:
+  Parameter handling is as follows:
 
-- Parameters are enclosed in curly braces ``{`` and ``}``
-- Escaping within the braces is possible using the backslash ``\``
-- Parameters are separated from the keyword/command by a (possibly empty) run
-  of space or TAB characters.
-  This is true for required and optional parameters.
+  * Parameters are enclosed in curly braces ``{`` and ``}``
+  * Escaping within the braces is possible using the backslash ``\`` as
+    escape character
+  * Parameters are separated from the keyword/command by a (possibly empty) run
+    of space or TAB characters.
+    This is true for required and optional parameters.
 
-.. todo:: Escaping
+    .. todo:: Escaping
 
-          A single backslash is a Generic.Error token
+              A single backslash yields a Generic.Error token when in
+              `default` and `expression` states.
 
 
-With Required Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~
+Commands With Required Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: algpseudocode
 
@@ -341,10 +292,10 @@
    \TEXT{\NAME{an entity name\}}                      \NAME{an entity name}
 
 
-With Optional Parameters
-~~~~~~~~~~~~~~~~~~~~~~~~
+Commands With Optional Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Some ``END``-keywords have optional parameters:
+Some ``END``-commands have optional parameters:
 
 .. code-block:: algpseudocode
 
@@ -360,13 +311,16 @@
 
    \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS {Foo Bar Class\}}   \TEXT{yields}   \CLASS{Foo Bar Class} ... \END CLASS {Foo Bar Class}
 
-.. seealso:: Syntax variants: `END-Keywords`_
+   \TEXT{\CLASS{Foo Bar Class\} ... \END CLASS}                   \TEXT{yields}   \CLASS{Foo Bar Class} ... \END CLASS
+
+.. seealso:: For other syntax variants concerning `END` see also section
+             `END-Commands`_.
 
 
-Without Parameters
-~~~~~~~~~~~~~~~~~~
+Commands Without Parameters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-"Normal" Keywords
+"Normal" Commands
 '''''''''''''''''
 
 .. code-block:: algpseudocode
@@ -404,11 +358,12 @@
 they are interpreted to be part of the comment.
 
 
-END-Keywords
+END-Commands
 ''''''''''''
 
-The separator character can be empty, a run of ASCII spaces, a run of TAB characters,
-a single underscore ``_`` or a single hyphen ``-`` like:
+The separator character can be empty, a run of ASCII spaces, a run of
+TAB characters, a single underscore ``_`` or a single hyphen ``-``
+like:
 
   ``\ENDIF``, ``\END IF``, ``\END-IF``, ``\END_IF`` or ``\END IF``
 
@@ -427,7 +382,7 @@
 
    \text{\END   IF}          \END       IF     \rem a single TAB character
 
-The list of END-keywords (here always just with ``-`` as separator):
+The list of END-commands (here always just with ``-`` as separator):
 
 .. code-block:: algpseudocode
 
@@ -442,6 +397,9 @@
    \text{\END-FORALL}                          \END-FORALL
    \text{\END-LOOP}                            \END-LOOP
 
+.. note:: The output of END-commands can be suppressed by setting the
+          lexer option ``no_end`` to ``True``.
+
 
 Names and Entities
 ==================
@@ -467,6 +425,7 @@
 
    \TEXT{Genève}                 Genève
 
+
 .. _explicit-token-types:
 
 Explicit Token Types
@@ -575,3 +534,54 @@
           Sphinx and are not augmented with any default filters.
 
 For older Sphinx versions your mileage may vary.
+
+
+Some Examples
+=============
+
+A synthetic example with many features:
+
+.. literalinclude:: examples/example-1.pseudocode
+   :language: algpseudocode
+   :lines: 2-
+
+With a customized `AlgPseudocodeLexer` and its `no_end`
+option set to ``True``.
+
+.. literalinclude:: examples/example-1.pseudocode
+   :language: NoEndAlgPseudocode
+   :lines: 2-
+
+This is Wikipedia's description of *Dinic's Algorithm*
+(see https://en.wikipedia.org/wiki/Dinic%27s_algorithm):
+
+.. literalinclude:: examples/algorithm-dinic.description
+   :language: algpseudocode
+   :lines: 2-
+
+This is Wikipedia's pseudocode of the *Ford–Fulkerson Algorithm*
+(see https://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm):
+
+.. literalinclude:: examples/algorithm-ford-fulkerson.pseudocode
+   :language: algpseudocode
+   :lines: 2-
+
+This is Wikipedia's pseudocode of the *Edmonds–Karp Algorithm*
+(see https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm)
+with a custom lexer that skip all ``ENDxxx`` keywords:
+
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+   :language: NoEndAlgPseudocode
+   :lines: 2-
+
+And now the *Edmonds–Karp Algorithm* with french keywords:
+
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+   :language: algpseudocode-fr
+   :lines: 2-
+
+And again the *Edmonds–Karp Algorithm* with german keywords:
+
+.. literalinclude:: examples/algorithm-edmonds-karp.pseudocode
+   :language: algpseudocode-de
+   :lines: 2-