How are Replacements intended to work?

[Kelly]

I don't seem to be able to get Replacements to behave as I expect.

Are they indeed intended to perform a temporary replacement in the text comparison view as it is displayed?

I attempted to use it to replace page number references in a large PDF that I was diff'ing. There has been just enough material added that most pages have shifted a little and a lot of page number references have changed. I don't care about those changes, but the replacement doesn't seem to have any effect.

If I create them as a grammar element, it works, but I was looking for a quick one off thing. I especially would find this useful since the unimportant text was moved into grammar section. I frequently find while working with various files that there are things like time stamps in log files, embedded line numbering, page headers, etc. that I want to temporarily take out of the picture.

In a similar vein I would like to totally exclude the page headings from the comparison as well. These cause a lot of orphans as text slips from one page to the next.

BTW, the help file hasn't been updated with content for replacements. It just shows "Enter topic text here."

[Tim]

In the current release, the help file now has a Replacements topic. Also, we've just posted a new video describing Replacements.

Replacements work only if the differences already are lining up, so they won't help with your page headings that are skewed due to text slips. We hope to reinstate the "Page Heading" grammar element type at some point, and that may be more appropriate.

I realize that changing the grammar definitions is awkward for one off things, but it's actually not bad for temporarily ignoring things. You can define a grammar element once, giving it a custom name, and then set it Important or Unimportant on a per-session basis.

[Michael Kujawa]

That's a very interesting feature! I've certainly done lots of diffs with hundreds of variable renames.

I'm still a little vague on what it's actually doing. Does it apply this replacement only to lines that differ? Does it try the line both ways (which would mean having 20 replacements gets expensive)? I've tried a handful of examples and I'm not quite sure what's happening under the hood.

What I tried (old on top, new on bottom):
public FooBarCor
public GazBarKoz

If I set Bar to be replaced by GazBarKoz, nothing changes. If I set Bar to be replaced by ZZZ, nothing changes. If I set Foo to be replaced by GazBarKoz, it changes the diff so that the BarCor appears deleted on the left.

[Michael Bulgrien]

Replacements occur in the left pane (or in you case, the top pane) only.

A replacement will have no affect unless the following is true on two opposing lines:
1) The text to be replaced must exist on the left side, and
2) The replacement text must exist on the right side.

If such a match is found, then the text to be replaced is highlighted and italicized on the left, and the replacement text is highlighted and italicized on the right to indicate that there is replacement logic in place that will equate the left side with the right side. If "Ignore Unimportant Differences" is active, then the highlight goes away to indicate that the campare considers both sides to be equivalent.

The "replacement" is a logical one performed during the compare of both sides, not a physical one that visibly changes one side to look like the other.

[Michael Bulgrien]

If I set Bar to be replaced by GazBarKoz, nothing changes.

I don't know why this replacement fails. I would expect:

public FooBarCor
public GazBarKoz

If I set Bar to be replaced by ZZZ, nothing changes.

That is correct. Since there is no ZZZ on the right, the replacement rule is ignored (a logical replacement on the left would have no effect on the compare because the replacement text does not exist on the right.)

If I set Foo to be replaced by GazBarKoz, it changes the diff so that the BarCor appears deleted on the left.

Not deleted. BarCor is displayed as an unmatched difference on the left:

public FooBarCor
public GazBarKoz

Since Foo has been logically replaced with GazBarKoz during the compare, Foo on the left equates to GazBarKoz on the right. This causes the BarCor on the left to have no matching text on the right.

[Michael Kujawa]

(That's what I meant by deleted.)

In the second example, I was testing what would happen if a replacement would make a diff worse--to see if replacements would add false diffs. They don't and that's good.

I also expected the first and third to have similar behavior and was surprised when they did not. So I either don't understand what replacements are supposed to do, or I found a bug. Thus the request for clarification

Just as a guess, it seems like replacements always start at word boundries?

[Kelly]

Thanks for the clarification that the replacement only occurs on the left. My problem is that any of a hundred page numbers referenced in the text, are different on the left and right and I can' predict what they would be on the right.
Example:
left: for more information see page 4-10
right: for more information see page 4-11

I was hoping that the replacement would apply to both sides and I would end up with something that looks like:
for more information see page n-n.

[Chris]

You can try just marking page ranges as unimportant text with a regular expression. In your above example, you can use a regular expression like "page \d+-\d+". The \d+ means one or more decimal characters.

[jdmarch]

I would like to be able to have "Replace with" empty string, so that I can ignore places where I don't care that a given word was omitted. When the "Replace With" field is empty, the OK button is disabled.

As a workaround, I used a regular expression
Word(.) replaced with $1
but simpler would be nicer IMO.

Thanks.

[Erik]

Replacements only happen if the text to find occurs on the left and the replace with occurs on the right at an appropriate position. The replace with has to exist for this to work.

A way to do what you're describing is to create a grammar item and make it unimportant.

[jdmarch]

I must be missing something, because I don't see how it's any harder to "replace" (for matching purposes) a string with nothing than with something,

Specifically why is it harder to match
<A><B><C> with <A><C>
than it is to match
<A><B><C> with <A><D><C>
?

I.e. why do you need to disallow the special case where <D> is empty?

[Erik]

A replacement only works if "Text to find" (ex. apple) exists on the left and "Replace with" (ex orange) exists on the right. This means that "apple" on the left can match with "apple" on the right, or it can be similar to "orange" on the right. What you're looking for is to make "apple" on the left unimportant, which is what the grammar is for.

Replacing "ABC" with "AC" is just as easy as replacing "ABC" with "ADC". However, this is not the same as replacing "B" with "". This requires finding the empty string on the right side which doesn't make sense. FYI, your workaround (replacing "B(.)" with "$1") will only work if "B" is followed by at least one character.

[jdmarch]

Thanks for clarifying, Erik.