diff --git a/docs/usermanual-buffers-language-script-and-direction.xml b/docs/usermanual-buffers-language-script-and-direction.xml
index d98c79b7f..0235d2d39 100644
--- a/docs/usermanual-buffers-language-script-and-direction.xml
+++ b/docs/usermanual-buffers-language-script-and-direction.xml
@@ -136,10 +136,12 @@
       determine which glyph to return.
     </para>
     <para>
-      The safest approach is to add all of the text available, then
-      use <parameter>item_offset</parameter> and
+      The safest approach is to add all of the text available (even
+      if your text contains a mix of scripts, directions, languages
+      and fonts), then use <parameter>item_offset</parameter> and
       <parameter>item_length</parameter> to indicate which characters you
-      want shaped, so that HarfBuzz has access to any context.
+      want shaped (which must all have the same script, direction,
+      language and font), so that HarfBuzz has access to any context.
     </para>
     <para>
       You can also add Unicode code points directly with