diff --git a/reference/xdiff/book.xml b/reference/xdiff/book.xml
index 36702399bc..0b0d665646 100644
--- a/reference/xdiff/book.xml
+++ b/reference/xdiff/book.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Purpose: basic.text -->
 <!-- Membership: pecl, external -->
  
@@ -10,7 +10,19 @@
  <preface xml:id="intro.xdiff">
   &reftitle.intro;
   <para>
-   xdiff extension creates and applies patches to both text and binary files.
+   xdiff extension enables you to create and apply patch files containing
+   differences between different revisions of files.
+  </para>
+  <para>
+   This extension supports two modes of operation - on strings and on files, as well
+   as two different patch formats - unified and binary. Unified patches are excellent
+   for text files as they are human-readable and easy to review. For binary files like
+   archives or images, binary patches will be adequate choice as they are binary safe and
+   handle non-printable characters well.
+  </para>
+  <para>
+   This extension uses libxdiff to implement these functions. Please see
+   <link xlink:href="&url.xdiff;">&url.xdiff;</link> for more informations.
   </para>
  </preface>
  <!-- }}} -->
diff --git a/reference/xdiff/constants.xml b/reference/xdiff/constants.xml
index 63016dc725..3bc7d6c38e 100644
--- a/reference/xdiff/constants.xml
+++ b/reference/xdiff/constants.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <appendix xml:id="xdiff.constants" xmlns="http://docbook.org/ns/docbook">
  &reftitle.constants;
  &extension.constants;
@@ -11,7 +11,9 @@
    </term>
    <listitem>
     <simpara>
-     
+     This flag indicates that xdiff_[string|file]_patch functions should create result by
+     applying patch to original content thus creating newer version of file. This is the default
+     mode of operation.
     </simpara>
    </listitem>
   </varlistentry>
@@ -22,7 +24,8 @@
    </term>
    <listitem>
     <simpara>
-     
+     This flag indicated that xdiff_[string|file]_patch functions should create result by
+     reversing patch changed from newer content thus creating original version.
     </simpara>
    </listitem>
   </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-file-diff-binary.xml b/reference/xdiff/functions/xdiff-file-diff-binary.xml
index ef834c0476..676e78433f 100644
--- a/reference/xdiff/functions/xdiff-file-diff-binary.xml
+++ b/reference/xdiff/functions/xdiff-file-diff-binary.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-file-diff-binary" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -29,6 +29,7 @@
      <term><parameter>file1</parameter></term>
      <listitem>
       <para>
+       Path to the first file.
       </para>
      </listitem>
     </varlistentry>
@@ -36,6 +37,7 @@
      <term><parameter>file2</parameter></term>
      <listitem>
       <para>
+       Path to the second file.
       </para>
      </listitem>
     </varlistentry>
@@ -43,7 +45,7 @@
      <term><parameter>dest</parameter></term>
      <listitem>
       <para>
-       Path of the resulting file. Resulting file is in binary format.
+       Path of the resulting file. Resulting file is in binary format and is human-unreadable.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-file-diff.xml b/reference/xdiff/functions/xdiff-file-diff.xml
index 93b2efb25f..e7f94831d5 100644
--- a/reference/xdiff/functions/xdiff-file-diff.xml
+++ b/reference/xdiff/functions/xdiff-file-diff.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-file-diff" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -18,7 +18,7 @@
    <methodparam choice="opt"><type>bool</type><parameter>minimal</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Makes a diff of two files and stores the result in a file.
+   Makes a diff of two files and stores the result in a file. Resulting file is human-readable.
   </para>
  </refsect1>
 
@@ -30,6 +30,7 @@
      <term><parameter>file1</parameter></term>
      <listitem>
       <para>
+       Path to the first file.
       </para>
      </listitem>
     </varlistentry>
@@ -37,6 +38,7 @@
      <term><parameter>file2</parameter></term>
      <listitem>
       <para>
+       Path to the second file.
       </para>
      </listitem>
     </varlistentry>
@@ -61,8 +63,8 @@
      <term><parameter>minimal</parameter></term>
      <listitem>
       <para>
-       Set this parameter to &true; if you want to minimalize size of diff
-       (can take a long time). Resulting file is human-readable.
+       Set this parameter to &true; if you want to minimalize size of the result
+       (can take a long time). 
       </para>
      </listitem>
     </varlistentry>
@@ -104,7 +106,7 @@ xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
   <note>
    <para>
     This function doesn't work well with binary files. To make diff of binary
-    files use <function>xdiff_file_diff_binary</function>.
+    files use <function>xdiff_file_diff_binary</function> function.
    </para>
   </note>
  </refsect1>
diff --git a/reference/xdiff/functions/xdiff-file-merge3.xml b/reference/xdiff/functions/xdiff-file-merge3.xml
index 798680bddf..7967e3abd9 100644
--- a/reference/xdiff/functions/xdiff-file-merge3.xml
+++ b/reference/xdiff/functions/xdiff-file-merge3.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-file-merge3" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -29,6 +29,7 @@
      <term><parameter>file1</parameter></term>
      <listitem>
       <para>
+       Path to the first file.
       </para>
      </listitem>
     </varlistentry>
@@ -36,6 +37,7 @@
      <term><parameter>file2</parameter></term>
      <listitem>
       <para>
+       Path to the second file.
       </para>
      </listitem>
     </varlistentry>
@@ -43,6 +45,7 @@
      <term><parameter>file3</parameter></term>
      <listitem>
       <para>
+       Path to the third file.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-file-patch-binary.xml b/reference/xdiff/functions/xdiff-file-patch-binary.xml
index 0c7b39faf6..aa00a735d7 100644
--- a/reference/xdiff/functions/xdiff-file-patch-binary.xml
+++ b/reference/xdiff/functions/xdiff-file-patch-binary.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-file-patch-binary" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -37,7 +37,8 @@
      <term><parameter>patch</parameter></term>
      <listitem>
       <para>
-       The binary patch file.
+       The binary patch file. It has to be created using <function>xdiff_file_diff_binary</function> or 
+       <function>xdiff_string_diff_binary</function> function.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-file-patch.xml b/reference/xdiff/functions/xdiff-file-patch.xml
index ba7807e5e3..eb869602b6 100644
--- a/reference/xdiff/functions/xdiff-file-patch.xml
+++ b/reference/xdiff/functions/xdiff-file-patch.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-file-patch" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -38,7 +38,8 @@
      <term><parameter>patch</parameter></term>
      <listitem>
       <para>
-       The patch file.
+       The patch file. It has to be created using <function>xdiff_string_diff</function>, 
+       <function>xdiff_file_diff</function> functions or compatible tools.
       </para>
      </listitem>
     </varlistentry>
@@ -68,7 +69,7 @@
   &reftitle.returnvalues;
   <para>
    Returns &false; if an internal error happened, string with rejected
-   chunks of patch or &true; if patch has been successfully applied.
+   chunks if patch couldn't be applied or &true; if patch has been successfully applied.
   </para>
  </refsect1>
 
diff --git a/reference/xdiff/functions/xdiff-string-diff-binary.xml b/reference/xdiff/functions/xdiff-string-diff-binary.xml
index 2bae9dc0a0..6cad47f717 100644
--- a/reference/xdiff/functions/xdiff-string-diff-binary.xml
+++ b/reference/xdiff/functions/xdiff-string-diff-binary.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-string-diff-binary" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -27,6 +27,7 @@
      <term><parameter>str1</parameter></term>
      <listitem>
       <para>
+       First string with binary data.
       </para>
      </listitem>
     </varlistentry>
@@ -34,6 +35,7 @@
      <term><parameter>str2</parameter></term>
      <listitem>
       <para>
+       Second string with binary data.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-string-diff.xml b/reference/xdiff/functions/xdiff-string-diff.xml
index 15314475eb..4ebbfe7e9f 100644
--- a/reference/xdiff/functions/xdiff-string-diff.xml
+++ b/reference/xdiff/functions/xdiff-string-diff.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-string-diff" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -29,6 +29,7 @@
      <term><parameter>str1</parameter></term>
      <listitem>
       <para>
+       First string with data.
       </para>
      </listitem>
     </varlistentry>
@@ -36,6 +37,7 @@
      <term><parameter>str2</parameter></term>
      <listitem>
       <para>
+       Second string with data.
       </para>
      </listitem>
     </varlistentry>
@@ -53,7 +55,7 @@
      <listitem>
       <para>
        Set this parameter to &true; if you want to minimalize the size of the
-       diff (can take a long time).
+       result (can take a long time).
       </para>
      </listitem>
     </varlistentry>
@@ -64,7 +66,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns string with result or &false; if an internal error happened.
+   Returns string with resulting diff or &false; if an internal error happened.
   </para>
  </refsect1>
 
diff --git a/reference/xdiff/functions/xdiff-string-merge3.xml b/reference/xdiff/functions/xdiff-string-merge3.xml
index 3103a17059..234c5b940e 100644
--- a/reference/xdiff/functions/xdiff-string-merge3.xml
+++ b/reference/xdiff/functions/xdiff-string-merge3.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-string-merge3" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -29,6 +29,7 @@
      <term><parameter>str1</parameter></term>
      <listitem>
       <para>
+       First string with data.
       </para>
      </listitem>
     </varlistentry>
@@ -36,6 +37,7 @@
      <term><parameter>str2</parameter></term>
      <listitem>
       <para>
+       Second string with data.
       </para>
      </listitem>
     </varlistentry>
@@ -43,6 +45,7 @@
      <term><parameter>str3</parameter></term>
      <listitem>
       <para>
+       Third string with data.
       </para>
      </listitem>
     </varlistentry>
diff --git a/reference/xdiff/functions/xdiff-string-patch.xml b/reference/xdiff/functions/xdiff-string-patch.xml
index 1433775a30..c62239258f 100644
--- a/reference/xdiff/functions/xdiff-string-patch.xml
+++ b/reference/xdiff/functions/xdiff-string-patch.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 <!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
 <refentry xml:id="function.xdiff-string-patch" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -17,7 +17,7 @@
    <methodparam choice="opt"><type>string</type><parameter role="reference">error</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Patches a string with a unified <parameter>patch</parameter> string.
+   Patches a string with a unified patch from <parameter>patch</parameter> parameter.
   </para>
  </refsect1>
 
@@ -37,7 +37,8 @@
      <term><parameter>patch</parameter></term>
      <listitem>
       <para>
-       The unified patch string.
+       The unified patch string. It has to be created using <function>xdiff_string_diff</function>, 
+       <function>xdiff_file_diff</function> functions or compatible tools.
       </para>
      </listitem>
     </varlistentry>