diff --git a/src/doc/doc/about/expressions.xml b/src/doc/doc/about/expressions.xml
index 939f07040..f7e405c48 100644
--- a/src/doc/doc/about/expressions.xml
+++ b/src/doc/doc/about/expressions.xml
@@ -4,9 +4,11 @@
 <doc>
 
   <title>About Expressions</title>
+  <keyword>Expressions</keyword>
+  <keyword>Expression Syntax</keyword>
 
   <p>
-  Beside a ruby programming API, KLayout provides support for simple expressions in some places.
+  Beside a ruby and Python programming API, KLayout provides support for simple expressions in some places.
   In particular this feature is employed to generate dynamic strings, for example when deriving the
   label text for a ruler.
   </p>
@@ -161,17 +163,14 @@ Box.new(-10, 0, 90, 60).width
   mentioned in the class documentation. Setter methods like "box_with=" can be used as targets in assignments, i.e.
   </p>
 
-  <pre>
-shape.box_width = 20
-</pre>
+  <pre>shape.box_width = 20</pre>
 
-  <p>Boolean predicates (like "is_box?") are used <b>without</b> the question mark because that is reserved
+  <p>
+  Boolean predicates (like "is_box?") are used <b>without</b> the question mark because that is reserved
   for the decision operator (".. ? .. : .."):
   </p>
 
-  <pre>
-shape.is_box
-</pre>
+  <pre>shape.is_box</pre>
 
   <h2>Concatenation of expressions</h2>
 
@@ -179,6 +178,24 @@ shape.is_box
   The semicolon separates two expressions. The value of that compound expression is the value of the last one.
   </p>
 
+  <h2>Keyword arguments</h2>
+
+  <p>
+  Most methods support keyword arguments similar to Python. For example you can write:
+  </p>
+
+  <pre>CplxTrans.new(rot = 45.0)</pre>
+
+  <p>
+  This is more explicit than writing the individual arguments and allows giving
+  one argument without having to insert the default values for the previous ones.
+  </p>
+
+  <p>
+  Keyword arguments are not supported for the built-in functions such as "sqrt" and
+  a few built-in methods.
+  </p>
+
   <h2>Variables</h2>
 
   <p>
diff --git a/src/doc/doc/programming/python.xml b/src/doc/doc/programming/python.xml
index 6eb8449d6..9389c848b 100644
--- a/src/doc/doc/programming/python.xml
+++ b/src/doc/doc/programming/python.xml
@@ -217,6 +217,21 @@ for edge in edges:
 </pre>
     </li>
 
+    <li><b>Keyword arguments:</b>
+
+    <p>Most methods support keyword arguments, for example:</p>
+
+    <pre># a 45 degree rotation
+t = pya.CplxTrans(rot = 45)</pre>
+
+    <p>
+    Exceptions are some built-in methods like "assign". Keyword arguments can be used
+    when the non-optional arguments are specified either as positional or other keyword
+    arguments.
+    </p>
+
+    </li>
+
     <li><b>Standard protocols:</b>
 
     <p>"x.to_s()" is available as "str(x)" too.</p>
diff --git a/src/doc/doc/programming/ruby_binding.xml b/src/doc/doc/programming/ruby_binding.xml
index 655f395de..8a6cb782c 100644
--- a/src/doc/doc/programming/ruby_binding.xml
+++ b/src/doc/doc/programming/ruby_binding.xml
@@ -408,6 +408,22 @@ A::new.f(x)
   omitted, the default value is used instead.
   </p>
 
+  <h3>Keyword arguments</h3>
+
+  <p>
+  Starting with version 3, Ruby supports "real" keyword arguments.
+  Keyword arguments are supported for most methods with the exception of a few built-in ones such as "assign".
+  Keyword arguments can be used when the other, non-optional arguments are given either by
+  positional arguments or other keyword arguments.
+  </p>
+
+  <p>
+  Keyword arguments are somewhat more expressive and allow a shorter notation. For example,
+  to instantiate a 45 degree rotation, you can write:
+  </p>
+
+  <pre>t = RBA::CplxTrans::new(rot: 45)</pre>
+
   <h2>Implicit conversions</h2>
 
   <h3>String arguments</h3>