diff --git a/reference/yaz/configure.xml b/reference/yaz/configure.xml
index 4ae713a34f..d8279bcd7b 100644
--- a/reference/yaz/configure.xml
+++ b/reference/yaz/configure.xml
@@ -1,32 +1,79 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.9 $ -->
+<!-- $Revision: 1.10 $ -->
 <section id="yaz.installation">
  &reftitle.install;
  <para>
-  Compile YAZ (ANSI/NISO Z39.50 support) and install it.
-  Build PHP with your favourite modules and add option 
-  <option role="configure">--with-yaz[=DIR]</option>.
-  Your task is roughly the following:
+  Obtain YAZ (ANSI/NISO Z39.50 support) and install it. 
+  YAZ can be fetched in source or in various prebuilt packages
+  from the <ulink url="&url.yaz.ftp;">YAZ archive</ulink>.
+  Systems such as Debian GNU/Linux, Suse Linux, FreeBSD also has YAZ
+  as part of their distribution.
  </para>
  <para>
-  <example>
-   <title>YAZ compilation</title>
-   <programlisting role="shell">
-<![CDATA[
-gunzip -c php-4.3.X.tar.gz|tar xf -
-gunzip -c yaz-2.0.tar.gz|tar xf -
-cd yaz-2.0
+  For the PHP4 series, the YAZ extension is bundled (but not YAZ itself)
+  Build PHP with your favorite modules and add option 
+  <option role="configure">--with-yaz[=DIR]</option>.
+ </para>
+ <example>
+  <title>YAZ compilation for PHP4 on Unix</title>
+  <programlisting role="shell">
+   <![CDATA[
+gunzip -c php-4.4.X.tar.gz|tar xf -
+gunzip -c yaz-2.1.8.tar.gz|tar xf -
+cd yaz-2.1.8
 ./configure --prefix=/usr
 make
-make install
-cd ../php-4.3.X.
+sudo make install
+cd ../php-4.4.X.
 ./configure --with-yaz=/usr/bin
 make
-make install
+sudo make install
 ]]>
-   </programlisting>
-  </example>
+  </programlisting>
+ </example>
+ <para>
+  For PHP5, the YAZ extension is in <ulink url="&url.pecl;">PECL</ulink>
+  and is installed as a shared object/dll.
+  If you have pear installed the easiest way to download, configure and
+  install the YAZ extension is by using the <command>pear</command> command.
  </para>
+ <example>
+  <title>Installation of PECL YAZ on GNU/Debian Linux</title>
+  <para>
+  </para>
+  <para>On a Debian GNU/Linux system the following installs YAZ and PECL YAZ:
+   command usually suffice:
+  </para>
+  <programlisting role="shell">
+    <![CDATA[
+sudo apt-get install libyaz-dev
+sudo pear install yaz
+]]>
+  </programlisting>
+ </example>
+ <para>
+  On Windows, <filename>php_yaz.dll</filename> depend on
+  <filename>yaz.dll</filename>. The <filename>yaz.dll</filename>
+  is part of the Win32 ZIP from the PHP site. It is also part 
+  of the Windows YAZ install available from the
+  <ulink url="&url.yaz.ftp.win32;">YAZ WIN32 area</ulink>.
+ </para>
+ <warning>
+  <para>
+   The PHP 5.0.5 Win32 zip includes a too old version of
+   <filename>yaz.dll</filename> (version 1.9.1 < required version 2.0.13).
+   If that's the case use the <filename>yaz.dll</filename> from a newer
+   <ulink url="&url.yaz.ftp.win32;">YAZ WIN32 install</ulink>.
+  </para>
+ </warning>
+
+ <para>
+  On windows, copy <filename>yaz.dll</filename> to a directory in your 
+  <varname>PATH</varname> environment
+  (<filename class="directory">c:\winnt\system32</filename> or
+  <filename class="directory">c:\windows\system32</filename>).
+ </para>
+
  <para>
   If you are using YAZ as a shared extension, add (or uncomment) the following
   line in &php.ini; on Unix:
@@ -38,15 +85,6 @@ make install
    extension=php_yaz.dll
   </screen>
  </para>
- <para>
-  On Windows, <filename>php_yaz.dll</filename> depend on
-  <filename>yaz.dll</filename>. You'll find <filename>yaz.dll</filename>
-  in sub directory <filename>dlls</filename> in the Win32 zip archive.
-  Copy <filename>yaz.dll</filename> to a directory in your 
-  <varname>PATH</varname> environment
-  (<filename class="directory">c:\winnt\system32</filename> or
-  <filename class="directory">c:\windows\system32</filename>).
- </para>
 
  &warn.imaprecodeyaz;