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