Friday, December 16, 2022

Manuskript, Again

So I've written a novel in Manuskript. Sixty-two thousand words later, I think I'm in a position to talk about it a little more authoritatively.

The good:


Manuskript is reasonably stable. It crashes from time to time (I had a poorly behaved font, which I think was the underlying cause) and I've yet to lose data, unlike Scrivener, although there was a close call, and I had to renumber all the scenes in The Silent Dust's metadata at one point to fix a crashing corruption of the file. At least I could.


Markdown turns out to be a delight to write in. Not only is it faster than type/select/shape and the styles horror of WYSIWIG editors, it's machine readable. This means that Pandoc can translate my novel into an ebook or typeset it in LaTeX right now, at least, once I get the templates set up. I can also translate the novel into a perfectly acceptable .docx file so the folks in my writing critique group (Armadillos! Yay!) can comment on it easily. Do I have to apply the changes to the novel manually? Yes.



Manuskript runs equally well on my Mac and my Linux box. It runs adequately on my Raspberry Pi 4, more on that later.


Familair Workflow:

If you came from Scrivener, Manuskript will be familiar to you. Folders of folders with scenes in individual documents at the deepest level. Compile the documents to their final format. 

Human-readable files

If you've used Microsoft Word, or any of the other WYSIWYG editors, you know that getting text out of a word processor format into another format can be very painful. Even Microsoft isn't consistent from their mac .docx files to the windows ones. Libreoffice does better, and Pandoc is fairly brilliant about translating from one format to another, but I'm tired of dealing with silly proprietary formats that hide all the formatting and make such a mess of it. This started in the 1970s with Wordstar, and it's been downhill ever since.

Open Source:

At the very least, you should always be able to grab a copy of Manuskript and open your files. There's no company that decides to turn your favorite word processor into a 'software service', or simply go out of business. I've had both. Done with that.


Best in Breed:

For what it does, Manuskript is the best software out there. It's as good as Scrivener, arguably more stable than Scrivener has been historically, and it runs on all my platforms. And it's free.


The good ideas, poorly implimented:

Side Data: Manuskript has ways to store character sketches, world information, timelines, all kinds of stuff like that. Unfortunately, each one is stored in a different format, and there's no way to make a global set for a series of books. It desperately needs a database behind it, and it hasn't got one. 


The editor:

Text editors are hard. I get it. But for reasons unknown, the Manuskript editor will, after a while, lose its ability to select a point in the text. Inserts are done at the end of the file, and cut and paste doesn't work at all. This is maddening.


Search/Replace: The search function works. It's a new addition, and it's ok. I'd like to be able to select between local (this document) and project-wide, but I can't. There is no replace. The easiest way to do search and replace in Manuskript is to save the file to the un-zipped version of the file format, and open the directory that results in MS Visual Studio Code, which has a brilliant global search and replace. I fear for the metadata every time I do that, however.


The Compiler:

Great idea. Gather the files and feed them to Pandoc. But there's no way to feed only one scene to Pandoc, nor can you easily pass flags to Pandoc. If the file format you want to compile to isn't already in the compiler's menu, you're on your own, more or less.


The Bad.

File Format: 

Oh God, the file format. Hidden away in the neat .zip file is a dog's breakfast of markdown files, JSON, YAML, XML, and heaven only knows what else. Metadata is scattered all over the place. You can get at everything, and none of it will make a basic text editor choke, but it's a mess to try and piece things back together if something breaks. Been there, done that.



The metadata system is, to be charitable, not Manuskript's strongest suit. Even the order of chapters or scenes in chapters is stored in metadata, and if that one number gets corrupted, two documents can wind up with the same order number. If they do, one or both of them will disappear.



If you look at how Manuskript works, it's really a web app running through a QT webview. While I get it, this makes it  whole lot easier to render markdown as rich text/html, and it handles all the really messy issues of text shaping, layout, font handling, and so on, it also means that you have a titanic binary blob that is almost a whole web browser. This murders performance on Raspberry Pis, and the damn thing isn't stable. One misbehaving font should generate errors, maybe even make a document unreadable. It should not crash the entire application every time you change the margins. News flash, it does. 


Manuskript has a versioning system. They recommend right in the instructions that you not turn it on. So I haven't.


I've been fairly vocal in my disdain for Python over the years. Yes, part of this is ignorance—I don't know Python at all. Part of it is that the idea of whitespace in a program having programmatic meaning makes me itch. Yes, I know there are special editors that take care of that for you. My point is it shouldn't exist. The big problems with Python in this case are 1. It's slow. Manuskript is somewhat marginal to use on a Raspberry Pi 4 with 8GiB of memory. This is embarrassing. Python is also very much a second-class citizen on the mac, where Apple dutifully breaks the python environment routinely. Just getting Manuskript running on the mac sometimes takes me hours. I see in the pull requests on the Manuskript github repo that they have someone doing a proper MacOS build with a proper bundle and everything, but it isn't in the distributions yet.

Best in Breed:

There are so many good ideas in Manuskript, and so many markdown editors out there are nicer and more stable but are missing functionality I use every day that it's very frustrating.



I'm starting another novel in Manuskript. It's good enough. It has its foibles, as I've tried to make plain above, but as I've also said, it's the best in breed for novel writing, as far as I'm concerned. Does it frustrate me terribly at times? Yes, yes it does. 


Am I dusting off my programming skills to try and write something better? Yesss, but nobody should hold their breath on that ever being finished. I have a language, a gui library, and a database picked. That's it so far. 

Mostly what I've accomplished so far is to become much more in tune with how big a project this is, and how hard some parts of it are. Also that I haven't seriously studied code in over 30 years, and GUIs are a pain in the ass to write code for. I've picked on Manuskript a lot in the text above, and I think I'm being fair. That said, I used it anyway, and will continue using it anyway for the foreseeable future.

No comments:

Blog Archive