Come to me, Superplague! I defy you!

Every winter, half the office gets taken out by illness. We call it “the Super Plague”, “the Creeping Crud”, “the Plague of Death.” It’s brutal.

Yesterday, I woke up feeling the tell-tale signs. Scratchy throat, low energy. Uh-oh.

But today I woke up feeling… totally fine! One hundred percent! Yes my friends, the famous Goer immune system, the same one that ensured the survival of prehistoric Goers, kicked in… and kicked ass.

So this is my post where I dance in the endzone, taunting the entire Team Virus defensive line. In your FACE, Team Virus! In your face!

Publishing in Standard Manuscript Format with Sphinx, reST, and Sffms LaTeX

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.


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, 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 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!

Counter-intuitive Thinking on the Battleship Movie

Hoisted from comments in $social_network, a friend of a friend says:

“And for what it’s worth, when it come to the Battleship film, I have a sneaking feeling that it’ll be a stormer. Look at this way: producer and director go into film exec’s office and starts by saying ‘look, we’ve got this idea to turn Battleship into a film, and it’ll star Rhianna.’ You’ve got to imagine that the rest of this pitch must have been of Godfather dimensions not to have been kicked into touch after that opening sentence…”

“Look, we’ve got this idea to turn the Pirates of the Caribbean ride into a film, and it’ll star Orlando Bloom.”

“Look, we’ve got this idea to turn…”

… and, actually, I’m out. Still, an intriguing theory.

How Does Scott Adams Do It?

It’s hard to understand how he does it. Scott Adams hasn’t worked as an engineer since when? The 70s? The early 80s? And yet even after all this time, he is still able to write cartoons that are pitch-perfect.

The only real explanation I can think of is that tech industry bullshit is so conservative and formulaic that even if you happened to master its syntax thirty years ago, you can plug in new buzzwords today and sound completely up-to-date.

That just raises the question — does all industry bullshit work like this? Is fashion industry bullshit today the same as fashion industry bullshit from the 70s? Or do different industries have wildly different bullshit mutation rates?

As an aside, is it just me or does Dilbert really match the color scheme of the site really well? I should start embedding these things more often.

HOWTO Fix a ‘Mail has undone actions’ IMAP error

When using OS X Mail on Leopard with IMAP, it is possible to get into a bad state with respect to the server. When this happens, Mail will start displaying an extremely-hard-to-dismiss dialog that resembles:

Mail has undone actions on some messages so that you can redo the actions while online.

Additional information: The IMAP command “UID COPY” (to Deleted Items) failed for the mailbox “Junk E-mail” with server error: Command Error. 10.

For the benefit of the entire Internets, here is the solution.

  1. Close

  2. Open a terminal and cd ~/Library/Mail/.

  3. In this directory is a subdirectory that is called something like IMAP-youremail@yourmailserver. (Or if you’re living dangerously and/or stupidly like me, Exchange-youremail@yourmailserver). cd into this directory.

  4. cd .OfflineCache/ and rm everything in this directory.

You’re welcome!