Collaborative Document Editing with svk
Pages: 1, 2

Merging Changes

Suppose that after some hard work, you have finished the translation. Someone has revised the original text to fix some wording:

Translating documents is really hard work and you deserve a better
tool.  The tool should be able to tell you which part of the original
text is updated, so you could adjust the translation accordingly.

The first line didn't change.

To bring this change to the translated version, use sfk's smart merge:

% svk smerge -C //articles/article-en.txt article-zh.txt
Auto-merging (3, 5) //articles/article-en.txt to //articles/article-zh.txt
 (base //articles/article-en.txt:3).
C   article-en.txt
New merge ticket:
 8712955e-75da-0310-a94d-be098d1d806e:/articles/article-en.txt:5
1 conflict found.

The smart merge command finds the last merge point automatically, so you don't have to worry about those funny revision numbers above. In this case, for the first time a merge is performed, the merge base is the point at which you copied (or branched) the original file. Run the smerge command often to update and commit article-en.txt, as catching up with the original text frequently is easier than doing a huge update some months later.

The -C option here means to check what the smerge command will do. It has found a conflict. Run smerge again without -C, which makes modifications to article-zh.txt. You'll see the content like this:

Figure 1. Conflicts after a merge.

The first line, which you have translated and whose original text has not changed, remains there. The second part, as you can see, now consists of a marker for the conflict, which shows your version with the original text that the translation was based on and, finally, the new version of the original text.

In a document longer than just four lines, svk will merge all the other changes that you haven't translated into the latest version of article-en.txt. This saves a lot of time tracking and copying them.

Now you can proceed to update the translations in the file. It should be relatively easier, since you can read the changes made in the original text while modifying your translation side by side.

Before you can commit the file again, you have to mark the conflicts that svk just found as resolved:

% svk resolved article-zh.txt
/home/clkao/articles/article-zh.txt marked as resolved.

Why? Consider that you are using svk the usual way--managing source code. The funny conflict markers won't mean much to any compiler, and committing them will result in an inconsistent state where your software won't build. This is not the case for document translation! If you can't finish updating all those conflicts for now, it's rather convenient to commit the work in progress, leaving the conflicts there for resolution later. In the event that you've set up a Subversion server, other people in the same group translating the same document may be able to finish the merge easily. This makes collaborative translation possible.

Using Merge Tools

A few tools allow interactive merges like the one we did earlier manually. svk supports Emacs (EDiff), meld, and FileMerge.App on Mac OS X. You can easily call them as external merge tools for conflict resolution. We will use Emacs as the example here.

Find the svk-merge-emacs tool under the utils directory in svk distribution. Also remember to put svk-ediff.el in your emacs lisp directory.

The SVKMERGE environment variable controls the external merge tool:

% export SVKMERGE=svk-merge-emacs
% svk smerge //articles/article-en.txt article-zh.txt
Auto-merging (3, 5) //articles/article-en.txt to //articles/article-zh.txt
 (base //articles/article-en.txt:3).
Started 5427, Try 'kill -USR1 5425' to terminate if things mess up

The svk smerge command now waits for the external merge tool. An Emacs window will pop up in ediff-merge-with-ancestor mode.

Press $$ to ignore obviously merged chunks, as you likely care only about conflicts. Use the n and p keys to navigate between chunks that need merging. Press + to expand a chunk to combined mode, which consists of the base text:

Figure 2. Merging with Emacs.

Comparing the ancestor and variant B parts by eye is sometimes tiring. In that case, mark the ancestor text and press =b to compare it with the revised master text in buffer B:

Figure 3. Viewing detailed changes.

This should give you a clearer idea about what has changed. When you decide how to reflect the change in your translation, press a to load the translated text back into the merging into buffer, then update it.

If the paragraph has had a complete rewrite and is far different from the old one, press b to load the new version and translate it from scratch.

When you are done with all the chunks, press q to finish the merge session. svk smerge will finish the rest of the merge. You can examine the change you made to article-zh.txt with svk diff:

Figure 4. The updated translation.

Run svk commit as usual when you are satisfied with it.

Limitations of svk Translation

svk translation works best if there are markups between sections or paragraphs, as that makes it easier for external merge tools to find corresponding paragraphs.

If the original article moves paragraphs around, you will have to track them manually. You will see in the conflict marker that the moved paragraph becomes empty, and the new location with the moved text will have an empty base and translated text.

Conclusion

Using branch and merge in svk as presented in the article can apply to any other version control system that supports branching and merge tracking and, perhaps, external merge tools.

Translation is an extreme type of article editing. The concepts here can also apply to conventional editing. Make a branch for the article that you are proofreading. When the author sends an updated version, you can smerge the changes painlessly, retaining the modification you made, or vice versa.

Chia-liang Kao is the original author of svk and the Perl bindings for Subversion.

---

Return to ONLamp.com