The Devil's Advocate's Versioning Quandary

Topic split, at Keith’s request. What thoughts have you?

There’s a similar problem in software development.

One of the most powerful ways of understanding a complex system during the early stages of development is to draw diagrams to describe it. They make it easier to comprehend a system in its entirety. These diagrams are useful at other stages too, like testing.

There are a number of techniques that take diagrams and generate code. The problem is the same now as it was fifteen years ago when I first encountered these techniques: the diagrams get out of sync with the code that’s generated, which makes them less valuable for understanding the system because they are wrong.

The problem has not been definitively solved. I’ve worked on a few products over the years that have tried to address the whole business of keeping diagrams up to date with the code, and updating the code to match the changes made to the diagram, and there are always corner cases where something will break - usually disastrously.

At least in writing the best solution is at least practical: use the technique which janra describes of always making changes in the source document and regenerating the result when needed.

… but there are always changes which need to be made in the result. If there are a lot of them and they need to be done manually, then that is going to cause problems. Chapter numbers are my bete noir, and I need to look at MMD more closely for exactly that reason.

If Keith finds a bug in Scrivener. Let’s assume it’s nothing serious; he’s spelt ‘NO’ incorrectly on the feature request dialog box for example. Now he has two choices in how he goes about fixing it.

1/. He can take the tedious option of finding the error in his source code, fixing it then recompiling it into a binary file.

2/. He can open the binary up in a hex editor, search for the offending spelling mistake and and then change it. No need to recompile.

Now which is the better option? Here’s a hint; I’ve seen programmers fired for going with the number 2 approach.

The Scrivener project is the ‘source code’ for the book; which it uses to generate the output. Dunno about anyone else, but I wouldn’t have the finished book and the Scrivener project fall out of step, for much the same reason that I don’t hack binary files to fix software bugs.

That’s the geeky perspective anyway.


That can, Jekyll & Hyde-like, be either a Typesetting Machine (this is how I think of Word) or a Writing Machine (which is Scrivener.)

Is there a way Word files, with page breaks (the easiest and most likely way to break sections) can strip out all formatting… except that?

Not likely.