%META:TOPICINFO{author="TWikiContributor" date="1289635554" format="1.1" version="1"}%
---+!! Compare Revisions Add-On
<!--
   Contributions to this TWiki add-on are appreciated. Please update the add-on page at
   http://twiki.org/cgi-bin/view/Plugins/CompareRevisionsAddOn or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/CompareRevisionsAddOnDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.

   * Set SHORTDESCRIPTION = Compares two revisions of a document
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

This add-on compares the rendered HTML output of two revisions and shows the differences broken down to the word-by-word level if necessary. The output can be formatted by templates and skins.

---++ Description

The !CompareRevisionsAddOn compares two revisions of a document, like _rdiff_ does. But in contrast to normal _rdiff_, the comparison is done with the rendered HTML output of the revisions instead of the TWiki source text files. (This feature was proposed by many of our users, who found the normal _rdiff_ output too technical - even with the _sidebyside_ option - and wanted to see
differences in the content of the page).

Furthermore, the differences between the revisions are shown as close as possible. If necessary, this means that different words are marked instead of whole lines or even paragraphs.

The differences may be shown in two formats, either side-by-side or as an interwoven output of the old and new revision (like it is done in  Word or !OpenOffice):

   * Screenshot of interwoven output: <br />
     <div class="twikiImage"><img src="%ATTACHURLPATH%/interweave.png" alt="interweave.png" width='714' height='366' /></div>

   * Screenshot of side-by-side output: <br />
     <div class="twikiImage"><img src="%ATTACHURLPATH%/sidebyside.png" alt="sidebyside.png" width='714' height='584' /></div>

These screenshots have been taken from Sandbox.CompareRevisionsAddOnDemoTopic.

The appearance can be affected by templates and skins.

---++ Usage

Call ==http:<nop>//your/twiki/bin/compare/Web/Topic?parameters== from your browser

---+++ Parameters

==rev1=<i>rev</i>== and ==rev2=<i>rev</i>== %BR%
Revision numbers of the two revisions which should be compared. 
Defaults to the last two revisions. (More exact:
_rev2_ defaults to the latest edition, _rev1_ defaults to _rev2_ - 1)

==render=interweave== or ==render=sidebyside== %BR%
Chooses the output format. May also be given in the preference variable COMPARERENDERSTYLE

==context=<i>n</i>== %BR%
The number _n_ of unchanged sections which should be shown around changed sections. 
A section means a top-level section like a paragraph, table, etc.
If _n=-1_ (the default), all unchanged sections are shown.
May also be given in the preference variable COMPARECONTEXT

==skin=<i>someskin</i>== %BR%
Chooses _someskin_ for the output. See section [[#Templates][Templates]] below

---+++ Templates

The output of the script is rendered by templates. Two templates are needed,
==compare.tmpl== (or ==compare.skin.tmpl==) for the side-by-side format,
and ==interweave.tmpl== (or ==interweave.skin.tmpl==) for the interwoven
format.

The templates itself are broken into 7 parts

<verbatim class="tml">
template for start of page
%REPEAT%
template for unchanged section 
which is not printed according to context
%REPEAT%
template for unchanged section 
which is printed
%REPEAT%
template for changed section
%REPEAT%
template for added section
%REPEAT%
template for deleted section
%REPEAT%
template for end of page
</verbatim>

All empty templates for a section default to their predecessor. (E.g. if you 
do not specify a template for a deleted section, it defaults to the template
for an added section, which in turn may default to the template for a changed section).

In the templates for a section, ==%<nop>TEXT1%== is replaced by the text of the old revision
and ==%<nop>TEXT2%== is replaced by the text of the new revision.
In interwoven output, only ==%<nop>TEXT1%== is used.

Examples for templates can be found in the default template files from
the distribution (==compare.tmpl==, ==compare.pattern.tmpl==, ==interweave.tmpl==,
==interweave.pattern.tmpl== ).

---+++ CSS Styles

The differences in the two revisions are marked with the help of
CSS style classes, whose appearance should be defined in the templates.

The following classes are used:

==craCompareAdd== %BR%
Class for added items (i.e. items which are in the newer revision, 
but not yet in the older one)

==craCompareDelete== %BR%
Class for deleted items (i.e. items which are in the older revision,
but no more in the newer one)

==craCompareChange1== %BR%
Class for the items from the older revision which have been changed.

==craCompareChange2== %BR%
Class for the items from the newer revision which have been changed.

In the default templates files from the distribution, the classes 
==craCompareAdd== and ==craCompareChange1== are defined with
a light red background and stroken out text, and ==craCompareDelete== 
and ==craCompareChange2== are defined with a light green background.

---++ Add-On Installation Instructions

__Note:__ You do not need to install anything on the browser to use this add-on. The following instructions are for the administrator who installs the add-on on the server where TWiki is running.

   * This script needs some additional Perl modules.
     If necessary, download and install the required perl modules from [[http://www.cpan.org][CPAN]]. 
     If you do not want to install these modules in your standard perl location,
     install them in /your/twiki/lib.
     (See e.g.
     [[http://www.perldoc.com/perl5.6.1/pod/perlmodinstall.html][perldoc perlmodinstall]] on how to 
     install perl modules).%BR%
     These modules are required:
      * [[http://cpan.uwinnipeg.ca/module/HTML::Tree][HTML::Tree]] (with HTML::TreeBuilder and HTML::Element). These modules in turn need
         * [[http://cpan.uwinnipeg.ca/module/HTML::Parser][HTML::Parser]]
         * [[http://cpan.uwinnipeg.ca/module/HTML::Tagset][HTML::Tagset]]
      * Algorithm::Diff (which is included in the standard TWiki installation
   * Download the zip file from the add-on Home (see below)
   * Unzip ==%TOPIC%.zip== in your TWiki installation directory. Content:
     | *File:*                      | *Description:*   |
     | ==data/TWiki/%TOPIC%.txt==   | Add-on topic     |
     | ==bin/compare==              | Add-on script  |
     | ==lib/TWiki/UI/Compare.pm==  | Perl package used by the script |
     | ==templates/compare.tmpl==   | Template for side-by-side output |
     | ==templates/compare.pattern.tmpl== | Same for pattern skin |
     | ==templates/interweave.tmpl==   | Template for interwoven output |
     | ==templates/interweave.pattern.tmpl== | Same for pattern skin |
     | ==lib/TWiki/Plugins/CompareRevisionsAddonPlugin.pm== | Helper plugin |
     | ==data/TWiki/CompareRevisionsAddonPlugin.txt== | Plugin topic |
     | ==pub/TWiki/CompareRevisionsAddOn/interweaved.png== | Interwoven screenshot |
     | ==pub/TWiki/CompareRevisionsAddOn/sidebyside.png== | Side-by-side screenshot |
     | ==data/Sandbox/CompareRevisionsAddOnDemoTopic.txt== | Demonstration topic |
     | ==data/Sandbox/CompareRevisionsAddOnDemoTopic.txt,v== | Demonstration topic history |

   * Test if the installation was successful:%BR%
     Call ==%<nop>SCRIPTURL%/compare/Web/Topic== with
     some existing topic. (Try for instance Sandbox.CompareRevisionsAddOnDemoTopic and 
     compare your output with above screenshots).

   * Enable the helper plugin CompareRevisionsAddonPlugin with the configure script
   * This plugin will support the HistoryPlugin, if it is enabled
   * If you disable this plugin, the skin will behave like standard <nop>PatternSkin again

---++ Add-On Info

|  Plugin Author: | TWiki:Main.JChristophFuchs, TWiki:Main.KennethLavrsen |
|  Copyright: | &copy; 2005-2006, !JChristophFuchs; <br /> &copy; 2008-2010 Kenneth Lavrsen and Foswiki Contributors <br /> &copy; 2006-2010 TWiki:TWiki.TWikiContributor | 
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Version: | 2010-11-12 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2010-11-12: | TWikibug:Item6530: Doc improvements; updated for TWiki-5.0 -- TWiki:Main.PeterThoeny |
|  21 Oct 2010 | Added dependency of HTML::Tree to installer and to core MANIFEST so you see it listed in configure |
|  04 Oct 2010 | Add CompareRevisionsAddOn.pm stub module to provide Version & Release strings | 
|  31 Jul 2010 | Paul Harvey: Documentation updates |
|  19 Sep 2009 | Kenneth Lavrsen: Expert settings in plugins makes configure fail to save. Using the hidden (H) setting instead which is much better anyway as this is not a setting to be altered by a user. |
|  18 Sep 2009 | Kenneth Lavrsen: Expert settings in plugins makes configure fail to save. Settings therefore un-experted again |
|  12 Sep 2009 | Kenneth Lavrsen: Fixed problem with tables always showing up as changed even when they were not |
|  22 Mar 2009 | Gilmar Santos Jr: ported to TWiki:Codev.TWikiStandAlone architecture |
|  09 Jan 2009 | Gilmar Santos Jr: fixed ambigous print |
|  08 Dec 2008 | Kenneth Lavrsen: Changed the author to myself. !JChristophFuchs is the original author but announced in 2006 that he no longer maintains this plugin. So now I officially take the task as maintainer. |
|  07 Nov 2007 | Arthur Clemens: Updated for TWiki 4.2  |
|  09 Apr 2006 | Updated for new <nop>PatternSkin in [[http://TWiki.org/cgi-bin/view/Codev/TWikiRelease04x00x02][TWikiRelease04x00x02]] |
|  26 Feb 2006 | Updated for TWiki 4 |
|  02 Mar 2005 | Corrected bug concerning uninitialized elements |
|  03 Feb 2005 | Removed blank paragraphs before comparing |
|  20 Jan 2005 | Initial version |
|  CPAN Dependencies: | [[http://cpan.uwinnipeg.ca/module/HTML::Parser][HTML::Parser]], [[http://cpan.uwinnipeg.ca/module/HTML::Tagset][HTML::Tagset]], [[http://cpan.uwinnipeg.ca/module/HTML::Tree][HTML::Tree]] |
|  Other Dependencies: | none |
|  Perl Version: | 5.008 |
|  Add-on Home: | http://TWiki.org/cgi-bin/view/Plugins/CompareRevisionsAddOn |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/CompareRevisionsAddOnDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/CompareRevisionsAddOnAppraisal |

__Related Topic:__ CompareRevisionsAddonPlugin

%META:FILEATTACHMENT{name="interweave.png" attachment="interweave.png" attr="h" comment="" date="1144955876" path="interweave.png" size="24037" stream="interweave.png" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="sidebyside.png" attachment="sidebyside.png" attr="h" comment="" date="1144955876" path="sidebyside.png" size="35098" stream="interweave.png" user="TWikiContributor" version="1"}%
