My final words on Manuskript

I no longer use Manuskript. Between the usual problems of keeping a steaming pile of Python working on both my platforms of choice, and the Manuskript/QT problems where chapters *disappear* if you move them around in the chapter list, I gave up. I had to restore data too many times by using dropbox's rollback function, and once more by resorting to my NAS backup. I stopped using it for my current writing.

However, I am in the final throes of getting "Ask the Dust", formerly known as "The Silent Dust," ready to publish, so I figured I could at least use the compiler in Manuskript and add the pieces I needed to the novel to get it ready for printing.

It lost data on me again.

It lost a whole *scene* silently. I nearly went to press with the first scene of a chapter unceremoniously hacked out.

Worse, I got into a discussion amongst the developers. Apparently the guy who runs the project was rejecting pull requests (new code contributions) because they had too much documentation in the code.

Say what?

I was assured that most of the code was "Self documenting" but there was code that needed special explanation.

That would have gotten you an F in the computer science I was taught. To my ears, it translated to "I don't know what I'm doing." This made me cringe for my data safety. Am I being unfair? Has computer science perhaps moved on since 1986, when I first studied it at the college level? Undoubtedly. Still. It's a problem for *me*.

I've poked around in the code a little, mostly to try to understand what the compiler was actually doing. It's not like it's documented *anywhere* that I could see. I finally wrote a bash program to have it masquerade as pandoc and tell me what flags were really being sent. Here's what the mighty Manuskript compiler really does, albeit not in any particular order:

1. For document file in the project, push every heading tag down one level. Basically find every # tag (how markdown spells <h1>, and add an additional # to it, so the <h1> becomes an <h2> and so on..

2. Pull the chapter name from the custom metadata for each markdown document and put that in as the top level heading. (The <h1> equivilent.)

3. Add a blank line at the end of each markdown document.

4. Concatenate all the modified markdown documents into one big document.

5. Call pandoc with a bunch of flags and feed it the one big document.

It's not exactly rocket science, and it's the only piece I've not been able to replicate with other software. (Mostly vscodium (the Microsoft-free version of Visual Studio Code) with lots of plugins.) You could do it with some bash scripting, a makefile (probably, although my make-fu has become weak). I settled (because I was in a hurry) for using the Manuskript compiler to produce just the combined markdown file, fixing a bug in that file, and throwing it into Pandoc from a bash script, and this was *still* easier and more robust than letting Manuskript do it.

 Wait, I hear you say. What about Manuskript's outlining, character database, world database and so forth and so on. You can't do *that* with vscodium.

You're right. That's a job for a wiki. In fact, I use Smeagol-wiki (A tiny little rust wiki server) for exactly that. And a web browser. And a bit of Go code I put together to build the index files in my wiki automatically, because the files change a lot. You can get smeagol here: https://smeagol.dev/, and my make_index program here https://github.com/jrstrick/Make_Index-for-Smeagol-Wiki (You'll need to install Go to build it though. Working on that.)

I think this vast and disparate architecture, even without Python and QT, is the real problem underlying Manuskript. Like Scrivener, it needs to be a suite of tools rather than one big tool that does the whole thing in one (tabbed) window. I think they've got an awful lot of code to maintain, and I've read (from the developers list) that it's horrifically intertwined with QT, so separating the QT horror out and replacing it with something better—if such a thing can be said to exist. Don't get me started about Linux GUI libraries—has proven very, very difficult. I know that Python, by itself, does not make software bad. I use FreeCAD, I use Blender, and probably a dozen other things I don't even know are python every day. But I think python plus QT plus embedded Chromium plus making a program that does too many different, non-trivial things probably is.

I wanted to love Manuskript. Here was an open source replacement for Scrivener. It worked. Writing fiction in markdown has been a godsend. But I can't love software that loses my data. I can't love software that dies every time I upgrade my system and the python environment gets changed out from under it. I can't love a wordprocessor that is so resource intensive it won't run well on a Raspberry Pi 4 with 8 gigs of RAM. I can't love Manuskript as it is, and because it's in python, I can't even try to fix it.

So. No more Manuskript for me. I don't see this changing.

btw: the my current vscode/vscodium addon stack is this: LTEX-LanguageTool grammar/spell checking, by valintįn, Markdown Fiction Writer by vsc-zoctarine, Markdown Links by tchayen, Marky stats by robole, the standard pandoc markdown syntax addon, Simple Markdown Header by sguerri, Markdown Preview Mermaid Support by bierner, Markdown Table by Takumil, and Text Toolbox by carlocardella.  Markdown Fiction Writer even has a compiler, of sorts, although it's pretty awkward to use for large scale documents. You may have to download Markdown Fiction Writer separately from the microsoft addon store (it's free) if you're using codium. I'm unclear why, but that's what worked.

 

I use vscodium for writing, because I have an entirely different addon stack in Visual Studio Code, that I use for, yanno, writing code. Yes, I know about profiles, I just don't do it that way.