From 469c0441635b04fb56b0b5819a397b947c897554 Mon Sep 17 00:00:00 2001 From: "Adam T. Carpenter" Date: Wed, 13 May 2026 20:39:49 -0400 Subject: post: vimdiff --- posts/2026-05-13-vimdiff.php | 91 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 posts/2026-05-13-vimdiff.php diff --git a/posts/2026-05-13-vimdiff.php b/posts/2026-05-13-vimdiff.php new file mode 100644 index 0000000..a9f117f --- /dev/null +++ b/posts/2026-05-13-vimdiff.php @@ -0,0 +1,91 @@ +

Using vimdiff for editing fiction and revision tracking

+

I’ve been on a story writing kick for about a year now. Actually, one +of my goals this year was to write at least one short story per +month.

+

Aside: so far I’m doing pretty good, I wrote four stories in January +and another in March. I’m also working on a serial web fiction!

+

Anyway, one of the things that I think a lot of writers will need to +deal with at some point is editor revisions. Not that this is a bad +thing, I’m very thankful for the awesome folks at Nat1 Publishing for +giving me feedback. Their edits always make my writing better and I’m +learning a lot.

+

Now that I’ve stated the obvious, I have one workflow gripe. That is +they require Word documents (.docx) for submissions. Now I write +everything in vim, format it with Markdown, track it with git, and +that’s that. Plain text all the way. When someone wants a Word doc or a +PDF, I just Pandoc it away into the format they want and ship it +off.

+

Normally this is plenty fine, everybody is happy. But when I get +edits back, almost always the changes are tracked in Word’s change +tracker. The LibreOffice Write equivalent would be the Compare Document +feature.

+
+

+ +

+
+

+

So for a few stories now I’ve gone through the process of opening up +LibreOffice, comparing documents, and then stepping through the changes +one at a time, accepting or rejecting what was there. Sometimes I make +edits which combine the two changes. It’s a bit cumbersome because +Write’s keyboard shortcuts aren’t that great for this feature. I also +don’t have Word on my swanky new Commodore OS Vision, so the clicking +continued.

+

Until I realized I’m basically using LibreOffice as a merge tool. +That gave me the idea that I really don’t need to use Write at all, I +just need another translation layer.

+

What I did was convert the .docx I got back from the editors into +markdown with Pandoc. Pandoc is really good at handling things like em +dashes with its own flavor of Markdown, so this wouldn’t be a +problem.

+
pandoc -o stardust_edited.md stardust_edited.docx
+

Then I made a copy of my original story and called it “final.” Now I +could use both files in vimdiff to track my changes.

+
vimdiff -o stardust_edited.md stardust_final.md
+
+

+ +

+
+

+

This might surprise strangers to vimdiff, but all of the same tools I +was using in Write were already available. Only now they were better for +a couple of reasons.

+

First, vimdiff supports a two-pane view with the editors’ copy on top +and my original (now final) copy on the bottom. Blocks of text with +modifications are highlighted magenta, while the actual changed +characters are highlighted red. This makes it really clear what’s mine, +what’s theirs, and what the final result (un-highlighted) will look +like.

+

Second, and most importantly, I get to use vim’s diff mode +keybindings. ]c jumps to the next change while +[c jumps back a change. dp will push the +currently highlighted change into my final copy, while do +will reject it, or place my original change into the editors’ copy.

+

This let me move through the document much faster with tools I’m way +more comfortable with. When I was finished, I just used Pandoc to turn +the final draft back into a .docx and sent it to the editors. I gave it +a final read just to make sure I didn’t miss anything in the conversion, +but there wasn’t anything really special about the formatting.

+
+

+ +

+
+

+

And there you have it, easy vimdiff change tracking for when people +send you Word documents. About the only thing this doesn’t get me is +comments, and for that LibreOffice hangs around on my install. Maybe +there’s a way to extract the comments and associate them with lines in +the resulting text. There are some projects, like this one +which are designed to extract comments as a Pandoc plugin. I’m sure it +could be worked into this solution, maybe with a nice script to tie it +all together. But that’s for another time.

-- cgit v1.2.3