diff --git a/reference/cpdf/reference.xml b/reference/cpdf/reference.xml
index 8221e4135f..3cd3dfd1da 100644
--- a/reference/cpdf/reference.xml
+++ b/reference/cpdf/reference.xml
@@ -1,15 +1,24 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.17 $ -->
+<!-- $Revision: 1.18 $ -->
 <!-- Purpose: utilspec.nontext -->
 <!-- Membership: pecl, external -->
+<!-- State: deprecated -->
 
  <reference xml:id="ref.cpdf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
-  <title>ClibPDF Functions</title>
+  <title>ClibPDF Functions [deprecated]</title>
   <titleabbrev>ClibPDF</titleabbrev>
 
   <partintro>
    <section xml:id="cpdf.intro">
     &reftitle.intro;
+    <warning>
+     <para>
+      ClibPDF support is deprecated and users are strongly encouraged to use
+      an alternative, like <link linkend="ref.haru">Haru</link>,
+      <link linkend="ref.pdf">PDFlib</link>, or one of the available
+      <link linkend="faq.using.freepdf">PHP alternatives.</link>
+     </para>
+    </warning>
     <para>
      ClibPDF lets you create PDF documents with PHP. ClibPDF functionality
      and API are similar to <link linkend="ref.pdf">PDFlib</link>.