data/TWiki/TWikiMergeDotPm.txt,v
changeset 0 414e01d06fd5
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiMergeDotPm.txt,v	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,160 @@
     1.4 +head	1.3;
     1.5 +access;
     1.6 +symbols;
     1.7 +locks; strict;
     1.8 +comment	@# @;
     1.9 +
    1.10 +
    1.11 +1.3
    1.12 +date	2007.01.16.04.12.00;	author TWikiContributor;	state Exp;
    1.13 +branches;
    1.14 +next	1.2;
    1.15 +
    1.16 +1.2
    1.17 +date	2006.04.01.05.55.39;	author TWikiContributor;	state Exp;
    1.18 +branches;
    1.19 +next	1.1;
    1.20 +
    1.21 +1.1
    1.22 +date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    1.23 +branches;
    1.24 +next	;
    1.25 +
    1.26 +
    1.27 +desc
    1.28 +@new-topic
    1.29 +@
    1.30 +
    1.31 +
    1.32 +1.3
    1.33 +log
    1.34 +@buildrelease
    1.35 +@
    1.36 +text
    1.37 +@---+ Package =TWiki::Merge=
    1.38 +
    1.39 +Support for merging strings
    1.40 +
    1.41 +
    1.42 +%TOC%
    1.43 +
    1.44 +---++ StaticMethod *merge2* <tt>($arev,$a,$brev,$b,$sep,$session,$info)</tt>
    1.45 +
    1.46 +   * =$arev= - rev for $a (string)
    1.47 +   * =$a= - first ('original') string
    1.48 +   * =$brev= - rev for $b (string)
    1.49 +   * =$b= - second ('new') string
    1.50 +   * =$sep= = separator, string RE e.g. '.*?\n' for lines
    1.51 +   * =$session= - TWiki object
    1.52 +   * =$info= - data block passed to plugins merge handler. Conventionally this will identify the source of the text being merged (the source form field, or undef for the body text)
    1.53 +
    1.54 +Perform a merge of two versions of the same text, using
    1.55 +HTML tags to mark conflicts.
    1.56 +
    1.57 +The granularity of the merge depends on the setting of $sep.
    1.58 +For example, if it is ="\\n"=, a line-by-line merge will be done.
    1.59 +
    1.60 +Where conflicts exist, they are marked using HTML &lt;del> and
    1.61 +&lt;ins> tags. &lt;del> marks content from $a while &lt;ins>
    1.62 +marks content from $b.
    1.63 +
    1.64 +Non-conflicting content (insertions from either set) are not
    1.65 +marked.
    1.66 +
    1.67 +The plugins =mergeHandler= is called for each merge.
    1.68 +
    1.69 +Call it like this:
    1.70 +<verbatim>
    1.71 +$newText = TWiki::Merge::merge2(
    1.72 +   $oldrev, $old, $newrev, $new, '.*?\n', $session, $info );
    1.73 +</verbatim>
    1.74 +
    1.75 +
    1.76 +
    1.77 +---++ StaticMethod *simpleMerge* <tt>($a,$b,$sep) -> \@@arr</tt>
    1.78 +
    1.79 +Perform a merge of two versions of the same text, returning
    1.80 +an array of strings representing the blocks in the merged context
    1.81 +where each string starts with one of "+", "-" or " " depending on
    1.82 +whether it is an insertion, a deletion, or just text. Insertions
    1.83 +and deletions alway happen in pairs, as text taken in from either
    1.84 +version that does not replace text in the other version will simply
    1.85 +be accepted.
    1.86 +
    1.87 +The granularity of the merge depends on the setting of $sep.
    1.88 +For example, if it is ="\\n"=, a line-by-line merge will be done.
    1.89 +$sep characters are retained in the outout.
    1.90 +
    1.91 +
    1.92 +
    1.93 +---++ StaticMethod *merge3* <tt>($arev,$a,$brev,$b,$crev,$c,$sep,</tt>
    1.94 +                          $session, $info )
    1.95 +
    1.96 +   * =$arev= - rev for common ancestor (id e.g. ver no)
    1.97 +   * =$a= - common ancestor
    1.98 +   * =$brev= - rev no for first derivative string (id)
    1.99 +   * =$b= - first derivative string
   1.100 +   * =$crev= - rev no for second derivative string (id)
   1.101 +   * =$c= - second derivative string
   1.102 +   * =$sep= = separator, string RE e.g. '.*?\n' for lines
   1.103 +   * =$session= - TWiki object
   1.104 +   * =$info= - data block passed to plugins merge handler. Conventionally this will identify the source of the text being merged (the source form field, or undef for the body text)
   1.105 +
   1.106 +Perform a merge of two versions (b and c) of the same text, using
   1.107 +HTML &lt;div> tags to mark conflicts. a is the common ancestor.
   1.108 +
   1.109 +The granularity of the merge depends on the setting of $sep.
   1.110 +For example, if it is =".*?\\n"=, a line-by-line merge will be done.
   1.111 +
   1.112 +Where conflicts exist, they are labeled using the provided revision
   1.113 +numbers.
   1.114 +
   1.115 +The plugins =mergeHandler= is called for each merge.
   1.116 +
   1.117 +Here's a little picture of a 3-way merge:
   1.118 +
   1.119 +      a   <- ancestor
   1.120 +     / \
   1.121 +    b   c <- revisions
   1.122 +     \ /
   1.123 +      d   <- merged result, returned.
   1.124 +
   1.125 +call it like this:
   1.126 +<verbatim>
   1.127 +    my ( $ancestorMeta, $ancestorText ) =
   1.128 +        $store->readTopic( undef, $webName, $topic, $originalrev );
   1.129 +    $newText = TWiki::Merge::merge3(
   1.130 +        $ancestorText, $prevText, $newText,
   1.131 +        $originalrev, $rev, "new",
   1.132 +        '.*?\n' );
   1.133 +</verbatim>
   1.134 +
   1.135 +
   1.136 +@
   1.137 +
   1.138 +
   1.139 +1.2
   1.140 +log
   1.141 +@buildrelease
   1.142 +@
   1.143 +text
   1.144 +@d9 1
   1.145 +@
   1.146 +
   1.147 +
   1.148 +1.1
   1.149 +log
   1.150 +@buildrelease
   1.151 +@
   1.152 +text
   1.153 +@d8 8
   1.154 +a15 1
   1.155 +---++ StaticMethod *insDelMerge* <tt>($a,$b,$sep,$session,$info)</tt>
   1.156 +d30 7
   1.157 +a36 1
   1.158 +The plugins mergeHandler is called for each merge.
   1.159 +d43 1
   1.160 +a43 1
   1.161 +and array of strings representing the blocks in the merged context
   1.162 +d55 44
   1.163 +@