--- a/docs/filters.rst	Fri May 22 23:46:11 2026 +0200
+++ b/docs/filters.rst	Sat May 23 11:43:21 2026 +0200
@@ -22,31 +22,33 @@
 
    }
 
-The "normal" AlgPseudocode lexer yields an error token for the code block
-below;
-`Sphinx`_ warns about this and---as a consequence---suppresses highlighting
-for this code block completely:
+The :ref:`AlgPseudocode lexer <lexer-algpseudocode>` by default yields an
+error token for the code block below because it encounters an unknown command.
+When used within `Sphinx`_ it warns about this
+and---as a consequence---suppresses highlighting for this code block
+completely (see also :ref:`this note <note-raiseonerror-filter>`):
 
 .. code-block:: none
 
    \nonexisting{TEST}
 
-With a custom AlgPseudocode lexer that has ``prohibit_raiseonerror_filter``
-activated the output in `Sphinx`_ is as:
+This may be changed by using a custom AlgPseudocode lexer that has
+the ``prohibit_raiseonerror_filter`` lexer option enabled.
+Then the the output in `Sphinx`_ is as follows:
 
 .. code-block:: no-raiseonerror-algpseudocode
 
    \nonexisting{TEST}
 
 
-With the "errortogenericerror" filter the very same block is highlighted
-as:
+Alternatively---with the "errortogenericerror" filter applied the very same
+block is highlighted as:
 
 .. code-block:: genericerror-algpseudocode
 
    \nonexisting{TEST}
 
-The above custom lexer has been defined for `Sphinx`_ using:
+The above custom lexer is to be defined in `Sphinx`_ using:
 
 .. code-block:: python
 
@@ -61,7 +63,7 @@
                AlgPseudocodeLexer,
                filters=[ErrorToGenericErrorTokenFilter]))
 
-               
+
 .. _tokenreplacefilter:
 
 TokenReplaceFilter
@@ -96,6 +98,10 @@
 
 The values in the token stream are retained.
 
+All :py:class:`str` types in any of the filter options are converted to
+real tokens using `Pygments`_  function
+:py:func:`pygments.token.string_to_tokentype`.
+
 
 ErrorToGenericErrorTokenFilter
 ==============================

--- a/docs/lexer-algpseudocode.rst	Fri May 22 23:46:11 2026 +0200
+++ b/docs/lexer-algpseudocode.rst	Sat May 23 11:43:21 2026 +0200
@@ -1,5 +1,6 @@
 .. -*- coding: utf-8; indent-tabs-mode: nil; -*-
 
+.. _lexer-algpseudocode:   
 
 *************************************
  AlgPseudocode and Language Variants
@@ -634,7 +635,7 @@
        app.add_lexer("noend-algpseudocode",
                      partial(AlgPseudocodeLexer, no_end=True))
 
-Similarily it works for custom styles and filters.
+.. _note-raiseonerror-filter:                     
 
 .. note:: Lexers in Sphinx are instantiated with the `raiseonerror` filter
           applied by default.
@@ -649,7 +650,7 @@
           :py:data:`sphinx.highlighting.lexers` somehow are taken as is by
           Sphinx and are not augmented with any default filters.
 
-          For more details see chapter :ref:`filters`.
+          See also chapter :ref:`filters`.
 
 For older Sphinx versions your mileage may vary.