Index: head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
+++ head/en_US.ISO8859-1/books/porters-handbook/plist/chapter.xml
@@ -382,6 +382,18 @@
 
     <programlisting>@sample(,games,660) etc/config.sample</programlisting>
 
+    <warning>
+      <para>If a keyword is used on an <link
+	  linkend="makefile-options">optional</link> entry, it must to
+	be added after the helper:</para>
+
+      <programlisting>%%FOO%%@sample etc/orbit.conf.sample</programlisting>
+
+      <para>This is because the options plist helpers are used to
+	comment out the line, so they need to be put first.  See <xref
+	  linkend="options_sub"/> for more information.</para>
+    </warning>
+
     <!--
     Keywords up-to-date with r381632.
     Try and keep the keywords alphanumerically sorted.