In preparation for multi-content revisions (MCR), we've made[1] several changes to action=compare. These changes should be deployed to Wikimedia wikis with 1.32.0-wmf.19 or later. The changes should also be available on the Beta Cluster[2] soon for testing.
== Supplying content using templated parameters ==
For MCR, when specifying content (as with the `fromtext` and `totext` parameters) we need the ability to specify content for each "slot" in the page. The way this works for action=compare is that (1) the base revision is determined using the parameters that identify the page and/or revision (`fromtitle`/`totitle`, `fromrev`/`torev`, and so on), then (2) the new `fromslots`/`toslots` parameter specifies which slots are being changed, and then (3) new parameters for each value of `fromslots`/`toslots` specify the content for each of those slots.
In the API help, these new parameters for each value of `fromslots`/`toslots` are described as "templated parameters" and have a placeholder in their names. Where the help describes "totext-{slot}", it's meaning that if you supply "toslots=foo|bar" then there would be corresponding parameters "totext-foo" and "totext-bar" to supply the text for those two slots.
In Special:ApiSandbox, input fields for "totext-foo" and "totext-bar" will appear when you enter those value for "toslots".
In the future templated parameters will be introduced for action=edit and action=parse as well, and other modules as the need arises.
== Deprecations and changes in action=compare ==
The following parameters are deprecated, with replacements as indicated.
- `fromtext` is replaced with `fromtext-main` with `fromslots=main`.
- `fromcontentmodel` is replaced with `fromcontentmodel-main` with `fromslots=main`.
- .`fromcontentformat` is replaced with `fromcontentformat-main` with `fromslots=main`.
- `totext` is replaced with `totext-main` with `toslots=main`.
- `tocontentmodel` is replaced with `tocontentmodel-main` with `toslots=main`.
- .`tocontentformat` is replaced with `tocontentformat-main` with `toslots=main`.
The `fromsection` and `tosection` parameters are also deprecated with no direct replacement. The intended use case for these parameters was to simulate a diff of a section edit, by supplying the edited section's text as `totext` and supplying `fromsection` to extract just the section being edited from the current revision. This use case is now supported by specifying `totext-main` as the edited section's text and supplying `tosection-main` to identify the section being edited, which will be combined into the existing content as for a section edit. This will result in a diff more closely matching that returned for a section edit from the web UI with respect to line numbers and context lines.
By default action=compare will return one HTML blob combining the diffs of all slots, much as is shown in the web UI. The new `slots` parameter may be used to get separate HTML blobs for each slot's diff and to limit which slots' diffs are returned..
Note that the already-deprecated[3] diffing parameters to revision-related modules, such as the rvdifftotext parameter to action=query&prop=revisions, will not be updated for MCR. Code using these parameters should be updated to use action=compare instead.
--
Brad Jorsch (Anomie)
Senior Software Engineer
Wikimedia Foundation