Extension:Wikidiff2

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced.svg
wikidiff2
Release status: stable
Implementation PHP
Description Faster diff plugin for MediaWiki under PHP and HHVM
Author(s) Tim Starling (Tim Starling (WMF)talk)
Latest version 1.9.0 (2018-10-11)
MediaWiki 1.27+
License GNU General Public License 2.0 or later
Download releases.wikimedia.org - wikidiff2
README
Translate the Wikidiff2 extension if it is available at translatewiki.net
Check usage and version matrix.
Issues Open tasks · Report a bug

Wikidiff2 is a PHP extension that provides the external diff engine for MediaWiki. It is partly based on the original wikidiff, partly on DifferenceEngine.php. It performs word-level (space-delimited) diffs on general text, and character-level diffs on text composed of characters from the Japanese and Thai alphabets and the unified han; it includes support for Thai segmentation for word-level diffs in that language. Japanese, Chinese and Thai do not use spaces to separate words. The input is assumed to be UTF-8 encoded. Invalid UTF-8 may cause undesirable operation, such as truncation of the output, so the input should be validated by the application. The input text should have unix-style line endings.

The output is available as an HTML fragment or a JSON string.

Installing[edit]

Debian or Ubuntu[edit]

apt-get install php-wikidiff2
Warning Warning: On Ubuntu Xenial, you should use the mediawiki-lts PPA for wikidiff2, as the standard package segfaults.

On older versions of the package you may need to run a command to actually enable the extension:

sudo phpenmod wikidiff2

(The command will be php5enmod on versions that provide PHP 5.)

If you are running a MediaWiki version older than 1.27 (newer versions automatically detect wikidiff2), add the following line to your LocalSettings.php file:

$wgExternalDiffEngine = 'wikidiff2';

Manually[edit]

First, get and compile libthai (it should be on your OS or distro's packages).

You can download wikidiff2 through git (git clone https://gerrit.wikimedia.org/r/mediawiki/php/wikidiff2.git) or by downloading a tarball from https://releases.wikimedia.org/wikidiff2/.

Then compile wikidiff2. You need phpize (shipped with PHP).

cd wikidiff2
phpize
./configure
make
sudo make install

Make sure that your php option

extension = wikidiff2.so

is set. This is usually set in your "php.ini" file.

If you are running a MediaWiki version older than 1.27 (newer versions automatically detect wikidiff2), add the following line to your LocalSettings.php file:

$wgExternalDiffEngine = 'wikidiff2';

Formats[edit]

HTML[edit]

The HTML diff—a number of HTML table rows with the rest of the document structure omitted—is available as a side-by-side or inline comparison. The characters "<", ">" and "&" will be HTML-escaped in the output. In the Wikidiff2 C++ library, you can access the side-by-side diff using the TableDiff class or the inline diff using the InlineDiff class. Both classes include an execute method that returns the diff of the text passed in as parameters. You can also access these execute methods using the PHP wrapper functions wikidiff2_do_diff (for the side-by-side diff) and wikidiff2_inline_diff (for the inline diff).

JSON[edit]

The JSON diff provides structured data to compose a visual, line-by-line comparison between two sets of text. In the Wikidiff2 C++ library, you can access the JSON diff using the InlineDiffJSON class, which includes an execute method that returns the diff of the text passed in as parameters. You can also access this execute method using the PHP wrapper function wikidiff2_inline_json_diff.

JSON diff schema

The JSON diff includes properties to identify changes between the two sets of text. For an example of a JSON diff, see the MediaWiki REST API compare revisions endpoint.

property type description
diff

required

array of objects Each object in the diff array represents a line in a visual, line-by-line comparison between the two revisions.
diff.type

required

integer The type of change represented by the diff object, either:
  • 0: A line with the same content in both revisions, included to provide context when viewing the diff. The API returns up to two context lines around each change.
  • 1: A line included in the to revision but not in the from revision.
  • 2: A line included in the from revision but not in the to revision.
  • 3: A line containing text that differs between the two revisions. (For changes to paragraph location as well as content, see type 5.)
  • 4: When a paragraph's location differs between the two revisions, a type 4 object represents the location in the from revision.
  • 5: When a paragraph's location differs between the two revisions, a type 5 object represents the location in the to revision. This type can also include word-level differences between the two revisions.
diff.lineNumber

optional

integer The line number of the change based on the to revision.
diff.text

required

string The text of the line, including content from both revisions. For a line containing text that differs between the two revisions, you can use highlightRanges to visually indicate added and removed text. For a line containing a new line, the API returns the text as "" (empty string).
diff.highlightRanges

optional

array of objects An array of objects that indicate where and in what style text should be highlighted to visually represent changes.

Each object includes:

  • start (integer): Where the highlighted text should start, in the number of bytes from the beginning of the line.
  • length (integer): The length of the highlighted section, in bytes.
  • type (integer): The type of highlight:
    • 0 indicates an addition.
    • 1 indicates a deletion.
diff.moveInfo

optional

object Visual indicators to use when a paragraph's location differs between the two revisions. moveInfo objects occur in pairs within the diff.
  • id (string): The ID of the paragraph described by the diff object.
  • linkId (string): The ID of the corresponding paragraph.
    • For type 4 diff objects, linkId represents the location in the to revision.
    • For type 5 diff objects, linkId represents the location in the from revision.
  • linkDirection (integer): A visual indicator of the relationship between the two locations. You can use this property to display an arrow icon within the diff.
    • 0 indicates that the linkId paragraph is lower on the page than the id paragraph.
    • 1 indicates that the linkId paragraph is higher on the page than the id paragraph.
diff.sectionTitleIndex

optional

integer An integer referring to the section title of the change as listed in sectionTitles. For example: a value of 0 corresponds to the first title listed in the sectionTitles array; a value of 1 corresponds to the second title.
sectionTitles

optional

array of strings An array of section titles referenced in the diff.

Links[edit]