From 4a22b5dfc3f62dda9eb8175a9822904bd3cf2ff4 Mon Sep 17 00:00:00 2001 From: Marcin Gibula Date: Thu, 3 Jul 2008 16:15:25 +0000 Subject: [PATCH] Documentation update. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@261981 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/xdiff/book.xml | 10 +++++- .../functions/xdiff-file-diff-binary.xml | 30 +++++++++++------- reference/xdiff/functions/xdiff-file-diff.xml | 31 +++++++++++-------- .../xdiff/functions/xdiff-file-merge3.xml | 27 +++++++++------- .../functions/xdiff-file-patch-binary.xml | 14 ++++++--- .../xdiff/functions/xdiff-file-patch.xml | 16 +++++++--- .../functions/xdiff-string-diff-binary.xml | 28 ++++++++++------- .../xdiff/functions/xdiff-string-diff.xml | 26 +++++++++------- .../xdiff/functions/xdiff-string-merge3.xml | 28 ++++++++++------- .../functions/xdiff-string-patch-binary.xml | 15 ++++++--- .../xdiff/functions/xdiff-string-patch.xml | 15 +++++++-- 11 files changed, 151 insertions(+), 89 deletions(-) diff --git a/reference/xdiff/book.xml b/reference/xdiff/book.xml index 0b0d665646..4c317f96e3 100644 --- a/reference/xdiff/book.xml +++ b/reference/xdiff/book.xml @@ -1,5 +1,5 @@ - + @@ -20,6 +20,14 @@ archives or images, binary patches will be adequate choice as they are binary safe and handle non-printable characters well. + + Starting from version 1.5.0 there are two different sets of functions for generating + binary patches. New functions - xdiff_string_rabdiff and + xdiff_file_rabdiff 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 + libxdiff site. + This extension uses libxdiff to implement these functions. Please see &url.xdiff; for more informations. diff --git a/reference/xdiff/functions/xdiff-file-diff-binary.xml b/reference/xdiff/functions/xdiff-file-diff-binary.xml index 676e78433f..f3011e2243 100644 --- a/reference/xdiff/functions/xdiff-file-diff-binary.xml +++ b/reference/xdiff/functions/xdiff-file-diff-binary.xml @@ -1,23 +1,27 @@ - + xdiff_file_diff_binary - Make binary diff of two files + Alias of xdiff_file_bdiff &reftitle.description; boolxdiff_file_diff_binary - stringfile1 - stringfile2 + stringold_file + stringnew_file stringdest - 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 xdiff_file_bpatch. + + + Starting with version 1.5.0 this function is an alias of xdiff_file_bdiff. @@ -26,18 +30,18 @@ - file1 + old_file - Path to the first file. + Path to the first file. This file acts as "old" file. - file2 + new_file - Path to the second file. + Path to the second file. This file acts as "new" file. @@ -45,7 +49,8 @@ dest - 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. @@ -96,7 +101,8 @@ xdiff_file_diff_binary($old_version, $new_version, 'my_script.bdiff'); &reftitle.seealso; - xdiff_string_diff_binary + xdiff_file_bdiff + xdiff_file_bpatch diff --git a/reference/xdiff/functions/xdiff-file-diff.xml b/reference/xdiff/functions/xdiff-file-diff.xml index e7f94831d5..0d7de2dfc2 100644 --- a/reference/xdiff/functions/xdiff-file-diff.xml +++ b/reference/xdiff/functions/xdiff-file-diff.xml @@ -1,5 +1,5 @@ - + @@ -11,14 +11,19 @@ &reftitle.description; boolxdiff_file_diff - stringfile1 - stringfile2 + stringold_file + stringnew_file stringdest intcontext boolminimal - 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 old_file and + new_file and stores it in dest file. The + resulting file is human-readable. An optional context parameter + specifies how many lines of context should be added around each change (with default value of 3). + Setting minimal parameter to true will result in outputting the shortest + patch file possible (can take a long time). @@ -27,18 +32,18 @@ - file1 + old_file - Path to the first file. + Path to the first file. This file acts as "old" file. - file2 + new_file - Path to the second file. + Path to the second file. This file acts as "new" file. @@ -46,7 +51,7 @@ dest - Path of the resulting file. + Path of the resulting patch file. @@ -55,7 +60,7 @@ Indicates how many lines of context you want to include in diff - result. + result. Default is 3. @@ -85,7 +90,7 @@ <function>xdiff_file_diff</function> example - 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. This function doesn't work well with binary files. To make diff of binary - files use xdiff_file_diff_binary function. + files use xdiff_file_bdiff/xdiff_file_rabdiff function. @@ -115,7 +120,7 @@ xdiff_file_diff($old_version, $new_version, 'my_script.diff', 2); &reftitle.seealso; - xdiff_string_diff + xdiff_file_patch diff --git a/reference/xdiff/functions/xdiff-file-merge3.xml b/reference/xdiff/functions/xdiff-file-merge3.xml index 7967e3abd9..18bf90843a 100644 --- a/reference/xdiff/functions/xdiff-file-merge3.xml +++ b/reference/xdiff/functions/xdiff-file-merge3.xml @@ -1,5 +1,5 @@ - + @@ -11,13 +11,15 @@ &reftitle.description; mixedxdiff_file_merge3 - stringfile1 - stringfile2 - stringfile3 + stringold_file + stringnew_file1 + stringnew_file2 stringdest - Merges three files into one and stores the result in a file. + Merges three files into one and stores the result in a file dest. + The old_file is an original version while new_file1 + and new_file2 are modified versions of an original. @@ -26,26 +28,26 @@ - file1 + old_file - Path to the first file. + Path to the first file. It acts as "old" file. - file2 + new_file1 - Path to the second file. + Path to the second file. It acts as modified version of old_file. - file3 + new_file2 - Path to the third file. + Path to the third file. It acts as modified version of old_file. @@ -53,7 +55,8 @@ dest - Path of the resulting file. + Path of the resulting file, containing merged changed from both new_file1 and + new_file2. diff --git a/reference/xdiff/functions/xdiff-file-patch-binary.xml b/reference/xdiff/functions/xdiff-file-patch-binary.xml index aa00a735d7..e221a7bda4 100644 --- a/reference/xdiff/functions/xdiff-file-patch-binary.xml +++ b/reference/xdiff/functions/xdiff-file-patch-binary.xml @@ -1,10 +1,10 @@ - + xdiff_file_patch_binary - Patch a file with a binary diff + Alias of xdiff_file_bpatch @@ -17,7 +17,12 @@ Patches a file with a binary - patch and stores the result in a file. + patch and stores the result in a file dest. + This function accepts patches created both via xdiff_file_bdiff + or xdiff_file_rabdiff functions or their string counterparts. + + + Starting with version 1.5.0 this function is an alias of xdiff_file_bpatch. @@ -37,8 +42,7 @@ patch - The binary patch file. It has to be created using xdiff_file_diff_binary or - xdiff_string_diff_binary function. + The binary patch file. diff --git a/reference/xdiff/functions/xdiff-file-patch.xml b/reference/xdiff/functions/xdiff-file-patch.xml index eb869602b6..62aea1ae54 100644 --- a/reference/xdiff/functions/xdiff-file-patch.xml +++ b/reference/xdiff/functions/xdiff-file-patch.xml @@ -1,5 +1,5 @@ - + @@ -17,8 +17,10 @@ intflags - Patches a file with a unified - patch and stores the result in a file. + Patches a file with a patch and stores the result in a file. + patch has to be an unified diff created by + xdiff_file_diff/xdiff_string_diff function. + An optional flags parameter specifies mode of operation. @@ -38,7 +40,7 @@ patch - The patch file. It has to be created using xdiff_string_diff, + The unified patch file. It has to be created using xdiff_string_diff, xdiff_file_diff functions or compatible tools. @@ -59,6 +61,10 @@ normal patch) or XDIFF_PATCH_REVERSE (reversed patch). + + Starting from version 1.5.0, you can also use binary OR to enable + XDIFF_PATCH_IGNORESPACE flag. + @@ -125,7 +131,7 @@ if (is_string($errors)) { &reftitle.seealso; - xdiff_string_patch + xdiff_file_diff diff --git a/reference/xdiff/functions/xdiff-string-diff-binary.xml b/reference/xdiff/functions/xdiff-string-diff-binary.xml index 6cad47f717..9a84ab40ce 100644 --- a/reference/xdiff/functions/xdiff-string-diff-binary.xml +++ b/reference/xdiff/functions/xdiff-string-diff-binary.xml @@ -1,22 +1,27 @@ - + xdiff_string_diff_binary - Make binary diff of two strings + Alias of xdiff_string_bdiff &reftitle.description; - stringxdiff_string_diff_binary - stringstr1 - stringstr2 + stringxdiff_string_bdiff + stringold_data + stringnew_data - 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 xdiff_string_bpatch/xdiff_file_bpatch. + + Starting with version 1.5.0 this function is an alias of xdiff_string_bdiff. + @@ -24,18 +29,18 @@ - str1 + old_data - First string with binary data. + First string with binary data. It acts as "old" data. - str2 + new_data - Second string with binary data. + Second string with binary data. It acts as "new" data. @@ -54,7 +59,8 @@ &reftitle.seealso; - xdiff_file_diff_binary + xdiff_string_bdiff + xdiff_string_bpatch diff --git a/reference/xdiff/functions/xdiff-string-diff.xml b/reference/xdiff/functions/xdiff-string-diff.xml index 4ebbfe7e9f..876d5fa465 100644 --- a/reference/xdiff/functions/xdiff-string-diff.xml +++ b/reference/xdiff/functions/xdiff-string-diff.xml @@ -1,5 +1,5 @@ - + @@ -11,13 +11,17 @@ &reftitle.description; stringxdiff_string_diff - stringstr1 - stringstr2 + stringold_data + stringnew_data intcontext boolminimal - Makes a unified diff of two strings. + Makes an unified diff containing differences between old_data string and + new_data string and returns it. The resulting diff is human-readable. + An optional context parameter specifies how many lines of context should be + added around each change (with default value of 3). Setting minimal parameter + to true will result in outputting the shortest patch file possible (can take a long time). @@ -26,18 +30,18 @@ - str1 + old_data - First string with data. + First string with data. It acts as "old" data. - str2 + new_data - Second string with data. + Second string with data. It acts as "new" data. @@ -46,7 +50,7 @@ Indicates how many lines of context you want to include in the diff - result. + result. Default is 3. @@ -102,7 +106,7 @@ if (is_string($diff)) { This function doesn't work well with binary strings. To make diff of binary - strings use xdiff_string_diff_binary. + strings use xdiff_string_bdiff/xdiff_string_rabdiff. @@ -111,7 +115,7 @@ if (is_string($diff)) { &reftitle.seealso; - xdiff_file_diff + xdiff_string_patch diff --git a/reference/xdiff/functions/xdiff-string-merge3.xml b/reference/xdiff/functions/xdiff-string-merge3.xml index 234c5b940e..0617d1ed4a 100644 --- a/reference/xdiff/functions/xdiff-string-merge3.xml +++ b/reference/xdiff/functions/xdiff-string-merge3.xml @@ -1,5 +1,5 @@ - + @@ -11,13 +11,17 @@ &reftitle.description; mixedxdiff_string_merge3 - stringstr1 - stringstr2 - stringstr3 + stringold_data + stringnew_data1 + stringnew_data2 stringerror - Merges three strings into one. + Merges three strings into one and returns the result. + The old_data is an original version of data + while new_file1 and new_file2 are modified + versions of an original. An optional error is used to pass any + rejected parts during merging process. @@ -26,26 +30,26 @@ - str1 + old_data - First string with data. + First string with data. It acts as "old" data. - str2 + new_data1 - Second string with data. + Second string with data. It acts as modified version of old_data. - str3 + new_data2 - Third string with data. + Third string with data. It acts as modified version of old_data. @@ -64,7 +68,7 @@ &reftitle.returnvalues; - 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. diff --git a/reference/xdiff/functions/xdiff-string-patch-binary.xml b/reference/xdiff/functions/xdiff-string-patch-binary.xml index 69943ff6e8..a01e342596 100644 --- a/reference/xdiff/functions/xdiff-string-patch-binary.xml +++ b/reference/xdiff/functions/xdiff-string-patch-binary.xml @@ -1,10 +1,10 @@ - + xdiff_string_patch_binary - Patch a string with a binary diff + Alias of xdiff_string_bpatch @@ -15,7 +15,12 @@ stringpatch - Patches a string with a binary patch. + Patches a string str with a binary patch. + This function accepts patches created both via xdiff_string_bdiff + and xdiff_string_rabdiff functions or their file counterparts. + + + Starting with version 1.5.0 this function is an alias of xdiff_string_bpatch. @@ -54,7 +59,9 @@ &reftitle.seealso; - xdiff_file_patch_binary + xdiff_string_bpatch + xdiff_string_bdiff + xdiff_string_rabdiff diff --git a/reference/xdiff/functions/xdiff-string-patch.xml b/reference/xdiff/functions/xdiff-string-patch.xml index c62239258f..29d0b285ac 100644 --- a/reference/xdiff/functions/xdiff-string-patch.xml +++ b/reference/xdiff/functions/xdiff-string-patch.xml @@ -1,5 +1,5 @@ - + @@ -17,7 +17,12 @@ stringerror - Patches a string with a unified patch from patch parameter. + Patches a str string with an unified patch in patch parameter + and returns the result. patch has to be an unified diff created by + xdiff_file_diff/xdiff_string_diff function. + An optional flags parameter specifies mode of operation. Any + rejected parts of the patch will be stored inside error variable if + it is provided. @@ -50,6 +55,10 @@ XDIFF_PATCH_NORMAL (default mode, normal patch) or XDIFF_PATCH_REVERSE (reversed patch). + + Starting from version 1.5.0, you can also use binary OR to enable + XDIFF_PATCH_IGNORESPACE flag. + @@ -109,7 +118,7 @@ if (strlen($errors)) { &reftitle.seealso; - xdiff_file_patch + xdiff_string_diff