diff --git a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
index f938b8d93b..617b08c7a9 100644
--- a/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ b/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -1143,8 +1143,19 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
 
     <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
+      and <filename>/bin/bash</filename>.  The shebagngfix macro fixes
+      shebang lines in scripts listed in
+      <varname>SHEBANG_FILES</varname>.  The shebangfix macro is run
+      from <literal>${WRKSRC}</literal>, so it can contain paths that
+      are relative to <literal>${WRKSRC}</literal>.  It can also deal
+      with absolute paths if files outside of
+      <literal>${WRKSRC}</literal> require 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,23 +1165,43 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi</programlisting>
       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
-      needs to be quoted.  For example, if it was not already defined,
-      the <application>Ksh</application> entry could be defined
-      as:</para>
+    <para><literal><replaceable>interp</replaceable>_OLD_CMD</literal>
+      will contain multiple values.  Any entry with spaces must be
+      quoted.  For example, if it was not already defined, the
+      <application>Ksh</application> entry could be defined as:</para>
 
     <programlisting>SHEBANG_LANG=	ksh
 ksh_OLD_CMD=	"/usr/bin/env ksh" /bin/ksh /usr/bin/ksh
 ksh_CMD=	${LOCALBASE}/bin/ksh</programlisting>
+
+    <para>Some software uses strange locations for an interpreter.
+      For example, an application might expect
+      <application>Python</application> to be located in
+      <filename>/opt/bin/python2.7</filename>.  The strange path to be
+      replaced can be declared in 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 scripts are
+	created with incorrect shebangs during the
+	<buildtarget>build</buildtarget> phase, the build process (for
+	examples, the <filename>configure</filename> script, or the
+	<filename>Makefiles</filename>) must be patched to generate
+	the right shebangs.  Correct paths for supported interpreters
+	are available in
+	<literal><replaceable>interp</replaceable>_CMD</literal>.</para>
+    </note>
   </sect1>
 
   <sect1 xml:id="uses-tar">