Editing Scrivener ‘Sync’ files

Do you use Scrivener? If so, and you’d like to edit your Scrivener files on another platform such as your iPad, I may have something that will help. I’ve made some ‘bundles’ and themes for the TextMate editor and the Textastic editor on the iPad that display inline annotations, comments and block-quotes in the text. I’ve included some mark-up, too, for some common grammar problems.

I’m writing a centennial history of the International Chamber of Commerce in Scrivener. It’s a moderately large non-fiction book (about 115k words, at present… too long, already). There are some 90 manuscript files in the Scrivener database: called the ‘Binder’ in the Scrivener interface. There are as many files, also in the Binder, that are outside the manuscript. These are notes, rejects, research etc.

I’m using Scrivener’s native RTF format for writing because my editors will want an MS Word file to work on. Scrivener’s main export routines order, format and ‘compile’ a Word document from my manuscript files. I back-up the Binder every time I close the program. But I’m also syncing (on close or save) the files in plain-text format to a folder on my DropBox account. This is a sort of extra backup. These text files are ‘synced’ because Scrivener reads them every time it opens (or when you tell it to) and incorporates any changes into its database.

The synced text files make it possible to edit your Scrivener manuscript using another computer and any text editor you like. When Scrivener is open, it’s looking at its own database not at the text-format sync files. So you can change them whenever you want without corrupting the Scrivener database.

Lots of editors can edit text files from your DropBox account. I’ve been using BBEdit (on my Mac) for years. No problems. But, for all its power, BBEdit is clunky in some specific ways. So I’ve moved over to TextMate 2 (alpha). I’m still uncertain about the switch because TextMate has had a troubled history.

Aside #1: The creator of TextMate tried to completely re-write his very successful first version. But he could not do it quickly or completely to his own satisfaction. The program lost a lot of market/attention-share. It seems to be back on track now as a public-domain program. But editors are the devil to write damned hard to maintain. No public-domain editor that I know of is first-class… except maybe the EMACS and Vim dinosaurs (and life is too short for more than a nodding acquaintance with them). I’m hoping that TextMate 2 will keep growing and will somehow survive and prosper as a public-domain program. But its too early to be confident.

Aside #2: My main gripe about BBEdit is that it has a very limited capacity for language grammars. In other words, it doesn’t offer much flexibility in displaying syntax markup in the editor. Sure, it comes packed with a very big bunch of syntax mark-up files. That’s fine if you use BBEdit as a code editor for a popular language. But if, like me, you use text-editors to write marked-up prose or if you want to write a grammar for an unsupported language, be prepared for agony, puzzlement, endless dicking-around and piles of frustration. I’ve tried. I failed. My other gripe about BBEdit is its carbon-looking window hardware and its generally clunky set of panels and dialogs. Improved recently, but …

Now TextMate excels at incorporating language grammars and stylesheets (‘themes’) that display selected syntax of the grammar. They’re sort-of-easy to compose (if you know regular expression grammar and you are comfortable with basic shell scripting and maybe with adapting/hacking ruby or python or perl scripts). There’s a built-in editor for the ‘bundles’ that contain the grammar files and the ‘themes’ that are used to colour the grammar. If you have a little CSS experience, the theme files that tie the grammar and the appearance together are not a big challenge.

How does this help with editing Scrivener files? Well, Scrivener uses a lightweight set of conventions to represent markup in its text-based sync files. For example, I’m using a conventional format in Scrivener for footnotes (actually, endnotes in my case) that puts them ‘inline’ in the text. They appear in the Scrivener window as grey-background ‘bubbles’ inserted in the text where the footnote/endnote reference marker will appear in the final RTF (or Word) document. This turns out to be a great way to write footnotes/endnotes because they appear to the author as a sort of parenthesis in the text (which is what they are in my book: endnotes are where the jokes and snarky stuff is located… as well as the reference citations, of course). In the synced text files these ‘inline’ footnotes/endnotes are represented by text enclosed in double braces; like this {{…}}. Inline comments or annotations are enclosed in double parentheses, like this ((….)).

I also have my own ‘markup’ in Scrivener. I have an RTF style for block-quotes whose indented, justified formatting is ‘preserved’ by Scrivener when it outputs its RTF files to Word. But there’s no special markup for your own styling in the synced text files that Scrivener creates. (I wish there were.) The only thing that distinguishes my block-quotes in the text files is the quote marks (“) that begin them on a new line and end them at the end of the line or, sometimes, just before the attribution information I include at the end of each blockquote. I enclose the attribution in brackets like this […].

So, all of my synced text files have some very simple markup of footnotes/endnotes, comments (that I use for glossary entries… let’s leave that for another time) and my ‘preserved’ blockquotes. Oh… and most footnotes/endnotes also contain a citation key for my bibliography software (Pages 2, at present. I’m ditching it as soon as I can. Probably for Bookends). A citation key looks like this: {Gallagher:xvr09}.

What I would like to do is to edit my Scrivener files in a text editor on computers where I’m not running Scrivener. I have Scrivener on my laptop, of course. But since I leave Scrivener running most of the time on my desktop computer (my main editorial station), I never open it on the laptop to edit the same project. That would confuse things. Scrivener (god bless it!) complains. So I edit the synced text-files on Dropbox, instead. BBEdit was fine. But one aspect annoyed me: the lightweight markup in the Scrivener text files was all-but-invisible in the text files. Without any visual clues, footnotes, comments and block-quotes looked pretty-much like the rest of the text.

It was the same on the iPad. Sometimes I’d like to spend a few otherwise-wasted half-hours (on trains, at airports, or stuck in dreadful committee meetings) editing the synced files on my iPad. It certainly has the stuff to do so. Dropbox editors are legion on the app-store. Many can handle the simple text of the synced files without a problem. But, as with BBEdit on my laptop, most of them don’t permit flexible markup of language grammars.

I did two things. First, I (re)started using TextMate on my laptop. I wrote my own (very lightweight) grammar file for the Scrivener text-file format. I also created a ‘theme’ file to display the syntax of these grammars. For example, the text of an inline footnote/endnote (defined as text between {{ and }}) is keyed via its name (‘meta.inline.footnote.text’) to a specific background colour (a sort of light grey) and font style (‘italic’) in a theme file associated with the grammar. The theme file I created is called “Nuage”. The grammar is embedded in a TextMate ‘bundle’ that I call “Scrivener-text”. When I choose to apply that bundle to a text file, I can also choose to apply the Nuage theme. TextMate remembers the kind of file and its location and re-applies the same bundle and theme to similar files thereafter. Now, every time I open one of the Scrivener text files from the Scrivener directory on DropBox, TextMate applies the right language grammar and theme file. I see all my footnotes distinguished in the text in an italic (acutally, slanted) font and with a light-grey background. I have different markup for comments and for block-quotes.

As for the IPad… I use the very capable and flexible Textastic. This is a mature text editor comparable in scope — on the iPad platform — to BBEdit on the OSX platform. (There is also an OSX version, but I’ve never used it). Best of all, it will import TextMate language grammars (in TM ‘bundles’) and theme files. So I can use the same markup on my Mac laptop and on my iPad. Textastic also syncs its files to DropBox. So I can edit the marked up text using colored syntax and it will automatically save (without the coloring) as a text file to DropBox in the form that Scrivener expects.

But WAIT! “That’s not all!” ™ I like to keep my writing clear. I want nouns and verbs to do the work. I don’t want to rely on weasely adverbs to fix-up weak verbs. I don’t want to write in passionless passive voice with no subjects to take responsibility for the action. Nor do I want to make simple editing errors like repeating one of the the words in a phrase accidentally when I move things around with cut-and-paste.

But I’m prone to do all of those things. Without even noticing.

So I have added a few tricks to my grammar file for Scrivener that, in combination with the Nuage theme file, highlight the most common mistakes I make. I stole the implementation of this idea from the “English” bundle which is itself a replication of three nifty little Shell scripts by Matt Might. Now my passives pong in red; my weasel words writhe in greeny-yellow; my double-ups display in orange. Hoorah!

A screen shot of Textastic (iPad) editing a Scriv-text file

A screen shot of Textastic (iPad) editing a Scriv-text file

So… if you use Scrivener, Textmate and Textastic… allow me to offer you (without any guarantees, warranty-against-damage or after-gift-support) my current version of the ‘Scrivener-text’ bundle for TextMate 2 (haven’t tried it with TM1.x) and the “Nuage” tmTheme file (for use in TextTastic) and the ‘Nuage’ bundle (that will install the theme in TextMate 2).

Installing the TextMate bundles is easy. Click on the downloaded files. They should install themselves. If not, copy them to Users/[your-user-name]/Library/Application Support/Avian/Bundles. The installation of the bundles and theme file in Textastic is also very easy. Download the files to the special #Textastic folder that you create in the side-bar of the Textastic editor. Restart the program. Then point the style and language-grammar files at the file you’re editing. (I’ll leave you to consult the Textastic help file for the details of how to do that.) The result? You should be able to edit syntax-coloured, marked-up Scrivener sync files anywhere.

Download: After all that, here’s the link to a zip file of my Scrivener-text bundle, the Nuage bundle (for TextMate) and the theme file (for Textastic on iOS).

No Comments

Leave a Reply

Your email is never shared.Required fields are marked *