Document the three-arg form of foreach

refdoc/chapters/control_structures.xml

@@ -281,6 +281,27 @@ for ( tmp2 = 0; tmp2 < sizeof(tmp1); tmp2++ )
 }
 </example>
 
+<p><tt>Foreach</tt> can also iterate over a mapping, providing both the key and the
+value at the same time:</p>
+
+<example>
+foreach ( mapping_expression; variable1; variable2 )
+  statement;
+</example>
+
+<p>This is approximately equivalent to:</p>
+
+<example>
+mapping tmp1 = mapping_expression;
+array tmp2 = indices(tmp1);
+for ( tmp3 = 0; tmp3 &lt; sizeof(tmp2); tmp3++ )
+{
+  variable1 = tmp2 [ tmp3 ];
+  variable2 = tmp1 [ variable1 ];
+  statement;
+}
+</example>
+
 </subsection>
 </section>