Model-View-Controller

Because of how source control prefers text files over binary files, the process of writing while working with Git is considerably different.

The biggest difference is that there is a separation of the source text files verses the output. In Git, you commit only the source files along with the instructions on how to transform them into the output, but don't check the output itself.

In development, this is the concept of Model-View-Controller (MFC), which means there is a separation of the data (the content), it's presentation (EPUB and PDF), and the method for making changes to the content.

Model

The “model” of a writing projects are the various Markdown files, the individual images, and everything else that will be combined together to product the output.

It also includes instructions to create the output. In some ways, this is like a box of LEGO bricks and their booklet. The final output (say a large Spelljammer scene) isn't thrown in the box pre-assembled but instead has to be put together by a process (a human in the LEGO example).

Justifications

There are a couple reasons for this.

One, it is far easier to produce another output from the sources files as opposed to copy/pasting the output from a binary output. I've recovered too many books from a PDF in that manner and it isn't enjoyable.

Two, tools change. You might start using Pandoc to generate your books but then realize you need something else. With the source files present, it is much easier to manipulate the files to fit the new standards than retroactively change the EPUB or PDF to match.

View

The “view” in this analogy are the tools that are used to manipulate, query, or transform the source files. They produce the EPUB and PDF files.

These are also not checked in because they are specific to an environment (Windows cannot run a Linux or Mac program). They are also almost always binary files.

Unlike the tools themselves, we do check in the build instructions and configurations for the project. This includes the Justfile, build systems, or style files. This would also include MfGames Writing's publication.json file.

Reproducibility

Including the source files and the configurations is another “leap of faith” with this approach. Ideally, given a set of source files and a configuration, the tool will produce the same output every time. That isn't always the case with later versions potentially being slightly different with the occasional breaking change (extra page numbers).

To avoid these slight changes, the tools has various ways of picking only a specific version either with scripts, setup, or a “lock file” such as package-lock.json with ensures a consistent environment. This is also were NixOS becomes useful, but programs like asdf or other mechanisms are used to ensure a specific version even ten year later.

Controller

The third and final part of the MVC is the controller. Controllers are the processes that change the model. Being that our “model” are the source files, the controller is just a text editor such as Notepad++, VS Code, Neovim, or even more esoteric tools like Emacs.