CompareRevisionsAddOn

Compares two revisions of a document. In contrast to normal rdiff, the comparison is done with the rendered HTML output.

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 Foswiki 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:
  
  

• Screenshot of side-by-side output:
  
  

These screenshots have been taken from CompareRevisionsAddOnDemoTopic. (Foswiki no longer ships with the revision history files, so the demo is no longer operational.)

The appearance can be affected by templates and skins.

Usage

Call https://foswiki.org/bin/compare/Web/Topic?parameters from your browser

Parameters

rev1=rev and rev2=rev
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
Chooses the output format. May also be given in the preference variable COMPARERENDERSTYLE

context=n
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=someskin
Chooses someskin for the output. See section Templates below

Templates

The output of the script is rendered by templates. Two templates are needed, comparesidebyside.tmpl (or comparesidebyside.skin.tmpl) for the side-by-side format, and compareinterweave.tmpl (or compareinterweave.skin.tmpl) for the interwoven format. The default templates use a common compare.tmpl (or complare.skin.tmpl) for things used by both.

The templates themselves are broken into 7 parts:

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

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, %TEXT1% is replaced by the text of the old revision and %TEXT2% is replaced by the text of the new revision. In interwoven output, only %TEXT1% is used.

Examples for templates can be found in the default template files from the distribution (compare.tmpl, comparesidebyside.tmpl, compareinterweave.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
Class for added items (i.e. items which are in the newer revision, but not yet in the older one)

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

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

craCompareChange2
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

This Add-On comes pre-installed on Foswiki. You should only need to re-install if there is an upgrade to the Add-On.

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

• Test if the installation was successful:
  Call https://foswiki.org/bin/compare/Web/Topic with some existing topic. (Try for instance 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 PatternSkin again

Dependencies

Name	Version	Description
HTML::Tree	>=3.23	Required for HTML comparisons of topic changes..

Change History

06 Aug 2023 (1.116)	Foswikitask:Item15151: add warnings and strictness
04 May 2017 (1.115)	Foswikitask:Item14366: use CGI::Carp in bin scripts BEGIN block cannot be found via LocalLib.cfg override.
14 Jun 2015 (1.114)	Foswikitask:Item13423: Perl 5.22 deprecations. Foswikitask:Item13378: Support utf-8 internally.
18 Dec 2014 (1.113)	Foswikitask:Item13068: Remove the CompareRevisionsAddOn demo, don't ship revision history Foswikitask:Item11737: Change hardcoded Main to Main Foswikitask:Item12875: Implement controls on access to topic History
01 May 2014 (1.112)	Foswikitask:Item12407: Don't decode entities during comparson. Convert to simple decimal version.
10 Feb 2014	Foswikitask:Item12741: Formatting parameters not passed on the referenced scripts
23 Oct 2013 (1.1.11)	Foswikitask:Item12423: fix double encoding in header on UTF-8 sites
28 Feb 2013 (1.1.10)	Foswikitask:Item12408: use correct template names in docs
31 Jan 2013 (1.1.9)	Foswikitask:Item12337: Remove undocumented dependency on CPAN:HTML::TreeBuilder >= 4.0
28 Nov 2012 (1.1.8)	Foswikitask:Item11267: Convert to perl version strings, Foswikitask:Item11755: Compare breaks characterset encoding. Foswikitask:Item11930: Read settings from SitePreferences
06 Apr 2012 (1.1.7)	Foswikitask:Item11445: References to Sandbos should use %SANDBOXWEB% macro. Release with Foswiki 1.1.5.
05 Dec 2011 (1.1.6)	Release with Foswiki 1.1.4 - minor code and documentation cleanup.
28 May 2011 (1.1.6)	Foswikitask:Item10803 - Fix invalid Foswiki configuration affecting ApacheLogin users introduced in 1.1.4
17 May 2011 (1.1.5)	Foswikitask:Item10677 - Speed optimization by avoiding doing pointless lookup for settings in plugin topic
30 Apr 2011 (1.1.4)	Foswikitask:Item10566 - Add compareauth script for ApacheLogin users - Switch to x.y.z version numbering - Moved dependency list from documentation into DEPENDENCIES manifest - Modernize system topic for BuildContrib
10 Apr 2011	Foswikitask:Item10401 - Call logEvent in compare Foswikitask:Item10402 - Don't use obsolete template for missing web/topic. Version shipping with 1.1.3
21 Oct 2010	Added dependency of HTML::Tree to installer and to core MANIFEST so you see it listed in configure
04 Oct 2010	Foswikitask:Item9774 - Add CompareRevisionsAddOn.pm stub module to provide Version & Release strings
31 Jul 2010	Paul Harvey: Foswikitask:Item9415 - 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
09 Aug 2009	Plugin is now a default plugin shipped with Foswiki. It will later have its function integrated in core in a future Foswiki version so its life as default plugin is temporary. Changed its switchboard setting to EXPERT so it is hidden in configure. You should never need to change this anyway.
22 Mar 2009	Gilmar Santos Jr: ported to FSA architecture (Foswiki:Tasks/Item1352)
09 Jan 2009	Gilmar Santos Jr: fixed ambigous print (Foswiki:Tasks.Item716)
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. Plugin is changed to Foswiki namespace and tested and works under Foswiki 1.0.0. Policy is now feel free to modify but please do not break compatibility.
07 Nov 2007	Arthur Clemens: Updated for TWiki 4.2
09 Apr 2006	Updated for new PatternSkin in 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

Related Topic: ContributedAddOns