post: vimdiff

1 files changed, 91 insertions, 0 deletions

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 @@
+<h1>Using vimdiff for editing fiction and revision tracking</h1>
+<p>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.</p>
+<p>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!</p>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<figure>
+<p>
+<img
+src="https://nextcloud.53hor.net/index.php/s/rZMSscgxYDfKZT7/preview"
+alt="Write compare document" />
+<figcaption aria-hidden="true">Write compare document</figcaption>
+</figure>
+</p>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<pre><code>pandoc -o stardust_edited.md stardust_edited.docx</code></pre>
+<p>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.</p>
+<pre><code>vimdiff -o stardust_edited.md stardust_final.md</code></pre>
+<figure>
+<p>
+<img
+src="https://nextcloud.53hor.net/index.php/s/YkRbbM64Lzx67w7/preview"
+alt="Vimdiff" />
+<figcaption aria-hidden="true">Vimdiff</figcaption>
+</figure>
+</p>
+<p>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.</p>
+<p>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.</p>
+<p>Second, and most importantly, I get to use vim’s diff mode
+keybindings. <code>]c</code> jumps to the next change while
+<code>[c</code> jumps back a change. <code>dp</code> will push the
+currently highlighted change into my final copy, while <code>do</code>
+will reject it, or place my original change into the editors’ copy.</p>
+<p>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.</p>
+<figure>
+<p>
+<img
+src="https://nextcloud.53hor.net/index.php/s/a3nCNEeBAiEG4s7/preview"
+alt="Final draft" />
+<figcaption aria-hidden="true">Final draft</figcaption>
+</figure>
+</p>
+<p>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 <a
+href="https://github.com/qq3g7bad/pandoc-comment-extractor">this one</a>
+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.</p>