svn: /pear/peardoc/trunk/en/package/networking/net-ldap2/ filter.xml ldif.xml

--6a10ce3280ab2c613349111f195ebdc3796f69e7
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit

beni                                     Mon, 09 Dec 2013 10:56:58 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=332317

Log:
* Some doc enhancements considering LDIF filtering

Changed paths:
    U   pear/peardoc/trunk/en/package/networking/net-ldap2/filter.xml
    U   pear/peardoc/trunk/en/package/networking/net-ldap2/ldif.xml

Modified: pear/peardoc/trunk/en/package/networking/net-ldap2/filter.xml
===================================================================
--- pear/peardoc/trunk/en/package/networking/net-ldap2/filter.xml	2013-12-09 10:53:33 UTC (rev 332316)
+++ pear/peardoc/trunk/en/package/networking/net-ldap2/filter.xml	2013-12-09 10:56:58 UTC (rev 332317)
@@ -5,7 +5,7 @@
         <refpurpose>Introduction to and usage of LDAP filters</refpurpose>
     </refnamediv>
     <refsection><info><title>What are LDAP filters?</title></info>
-
+        <para>LDAP filters usually serve as parameter to a <link linkend="package.networking.net-ldap2.search">LDAP Search request</link>.</para>
         <para>
             LDAP filters are defined in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.ietf.org/rfc/rfc2254.txt">RFC 2254</link>
             and can be compared to the WHERE clause in SQL select statements - they filter
@@ -14,7 +14,6 @@
             the <classname>Net_LDAP2_Filter</classname> class which mostly releases you of the burden to escape yourself and
             to remember all the various special characters needed for constructing and combining filters.
         </para>
-        <para>Where and how to use filters is described in chapter <link linkend="package.networking.net-ldap2.search">Search</link>.</para>
     </refsection>

     <refsection><info><title>Some LDIF filter basics</title></info>

Modified: pear/peardoc/trunk/en/package/networking/net-ldap2/ldif.xml
===================================================================
--- pear/peardoc/trunk/en/package/networking/net-ldap2/ldif.xml	2013-12-09 10:53:33 UTC (rev 332316)
+++ pear/peardoc/trunk/en/package/networking/net-ldap2/ldif.xml	2013-12-09 10:56:58 UTC (rev 332317)
@@ -14,10 +14,18 @@

         <para>
             LDIF files are in detail described at <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.ietf.org/rfc/rfc2849.txt">RFC 2849</link>.
-            Shortly, they contain directory data in an plain text, human readable format, much like
-            a SQL file does. However, unlike an SQL dump, LDIF files are mostly data based, not action based.
-            There are two different possible LDIF file contents which can be mixed freely: content and change format.
-            The first and most often used one is the LDIF content format:
+            Shortly, they contain data records in an plain text, human readable format, much like
+            a SQL file does. An LDIF file specifies a set of directory entries, or a set of changes to
+            be applied to directory entries, but not both at the same time: the formats cannot be mixed
+            inside the same file.
+
+            LDIF-content files are very usable for manual transporting data or for full backups.
+            LDIF-change files are an easy way to perform adjustments to a database like automated
+            data synchonisation.
+
+            LDIF files can contain comments (first character on line is a hash "#") which are very useful
+            in case humans need to interpret or read the data.
+
         </para>
         <example><info><title>Example LDIF content file</title></info>

@@ -50,27 +58,12 @@
         <para>
             LDIF files could describe not only the data an entry contains, but also various
             changes to the entry itself. If such an LDIF file would then be given to a
-            LDAP server, he would interpret those changes instead just importing the data.
-            Note in the example below, that even though LDIF content and LDIF change files could be
-            mixed freely, this is not true for individual entries: a specific entry may be either
-            describing content or changes, but not both.
+            LDAP server, he would interpret those changes instead just importing the data. It
+            is comparable to a diff file on unix and familiar to the SQL dump.
         </para>
     <example><info><title>Example LDIF change file</title></info>

         <programlisting role="text"><![CDATA[
-#
-# This is a content+change LDIF file.
-# It does contain the (shortened) entry from the example above to show
-# that LDIF files can contain multiple entry modes.
-# The second entry is a change entry. In this case, some
-# operations will be done on the entries attributes.
-#
-version: 1
-dn: cn=test1,ou=example,dc=cno
-objectclass: someobjectclass
-attr1: 12345
-cn: test1
-
 # Delete attr1, replace values of attr2 and add new attribute attr42
 # The attribute "changetype" is special: it says, what to do with
 # this entries dataset. It could also be "delete" or "add" to delete
@@ -227,6 +220,14 @@

 ]]></programlisting>
         </example>
+
+        <para>
+          Since version 2.1.0 <classname>Net_LDAP2_Filter</classname> can do client side filtering on entry objects.
+          This may be especially useful when combined with LDIF reading support as it allows the developer
+          to execute select querys on the LDIF content. That enables for example the development of
+          reports on those files without the need for an LDAP server.
+          Please refer to the documentation of <link linkend="package.networking.net-ldap2.filter">LDAP filters</link>.
+        </para>
     </refsection>

     <refsection><info><title>Writing Net_LDAP2_Entry objects to a LDIF content file</title></info>

--6a10ce3280ab2c613349111f195ebdc3796f69e7--