Although it’s the Year of our Lord 2011, and we are blessed with no end of advanced publishing technology, many fiction writers practice their craft something along these lines:

1. Open Microsoft Word or Libre Office.
2. Type some stuff.
3. At the end of the writing session, click “Save As” and save your file as "Title_of_Story Todays_Date.doc"
4. Occasionally, when you remember, burn all your story files to a CD.

Some writers are a little nerdier. They might use a specialized writing tool such as Scrivener or Ulysses. They might have automated backup set up. Or they might use an online word processor such as Zoho Docs and Google Docs which provide “free” offsite storage and version control.

But what if you’re a really nerdy writer? Nerdy enough to want to author in an open plain text format? Nerdy enough to want to check your files into a real version control system? Nerdy enough to run diff and sed and perform other text-munging feats of strength?

It all sounds promising, but there’s one major obstacle standing in your way: Standard Manuscript Format. Double spaced, 12pt monospace, one-inch margins, a running header with the author and title, you know the drill. This exacting print-ready format is easy to produce with a word processor, but if you want to stay outside of that world, you’re in for some serious pain. So what to do?

• Give up and use Word.
• Wait for the current generation of publishers and editors and all the people they have trained to die.
• Other.

I choose… “Other!”

Using Sffms

When it comes to exacting typesetting, nothing beats LaTeX. And it just so happens that M. C. DeMarco has designed a LaTeX document class named sffms that outputs Standard Manuscript Format.

DeMarco has documented sffms to the point where you can use sffms without actually knowing much about LaTeX itself. There’s a bunch of config-y header-y stuff at the top of the file. Paragraphs look like paragraphs. Occasionally you need to add a special command like chapter{In Which Stuff Happens} to create a chapter break, or emph{Look out!} for emphasis. You run the thing through latex and then pdflatex, and out comes a beautifully typeset manuscript complete with wordcount. You have to watch out for reserved LaTeX characters, but quite honestly, authoring a story in LaTeX is easier and cleaner than, say, hand authoring the same thing in HTML. It’s all quite civilized.

The one wrinkle is that the LaTeX toolchain really only works for print. All the TeX to HTML conversion tools I’ve tried are ancient and horrible. They’re particularly bad with sffms, which has some differences from a “normal” LaTeX article that trip up the ordinary HTML converters.

So if all you want to do is submit manuscripts to publishers, you are golden with LaTeX and sffms. But if you want anything even remotely reasonable to post to the web, you’ll need to roll your own converter. Or read on.

Using Sphinx and reST

LaTeX is a great technology. But for a humane plain text format that converts nicely to HTML, we have to move forward in time a couple of decades. reStructuredText (aka reST) is a lightweight markup language developed by the Python community for technical documentation. Sphinx is a builder tool that transforms reStructuredText into different target output formats.

The nice thing about authoring in reST is that the source files are even cleaner-looking than LaTeX (let alone an angle brackety language). Paragraphs are paragraphs. Chapter headings are titles with underlines. Emphasized text is text surrounded by asterisks. Even if the entire Python documentation toolchain disappears, even if you’re looking at your story’s source files decades from now, your work will still be perfectly readable as plain text.

For the fiction writer, what Sphinx brings to the table is solid, easy to use HTML production. If you don’t like the built-in HTML templates, it’s straightforward to hack your own. Sphinx also produces EPUB out of the box, as should all writing tools worthy of your consideration. So to recap: reST is a really nice source format, while Sphinx provides you with lots of power and control over how the HTML and EPUB output looks. Looking good so far!

Sphinx also produces LaTeX output. The problem with Sphinx’s LaTeX output is that — surprise! — it’s designed to typeset a nice looking technical manual, not a novel. The results look nothing like Standard Manuscript Format. Ah, well.

But wait a second:

1. sffms LaTeX is designed to typeset documents into Standard Manuscript Format… but its HTML output is unacceptable.
2. Sphinx and reST have great HTML facilities… but its LaTeX output is unacceptable.

Hmmm…

Someone Got sffms Peanut Butter in My reST Chocolate!

So it turns out that it’s not terribly difficult to write a Sphinx extension, even if you are a Bear of Very Little Brain who hardly knows a lick of Python. Now available for public consumption: the sffms Sphinx extension. And yes, the source code is available on github.

To use this extension:

• You must be able to install LaTeX with the sffms document class included.
• You must be able to install Python and Sphinx.
• You must be comfortable editing configuration files and running commands on the command line.

There is also very little documentation other than some comments in example files (though I’m working on that). In other words, this extension is for software engineers who also like to write fiction. Preferably software engineers who have used Sphinx before, and who have lots of patience.

You don’t have to be familiar with the sffms LaTeX class, but reading DeMarco’s original documentation might help you wrap your head around what sffms actually can do. My extension currently exposes almost all the knobs that are available in the sffms LaTeX class. For example, you can set sffms_frenchspacing = True in your Sphinx conf.py, which injects a frenchspacing command in the resulting LaTeX output.

If you want to kick the tires, here is a sketchy outline of what to do:

1. Install LaTeX with the sffms LaTeX class.
2. Verify that you can run latex successfully on one of DeMarco’s example stories.
3. Install Python 2.x (if necessary), followed by the Sphinx and sffms Python packages.
4. Verify that you can do a vanilla Sphinx doc build. You can use sphinx-quickstart to create a test Sphinx document. Try creating a PDF manual of your test document.
5. Download the skeleton short story and skeleton novel from GitHub. (These artifacts are not currently included in the sffms package itself, but they should be).
6. cd into one of the skeleton directories and run sphinx-build -b sffms . _build.
7. cd into _build/sffms and run latex index.tex — twice.
8. Run pdflatex index.tex. View the resulting PDF.
9. Go back to the story directory and start playing around with the Sphinx conf.py file. The configuration file contains all the available sffms configuration options with comments. The file also contains some minimal options for Sphinx in general. These other options are uncommented and you can ignore them if you are just working with sffms LaTeX output.

The next order of business is to write some real documentation. Beyond that, I welcome any bug reports or suggestions for feature enhancements. I am neither a professional programmer nor very experienced with Python, so any help you can provide would be very… helpful. Thanks!