Index: en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -1144,7 +1144,15 @@
     <para>A lot of software uses incorrect locations for script
       interpreters, most notably <filename>/usr/bin/perl</filename>
       and <filename>/bin/bash</filename>.  This fixes shebang lines in
-      scripts listed in <varname>SHEBANG_FILES</varname>.  Currently
+      scripts listed in <varname>SHEBANG_FILES</varname>.  It is run
+      from <literal>${WRKSRC}</literal>, so it can contain paths that
+      are relative to it, but it can contain absolute path if files
+      outside of WRKSRC need patching.  For example:</para>
+
+    <programlisting>USES=	shebangfix
+SHEBANG_FILES=	scripts/foobar.pl scripts/*.sh</programlisting>
+
+    <para>Currently
       <application>Bash</application>,
       <application>Java</application>, <application>Ksh</application>,
       <application>Lua</application>,
@@ -1154,16 +1162,17 @@
       and <application>Tk</application> are supported by default.  To
       support another interpreter, set
       <varname>SHEBANG_LANG</varname>,
-      <varname><replaceable>foo</replaceable>_OLD_CMD</varname> and
-      <varname><replaceable>foo</replaceable>_CMD</varname>.  For
+      <varname><replaceable>interp</replaceable>_OLD_CMD</varname> and
+      <varname><replaceable>interp</replaceable>_CMD</varname>.  For
       example:</para>
 
     <programlisting>SHEBANG_LANG=	lua
 lua_OLD_CMD=	/usr/bin/lua
 lua_CMD=	${LOCALBASE}/bin/lua</programlisting>
 
-    <para>As <literal><replaceable>foo</replaceable>_OLD_CMD</literal>
-      can contain multiple values, if an entry contains a space, it
+    <para>As
+      <literal><replaceable>interp</replaceable>_OLD_CMD</literal>
+      will contain multiple values, if an entry contains a space, it
       needs to be quoted.  For example, if it was not already defined,
       the <application>Ksh</application> entry could be defined
       as:</para>
@@ -1171,6 +1180,24 @@
     <programlisting>SHEBANG_LANG=	ksh
 ksh_OLD_CMD=	"/usr/bin/env ksh" /bin/ksh /usr/bin/ksh
 ksh_CMD=	${LOCALBASE}/bin/ksh</programlisting>
+
+    <para>If some software has a strange location for an interpreter,
+      for example, its <application>Python</application> is located in
+      <filename>/opt/bin/python2.7</filename>, add to the port
+      <filename>Makefile</filename>:</para>
+
+    <programlisting>python_OLD_CMD=	/opt/bin/python2.7</programlisting>
+
+    <note>
+      <para>The fixing of shebangs is done during the
+	<buildtarget>patch</buildtarget> phase.  If some scripts are
+	generated during the <buildtarget>build</buildtarget> phase,
+	and their resulting shebangs are wrong, the build process
+	should be patched to generate the right shebangs.  All the
+	<emphasis>correct</emphasis> paths for supported interpreters
+	are available in
+	<literal><replaceable>interp</replaceable>_CMD</literal>.</para>
+    </note>
   </sect1>
 
   <sect1 xml:id="uses-tar">