--- 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)
      /*