Editing Scrivener ‘Sync’ files

Do you use Scriven­er? If so, and you’d like to edit your Scriven­er files on anoth­er plat­form such as your iPad, I may have some­thing that will help. I’ve made some ‘bun­dles’ and themes for the Text­Mate edi­tor and the Tex­tas­tic edi­tor on the iPad that dis­play inline anno­ta­tions, com­ments and block-quotes in the text. I’ve includ­ed some mark-up, too, for some com­mon gram­mar problems.

I’m writ­ing a cen­ten­ni­al his­to­ry of the Inter­na­tion­al Cham­ber of Com­merce in Scriven­er. It’s a mod­er­ate­ly large non-fic­tion book (about 115k words, at present… too long, already). There are some 90 man­u­script files in the Scriven­er data­base: called the ‘Binder’ in the Scriven­er inter­face. There are as many files, also in the Binder, that are out­side the man­u­script. These are notes, rejects, research etc.

I’m using Scriven­er’s native RTF for­mat for writ­ing because my edi­tors will want an MS Word file to work on. Scriven­er’s main export rou­tines order, for­mat and ‘com­pile’ a Word doc­u­ment from my man­u­script files. I back-up the Binder every time I close the pro­gram. But I’m also sync­ing (on close or save) the files in plain-text for­mat to a fold­er on my Drop­Box account. This is a sort of extra back­up. These text files are ‘synced’ because Scriven­er reads them every time it opens (or when you tell it to) and incor­po­rates any changes into its database.

The synced text files make it pos­si­ble to edit your Scriven­er man­u­script using anoth­er com­put­er and any text edi­tor you like. When Scriven­er is open, it’s look­ing at its own data­base not at the text-for­mat sync files. So you can change them when­ev­er you want with­out cor­rupt­ing the Scriven­er database.

Lots of edi­tors can edit text files from your Drop­Box account. I’ve been using BBE­d­it (on my Mac) for years. No prob­lems. But, for all its pow­er, BBE­d­it is clunky in some spe­cif­ic ways. So I’ve moved over to Text­Mate 2 (alpha). I’m still uncer­tain about the switch because Text­Mate has had a trou­bled history.

Aside #1: The cre­ator of Text­Mate tried to com­plete­ly re-write his very suc­cess­ful first ver­sion. But he could not do it quick­ly or com­plete­ly to his own sat­is­fac­tion. The pro­gram lost a lot of mar­ket/at­ten­tion-share. It seems to be back on track now as a pub­lic-domain pro­gram. But edi­tors are the dev­il to write damned hard to main­tain. No pub­lic-domain edi­tor that I know of is first-class… except maybe the EMACS and Vim dinosaurs (and life is too short for more than a nod­ding acquain­tance with them). I’m hop­ing that Text­Mate 2 will keep grow­ing and will some­how sur­vive and pros­per as a pub­lic-domain pro­gram. But its too ear­ly to be confident.

Aside #2: My main gripe about BBE­d­it is that it has a very lim­it­ed capac­i­ty for lan­guage gram­mars. In oth­er words, it does­n’t offer much flex­i­bil­i­ty in dis­play­ing syn­tax markup in the edi­tor. Sure, it comes packed with a very big bunch of syn­tax mark-up files. That’s fine if you use BBE­d­it as a code edi­tor for a pop­u­lar lan­guage. But if, like me, you use text-edi­tors to write marked-up prose or if you want to write a gram­mar for an unsup­port­ed lan­guage, be pre­pared for agony, puz­zle­ment, end­less dick­ing-around and piles of frus­tra­tion. I’ve tried. I failed. My oth­er gripe about BBE­d­it is its car­bon-look­ing win­dow hard­ware and its gen­er­al­ly clunky set of pan­els and dialogs. Improved recent­ly, but …

Now Text­Mate excels at incor­po­rat­ing lan­guage gram­mars and stylesheets (‘themes’) that dis­play select­ed syn­tax of the gram­mar. They’re sort-of-easy to com­pose (if you know reg­u­lar expres­sion gram­mar and you are com­fort­able with basic shell script­ing and maybe with adapting/hacking ruby or python or perl scripts). There’s a built-in edi­tor for the ‘bun­dles’ that con­tain the gram­mar files and the ‘themes’ that are used to colour the gram­mar. If you have a lit­tle CSS expe­ri­ence, the theme files that tie the gram­mar and the appear­ance togeth­er are not a big challenge.

How does this help with edit­ing Scriven­er files? Well, Scriven­er uses a light­weight set of con­ven­tions to rep­re­sent markup in its text-based sync files. For exam­ple, I’m using a con­ven­tion­al for­mat in Scriven­er for foot­notes (actu­al­ly, end­notes in my case) that puts them ‘inline’ in the text. They appear in the Scriven­er win­dow as grey-back­ground ‘bub­bles’ insert­ed in the text where the footnote/endnote ref­er­ence mark­er will appear in the final RTF (or Word) doc­u­ment. This turns out to be a great way to write footnotes/endnotes because they appear to the author as a sort of paren­the­sis in the text (which is what they are in my book: end­notes are where the jokes and snarky stuff is locat­ed… as well as the ref­er­ence cita­tions, of course). In the synced text files these ‘inline’ footnotes/endnotes are rep­re­sent­ed by text enclosed in dou­ble braces; like this {{…}}. Inline com­ments or anno­ta­tions are enclosed in dou­ble paren­the­ses, like this ((.…)).

I also have my own ‘markup’ in Scriven­er. I have an RTF style for block-quotes whose indent­ed, jus­ti­fied for­mat­ting is ‘pre­served’ by Scriven­er when it out­puts its RTF files to Word. But there’s no spe­cial markup for your own styling in the synced text files that Scriven­er cre­ates. (I wish there were.) The only thing that dis­tin­guish­es 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, some­times, just before the attri­bu­tion infor­ma­tion I include at the end of each block­quote. I enclose the attri­bu­tion in brack­ets like this […].

So, all of my synced text files have some very sim­ple markup of footnotes/endnotes, com­ments (that I use for glos­sary entries… let’s leave that for anoth­er time) and my ‘pre­served’ block­quotes. Oh… and most footnotes/endnotes also con­tain a cita­tion key for my bib­li­og­ra­phy soft­ware (Pages 2, at present. I’m ditch­ing it as soon as I can. Prob­a­bly for Book­ends). A cita­tion key looks like this: {Gallagher:xvr09}.

What I would like to do is to edit my Scriven­er files in a text edi­tor on com­put­ers where I’m not run­ning Scriven­er. I have Scriven­er on my lap­top, of course. But since I leave Scriven­er run­ning most of the time on my desk­top com­put­er (my main edi­to­r­i­al sta­tion), I nev­er open it on the lap­top to edit the same project. That would con­fuse things. Scriven­er (god bless it!) com­plains. So I edit the synced text-files on Drop­box, instead. BBE­d­it was fine. But one aspect annoyed me: the light­weight markup in the Scriven­er text files was all-but-invis­i­ble in the text files. With­out any visu­al clues, foot­notes, com­ments and block-quotes looked pret­ty-much like the rest of the text.

It was the same on the iPad. Some­times I’d like to spend a few oth­er­wise-wast­ed half-hours (on trains, at air­ports, or stuck in dread­ful com­mit­tee meet­ings) edit­ing the synced files on my iPad. It cer­tain­ly has the stuff to do so. Drop­box edi­tors are legion on the app-store. Many can han­dle the sim­ple text of the synced files with­out a prob­lem. But, as with BBE­d­it on my lap­top, most of them don’t per­mit flex­i­ble markup of lan­guage grammars.

I did two things. First, I (re)started using Text­Mate on my lap­top. I wrote my own (very light­weight) gram­mar file for the Scriven­er text-file for­mat. I also cre­at­ed a ‘theme’ file to dis­play the syn­tax of these gram­mars. For exam­ple, the text of an inline footnote/endnote (defined as text between {{ and }}) is keyed via its name (‘meta.inline.footnote.text’) to a spe­cif­ic back­ground colour (a sort of light grey) and font style (‘ital­ic’) in a theme file asso­ci­at­ed with the gram­mar. The theme file I cre­at­ed is called “Nuage”. The gram­mar is embed­ded in a Text­Mate ‘bun­dle’ that I call “Scriven­er-text”. When I choose to apply that bun­dle to a text file, I can also choose to apply the Nuage theme. Text­Mate remem­bers the kind of file and its loca­tion and re-applies the same bun­dle and theme to sim­i­lar files there­after. Now, every time I open one of the Scriven­er text files from the Scriven­er direc­to­ry on Drop­Box, Text­Mate applies the right lan­guage gram­mar and theme file. I see all my foot­notes dis­tin­guished in the text in an ital­ic (acu­tal­ly, slant­ed) font and with a light-grey back­ground. I have dif­fer­ent markup for com­ments and for block-quotes.

As for the IPad… I use the very capa­ble and flex­i­ble Tex­tas­tic. This is a mature text edi­tor com­pa­ra­ble in scope — on the iPad plat­form — to BBE­d­it on the OSX plat­form. (There is also an OSX ver­sion, but I’ve nev­er used it). Best of all, it will import Text­Mate lan­guage gram­mars (in TM ‘bun­dles’) and theme files. So I can use the same markup on my Mac lap­top and on my iPad. Tex­tas­tic also syncs its files to Drop­Box. So I can edit the marked up text using col­ored syn­tax and it will auto­mat­i­cal­ly save (with­out the col­or­ing) as a text file to Drop­Box in the form that Scriven­er expects.

But WAIT! “That’s not all!” ™ I like to keep my writ­ing clear. I want nouns and verbs to do the work. I don’t want to rely on wease­ly adverbs to fix-up weak verbs. I don’t want to write in pas­sion­less pas­sive voice with no sub­jects to take respon­si­bil­i­ty for the action. Nor do I want to make sim­ple edit­ing errors like repeat­ing one of the the words in a phrase acci­den­tal­ly when I move things around with cut-and-paste.

But I’m prone to do all of those things. With­out even noticing.

So I have added a few tricks to my gram­mar file for Scriven­er that, in com­bi­na­tion with the Nuage theme file, high­light the most com­mon mis­takes I make. I stole the imple­men­ta­tion of this idea from the “Eng­lish” bun­dle which is itself a repli­ca­tion of three nifty lit­tle Shell scripts by Matt Might. Now my pas­sives pong in red; my weasel words writhe in gree­ny-yel­low; my dou­ble-ups dis­play in orange. Hoorah!

A screen shot of Textastic (iPad) editing a Scriv-text file
A screen shot of Tex­tas­tic (iPad) edit­ing a Scriv-text file

So… if you use Scriven­er, Text­mate and Tex­tas­tic… allow me to offer you (with­out any guar­an­tees, war­ran­ty-against-dam­age or after-gift-sup­port) my cur­rent ver­sion of the ‘Scriven­er-text’ bun­dle for Text­Mate 2 (haven’t tried it with TM1.x) and the “Nuage” tmTheme file (for use in Text­Tas­tic) and the ‘Nuage’ bun­dle (that will install the theme in Text­Mate 2).

Installing the Text­Mate bun­dles is easy. Click on the down­loaded files. They should install them­selves. If not, copy them to Users/[your-user-name]/Library/Application Support/Avian/Bundles. The instal­la­tion of the bun­dles and theme file in Tex­tas­tic is also very easy. Down­load the files to the spe­cial #Tex­tas­tic fold­er that you cre­ate in the side-bar of the Tex­tas­tic edi­tor. Restart the pro­gram. Then point the style and lan­guage-gram­mar files at the file you’re edit­ing. (I’ll leave you to con­sult the Tex­tas­tic help file for the details of how to do that.) The result? You should be able to edit syn­tax-coloured, marked-up Scriven­er sync files anywhere.

Down­load: After all that, here’s the link to a zip file of my Scriven­er-text bun­dle, the Nuage bun­dle (for Text­Mate) and the theme file (for Tex­tas­tic on iOS).

Leave a Comment

Your email address will not be published. Required fields are marked *