Compare Revisions Add-On

Compare Revisions Add-On

This add-on compares the renderd 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.

This add-on compares the renderd 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

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).

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.

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

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 interwoven output:
  
  

• Screenshot of side-by-side output:
  
  

• Screenshot of side-by-side output:
  
  

These screenshots have been taken from CompareRevisionsAddOnDemoTopic.

These screenshots have been taken from CompareRevisionsAddOnDemoTopic.

The appearance can be affected by templates and skins.

The appearance can be affected by templates and skins.

Usage

Usage

Call http://your/foswiki/bin/compare/Web/Topic?parameters from your browser

Call http://your/foswiki/bin/compare/Web/Topic?parameters from your browser

Parameters

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)

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

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

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

skin=someskin
Chooses someskin for the output. See section Templates below

Templates

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

The templates itself 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

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).

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.

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, compare.pattern.tmpl, interweave.tmpl, interweave.pattern.tmpl ).

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

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

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)

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)

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.

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.

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.

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

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 Foswiki is running.

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 Foswiki is running.

• This script needs some additional Perl modules. If necessary, download and install the required perl modules from CPAN. If you do not want to install these modules in your standard perl location, install them in /your/foswiki/lib. (See e.g. perldoc perlmodinstall on how to install perl modules).
  These modules are required:
  • HTML::Tree (with HTML::TreeBuilder and HTML::Element). These modules in turn need
    • HTML::Parser
    • HTML::Tagset
  • Algorithm::Diff (which is included in the standard Foswiki installation
• Download the ZIP file from the Add-on Home (see below)
• Unzip CompareRevisionsAddOn.zip in your Foswiki installation directory. Content:

  File:	Description:
  data/Projekte/Projekte/System/CompareRevisionsAddOn.txt	Add-on topic
  bin/compare	Add-on script
  lib/Foswiki/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/Foswiki/Plugins/CompareRevisionsAddonPlugin.pm	Helper plugin
  data/Projekte/Projekte/System/CompareRevisionsAddonPlugin.txt	Plugin topic
  pub/Projekte/Projekte/System/CompareRevisionsAddOn/interweaved.png	Interwoven screenshot
  pub/Projekte/Projekte/System/CompareRevisionsAddOn/sidebyside.png	Side-by-side screenshot
  data/Sandbox/CompareRevisionsAddOnDemoTopic.txt	Demonstration topic
  data/Sandbox/CompareRevisionsAddOnDemoTopic.txt,v	Demonstration topic history

• This script needs some additional Perl modules. If necessary, download and install the required perl modules from CPAN. If you do not want to install these modules in your standard perl location, install them in /your/foswiki/lib. (See e.g. perldoc perlmodinstall on how to install perl modules).
  These modules are required:
  • HTML::Tree (with HTML::TreeBuilder and HTML::Element). These modules in turn need
    • HTML::Parser
    • HTML::Tagset
  • Algorithm::Diff (which is included in the standard Foswiki installation
• Download the ZIP file from the Add-on Home (see below)
• Unzip CompareRevisionsAddOn.zip in your Foswiki installation directory. Content:

  File:	Description:
  data/System/CompareRevisionsAddOn.txt	Add-on topic
  bin/compare	Add-on script
  lib/Foswiki/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/Foswiki/Plugins/CompareRevisionsAddonPlugin.pm	Helper plugin
  data/System/CompareRevisionsAddonPlugin.txt	Plugin topic
  pub/System/CompareRevisionsAddOn/interweaved.png	Interwoven screenshot
  pub/System/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:
  Call %SCRIPTURL%/compare/Web/Topic with some existing topic. (Try for instance CompareRevisionsAddOnDemoTopic and compare your output with above screenshots).

• Test if the installation was successful:
  Call %SCRIPTURL%/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

• 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

Add-On Info

Add-On Info

Related Topic: ContributedAddOns

Related Topic: ContributedAddOns