Documentation update.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@261981 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Marcin Gibula 2008-07-03 16:15:25 +00:00
parent 697a71435a
commit 4a22b5dfc3
11 changed files with 151 additions and 89 deletions

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.3 $ -->
<!-- $Revision: 1.4 $ -->
<!-- Purpose: basic.text -->
<!-- Membership: pecl, external -->
@ -20,6 +20,14 @@
archives or images, binary patches will be adequate choice as they are binary safe and
handle non-printable characters well.
</para>
<para>
Starting from version 1.5.0 there are two different sets of functions for generating
binary patches. New functions - <function>xdiff_string_rabdiff</function> and
<function>xdiff_file_rabdiff</function> generate output compatible with older functions
but are typically faster and generate smaller results. For more details about methods of
generating binary patches and differences between them, please check
<link xlink:href="&url.xdiff;">libxdiff</link> site.
</para>
<para>
This extension uses libxdiff to implement these functions. Please see
<link xlink:href="&url.xdiff;">&url.xdiff;</link> for more informations.

View file

@ -1,23 +1,27 @@
<?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-diff-binary" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>xdiff_file_diff_binary</refname>
<refpurpose>Make binary diff of two files</refpurpose>
<refpurpose>Alias of xdiff_file_bdiff</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>xdiff_file_diff_binary</methodname>
<methodparam><type>string</type><parameter>file1</parameter></methodparam>
<methodparam><type>string</type><parameter>file2</parameter></methodparam>
<methodparam><type>string</type><parameter>old_file</parameter></methodparam>
<methodparam><type>string</type><parameter>new_file</parameter></methodparam>
<methodparam><type>string</type><parameter>dest</parameter></methodparam>
</methodsynopsis>
<para>
Makes a binary diff of two files and stores the result in a file.
This function works with both text and binary files.
Makes a binary diff of two files and stores the result in a patch file.
This function works with both text and binary files. Resulting patch
file can be later applied using <function>xdiff_file_bpatch</function>.
</para>
<para>
Starting with version 1.5.0 this function is an alias of <function>xdiff_file_bdiff</function>.
</para>
</refsect1>
@ -26,18 +30,18 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>file1</parameter></term>
<term><parameter>old_file</parameter></term>
<listitem>
<para>
Path to the first file.
Path to the first file. This file acts as "old" file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>file2</parameter></term>
<term><parameter>new_file</parameter></term>
<listitem>
<para>
Path to the second file.
Path to the second file. This file acts as "new" file.
</para>
</listitem>
</varlistentry>
@ -45,7 +49,8 @@
<term><parameter>dest</parameter></term>
<listitem>
<para>
Path of the resulting file. Resulting file is in binary format and is human-unreadable.
Path of the resulting patch file. Resulting file containts differences
between "old" and "new" files. It is in binary format and is human-unreadable.
</para>
</listitem>
</varlistentry>
@ -96,7 +101,8 @@ xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff');
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_string_diff_binary</function></member>
<member><function>xdiff_file_bdiff</function></member>
<member><function>xdiff_file_bpatch</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -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" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -11,14 +11,19 @@
&reftitle.description;
<methodsynopsis>
<type>bool</type><methodname>xdiff_file_diff</methodname>
<methodparam><type>string</type><parameter>file1</parameter></methodparam>
<methodparam><type>string</type><parameter>file2</parameter></methodparam>
<methodparam><type>string</type><parameter>old_file</parameter></methodparam>
<methodparam><type>string</type><parameter>new_file</parameter></methodparam>
<methodparam><type>string</type><parameter>dest</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>context</parameter></methodparam>
<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. Resulting file is human-readable.
Makes an unified diff containing differences between <parameter>old_file</parameter> and
<parameter>new_file</parameter> and stores it in <parameter>dest</parameter> file. The
resulting file is human-readable. An optional <parameter>context</parameter> parameter
specifies how many lines of context should be added around each change (with default value of 3).
Setting <parameter>minimal</parameter> parameter to true will result in outputting the shortest
patch file possible (can take a long time).
</para>
</refsect1>
@ -27,18 +32,18 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>file1</parameter></term>
<term><parameter>old_file</parameter></term>
<listitem>
<para>
Path to the first file.
Path to the first file. This file acts as "old" file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>file2</parameter></term>
<term><parameter>new_file</parameter></term>
<listitem>
<para>
Path to the second file.
Path to the second file. This file acts as "new" file.
</para>
</listitem>
</varlistentry>
@ -46,7 +51,7 @@
<term><parameter>dest</parameter></term>
<listitem>
<para>
Path of the resulting file.
Path of the resulting patch file.
</para>
</listitem>
</varlistentry>
@ -55,7 +60,7 @@
<listitem>
<para>
Indicates how many lines of context you want to include in diff
result.
result. Default is 3.
</para>
</listitem>
</varlistentry>
@ -85,7 +90,7 @@
<example>
<title><function>xdiff_file_diff</function> example</title>
<para>
The following code makes unified diff of two php files.
The following code makes unified diff of two php files with context lenght of 2.
</para>
<programlisting role="php">
<![CDATA[
@ -106,7 +111,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> function.
files use <function>xdiff_file_bdiff</function>/<function>xdiff_file_rabdiff</function> function.
</para>
</note>
</refsect1>
@ -115,7 +120,7 @@ xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2);
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_string_diff</function></member>
<member><function>xdiff_file_patch</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -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-merge3" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -11,13 +11,15 @@
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>xdiff_file_merge3</methodname>
<methodparam><type>string</type><parameter>file1</parameter></methodparam>
<methodparam><type>string</type><parameter>file2</parameter></methodparam>
<methodparam><type>string</type><parameter>file3</parameter></methodparam>
<methodparam><type>string</type><parameter>old_file</parameter></methodparam>
<methodparam><type>string</type><parameter>new_file1</parameter></methodparam>
<methodparam><type>string</type><parameter>new_file2</parameter></methodparam>
<methodparam><type>string</type><parameter>dest</parameter></methodparam>
</methodsynopsis>
<para>
Merges three files into one and stores the result in a file.
Merges three files into one and stores the result in a file <parameter>dest</parameter>.
The <parameter>old_file</parameter> is an original version while <parameter>new_file1</parameter>
and <parameter>new_file2</parameter> are modified versions of an original.
</para>
</refsect1>
@ -26,26 +28,26 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>file1</parameter></term>
<term><parameter>old_file</parameter></term>
<listitem>
<para>
Path to the first file.
Path to the first file. It acts as "old" file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>file2</parameter></term>
<term><parameter>new_file1</parameter></term>
<listitem>
<para>
Path to the second file.
Path to the second file. It acts as modified version of <parameter>old_file</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>file3</parameter></term>
<term><parameter>new_file2</parameter></term>
<listitem>
<para>
Path to the third file.
Path to the third file. It acts as modified version of <parameter>old_file</parameter>.
</para>
</listitem>
</varlistentry>
@ -53,7 +55,8 @@
<term><parameter>dest</parameter></term>
<listitem>
<para>
Path of the resulting file.
Path of the resulting file, containing merged changed from both <parameter>new_file1</parameter> and
<parameter>new_file2</parameter>.
</para>
</listitem>
</varlistentry>

View file

@ -1,10 +1,10 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- 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>
<refname>xdiff_file_patch_binary</refname>
<refpurpose>Patch a file with a binary diff</refpurpose>
<refpurpose>Alias of xdiff_file_bpatch</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -17,7 +17,12 @@
</methodsynopsis>
<para>
Patches a <parameter>file</parameter> with a binary
<parameter>patch</parameter> and stores the result in a file.
<parameter>patch</parameter> and stores the result in a file <parameter>dest</parameter>.
This function accepts patches created both via <function>xdiff_file_bdiff</function>
or <function>xdiff_file_rabdiff</function> functions or their string counterparts.
</para>
<para>
Starting with version 1.5.0 this function is an alias of <function>xdiff_file_bpatch</function>.
</para>
</refsect1>
@ -37,8 +42,7 @@
<term><parameter>patch</parameter></term>
<listitem>
<para>
The binary patch file. It has to be created using <function>xdiff_file_diff_binary</function> or
<function>xdiff_string_diff_binary</function> function.
The binary patch file.
</para>
</listitem>
</varlistentry>

View file

@ -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" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -17,8 +17,10 @@
<methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
</methodsynopsis>
<para>
Patches a <parameter>file</parameter> with a unified
<parameter>patch</parameter> and stores the result in a file.
Patches a <parameter>file</parameter> with a <parameter>patch</parameter> and stores the result in a file.
<parameter>patch</parameter> has to be an unified diff created by
<function>xdiff_file_diff</function>/<function>xdiff_string_diff</function> function.
An optional <parameter>flags</parameter> parameter specifies mode of operation.
</para>
</refsect1>
@ -38,7 +40,7 @@
<term><parameter>patch</parameter></term>
<listitem>
<para>
The patch file. It has to be created using <function>xdiff_string_diff</function>,
The unified patch file. It has to be created using <function>xdiff_string_diff</function>,
<function>xdiff_file_diff</function> functions or compatible tools.
</para>
</listitem>
@ -59,6 +61,10 @@
normal patch) or <constant>XDIFF_PATCH_REVERSE</constant> (reversed
patch).
</para>
<para>
Starting from version 1.5.0, you can also use binary OR to enable
<constant>XDIFF_PATCH_IGNORESPACE</constant> flag.
</para>
</listitem>
</varlistentry>
</variablelist>
@ -125,7 +131,7 @@ if (is_string($errors)) {
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_string_patch</function></member>
<member><function>xdiff_file_diff</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -1,22 +1,27 @@
<?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-diff-binary" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>xdiff_string_diff_binary</refname>
<refpurpose>Make binary diff of two strings</refpurpose>
<refpurpose>Alias of xdiff_string_bdiff</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>xdiff_string_diff_binary</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
<type>string</type><methodname>xdiff_string_bdiff</methodname>
<methodparam><type>string</type><parameter>old_data</parameter></methodparam>
<methodparam><type>string</type><parameter>new_data</parameter></methodparam>
</methodsynopsis>
<para>
Makes a binary diff of two strings.
Makes a binary diff of two strings and returns the result.
This function works with both text and binary data. Resulting patch
can be later applied using <function>xdiff_string_bpatch</function>/<function>xdiff_file_bpatch</function>.
</para>
<para>
Starting with version 1.5.0 this function is an alias of <function>xdiff_string_bdiff</function>.
</para>
</refsect1>
<refsect1 role="parameters">
@ -24,18 +29,18 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>str1</parameter></term>
<term><parameter>old_data</parameter></term>
<listitem>
<para>
First string with binary data.
First string with binary data. It acts as "old" data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>str2</parameter></term>
<term><parameter>new_data</parameter></term>
<listitem>
<para>
Second string with binary data.
Second string with binary data. It acts as "new" data.
</para>
</listitem>
</varlistentry>
@ -54,7 +59,8 @@
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_file_diff_binary</function></member>
<member><function>xdiff_string_bdiff</function></member>
<member><function>xdiff_string_bpatch</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -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-diff" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -11,13 +11,17 @@
&reftitle.description;
<methodsynopsis>
<type>string</type><methodname>xdiff_string_diff</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
<methodparam><type>string</type><parameter>old_data</parameter></methodparam>
<methodparam><type>string</type><parameter>new_data</parameter></methodparam>
<methodparam choice="opt"><type>int</type><parameter>context</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>minimal</parameter></methodparam>
</methodsynopsis>
<para>
Makes a unified diff of two strings.
Makes an unified diff containing differences between <parameter>old_data</parameter> string and
<parameter>new_data</parameter> string and returns it. The resulting diff is human-readable.
An optional <parameter>context</parameter> parameter specifies how many lines of context should be
added around each change (with default value of 3). Setting <parameter>minimal</parameter> parameter
to true will result in outputting the shortest patch file possible (can take a long time).
</para>
</refsect1>
@ -26,18 +30,18 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>str1</parameter></term>
<term><parameter>old_data</parameter></term>
<listitem>
<para>
First string with data.
First string with data. It acts as "old" data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>str2</parameter></term>
<term><parameter>new_data</parameter></term>
<listitem>
<para>
Second string with data.
Second string with data. It acts as "new" data.
</para>
</listitem>
</varlistentry>
@ -46,7 +50,7 @@
<listitem>
<para>
Indicates how many lines of context you want to include in the diff
result.
result. Default is 3.
</para>
</listitem>
</varlistentry>
@ -102,7 +106,7 @@ if (is_string($diff)) {
<note>
<para>
This function doesn't work well with binary strings. To make diff of binary
strings use <function>xdiff_string_diff_binary</function>.
strings use <function>xdiff_string_bdiff</function>/<function>xdiff_string_rabdiff</function>.
</para>
</note>
</refsect1>
@ -111,7 +115,7 @@ if (is_string($diff)) {
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_file_diff</function></member>
<member><function>xdiff_string_patch</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.10 $ -->
<!-- $Revision: 1.11 $ -->
<!-- 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>
@ -11,13 +11,17 @@
&reftitle.description;
<methodsynopsis>
<type>mixed</type><methodname>xdiff_string_merge3</methodname>
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
<methodparam><type>string</type><parameter>str3</parameter></methodparam>
<methodparam><type>string</type><parameter>old_data</parameter></methodparam>
<methodparam><type>string</type><parameter>new_data1</parameter></methodparam>
<methodparam><type>string</type><parameter>new_data2</parameter></methodparam>
<methodparam choice="opt"><type>string</type><parameter role="reference">error</parameter></methodparam>
</methodsynopsis>
<para>
Merges three strings into one.
Merges three strings into one and returns the result.
The <parameter>old_data</parameter> is an original version of data
while <parameter>new_file1</parameter> and <parameter>new_file2</parameter> are modified
versions of an original. An optional <parameter>error</parameter> is used to pass any
rejected parts during merging process.
</para>
</refsect1>
@ -26,26 +30,26 @@
<para>
<variablelist>
<varlistentry>
<term><parameter>str1</parameter></term>
<term><parameter>old_data</parameter></term>
<listitem>
<para>
First string with data.
First string with data. It acts as "old" data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>str2</parameter></term>
<term><parameter>new_data1</parameter></term>
<listitem>
<para>
Second string with data.
Second string with data. It acts as modified version of <parameter>old_data</parameter>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>str3</parameter></term>
<term><parameter>new_data2</parameter></term>
<listitem>
<para>
Third string with data.
Third string with data. It acts as modified version of <parameter>old_data</parameter>.
</para>
</listitem>
</varlistentry>
@ -64,7 +68,7 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns merged string, &false; if an internal error happened, or &true;
Returns the merged string, &false; if an internal error happened, or &true;
if merged string is empty.
</para>
</refsect1>

View file

@ -1,10 +1,10 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.0. Found in /scripts directory of phpdoc. -->
<refentry xml:id="function.xdiff-string-patch-binary" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>xdiff_string_patch_binary</refname>
<refpurpose>Patch a string with a binary diff</refpurpose>
<refpurpose>Alias of xdiff_string_bpatch</refpurpose>
</refnamediv>
<refsect1 role="description">
@ -15,7 +15,12 @@
<methodparam><type>string</type><parameter>patch</parameter></methodparam>
</methodsynopsis>
<para>
Patches a string with a binary <parameter>patch</parameter>.
Patches a string <parameter>str</parameter> with a binary <parameter>patch</parameter>.
This function accepts patches created both via <function>xdiff_string_bdiff</function>
and <function>xdiff_string_rabdiff</function> functions or their file counterparts.
</para>
<para>
Starting with version 1.5.0 this function is an alias of <function>xdiff_string_bpatch</function>.
</para>
</refsect1>
@ -54,7 +59,9 @@
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_file_patch_binary</function></member>
<member><function>xdiff_string_bpatch</function></member>
<member><function>xdiff_string_bdiff</function></member>
<member><function>xdiff_string_rabdiff</function></member>
</simplelist>
</para>
</refsect1>

View file

@ -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-patch" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
@ -17,7 +17,12 @@
<methodparam choice="opt"><type>string</type><parameter role="reference">error</parameter></methodparam>
</methodsynopsis>
<para>
Patches a string with a unified patch from <parameter>patch</parameter> parameter.
Patches a <parameter>str</parameter> string with an unified patch in <parameter>patch</parameter> parameter
and returns the result. <parameter>patch</parameter> has to be an unified diff created by
<function>xdiff_file_diff</function>/<function>xdiff_string_diff</function> function.
An optional <parameter>flags</parameter> parameter specifies mode of operation. Any
rejected parts of the patch will be stored inside <parameter>error</parameter> variable if
it is provided.
</para>
</refsect1>
@ -50,6 +55,10 @@
<constant>XDIFF_PATCH_NORMAL</constant> (default mode, normal patch)
or <constant>XDIFF_PATCH_REVERSE</constant> (reversed patch).
</para>
<para>
Starting from version 1.5.0, you can also use binary OR to enable
<constant>XDIFF_PATCH_IGNORESPACE</constant> flag.
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -109,7 +118,7 @@ if (strlen($errors)) {
&reftitle.seealso;
<para>
<simplelist>
<member><function>xdiff_file_patch</function></member>
<member><function>xdiff_string_diff</function></member>
</simplelist>
</para>
</refsect1>