Edit Mac Scrivener 3 With iOS Ulysses, Part 2: Prepping Your Existing Scrivener Project #amwriting

Scrivener and Ulysses CAN get along

Articles in this series:

Part 2: Prepping your existing Scrivener Project

Introduction

In Part 1 of this series, I talked about changing your Scrivener habits in order to edit with Ulysses, eventually. In Part 2, I’m going to talk about changing your existing project so that it compiles with the Scrivener “Convert MultiMarkdown to Rich Text” option ON, and so that it syncs as smoothly as possible with Ulysses. Believe me, you want to do as much as possible of this work before you start syncing and editing with Ulysses. If you’re new to my articles on how to edit Scrivener projects with Ulysses, please review “Is this workflow for you?” in Part 1. You’re about to make some significant changes to your existing project, and I wouldn’t want you to put in a few hours of work on it and then blame me if you don’t like the result… If you’re not sure, I suggest you start with a new project making the changes to the base preferences I suggest in Part 1, and then skipping ahead to Part 3. Or, you could make a fresh copy of the Scrivener Tutorial Project (in Scrivener, use the menu item Help→Interactive Tutorial to make a new one.) and follow along here in Part 2 without touching your work-in-progress (WIP) until you’re sure you understand the needed changes. But if you’re brave and reasonably certain, I’ll provide directions so that you’ll be able to revert your entire WIP (if needed) or any part of it. Just as a reminder, you’ll need to type Markdown and MultiMarkdown directly into Scrivener. If you need to, you can review them here:

Ready?

Let’s make a backup and a bunch of snapshots!

First, use the menu command File→Back Up→Back Up To… to make a backup of the project you’re converting. (From now on I’ll refer to that project as your WIP, even though it may be a copy of the Tutorial.) Be sure to tick the “Back up as ZIP file” checkbox underneath the file list to make the backup a compressed archive! Save the backup somewhere other than your usual backup folder, so that you can find it easily (I suggest the Desktop.) With that backup tucked away as insurance, let’s make named snapshots of all your WIP’s files and folders.

  • Select all the top-level folders in your Binder.
  • Use the menu command View→Outline→Expand All to show everything in your Binder.
  • Use ⌘-A or Edit→Select All so that all the documents in your Binder are selected.
  • Use Documents→Snapshots→Take Titled Snapshots of Selected Documents.
  • Give the snapshots a name, like “Before Ulysses Conversion” or whatever else takes your fancy, and click OK. (Any document that isn’t text, or is empty, will be ignored.) It may take a while, if your WIP is large. Get a fresh cup of your caffeinated beverage of choice.

Now you can not only revert any individual document to its “before Ulysses” state, you’ll be able to see what it looked like before you started, so you can check your progress. Finally, before we start the changes, I suggest you turn on View→Text Editing→Show Invisibles. Some of what we must do involves changing the number of spaces, tabs, and returns in your text. It helps to be able to see them.

Convert Inspector Comments and Inspector Footnotes

This one’s easy, and easy to reverse as well.

  1. In the Binder, select all the text documents that you think you might ever compile.
  2. Put the editor into Scrivenings view. It may take a few seconds to load if your project is large.
  3. After the view loads, put your cursor somewhere in the editor.
  4. Display the Inspector, showing the Comments and Footnotes tab.
  5. Nothing there? You’re done. Move on to Update Paragraphs, below.
  6. If you have some, ask yourself this question: Will I ever need to have these in the Inspector again?
  7. If your answer is yes, scan through your comments and footnotes.
  8. If any comment or footnote has more than one paragraph, remove the paragraph breaks. (I like to put in a bullet so that I can easily restore the paragraphs after I return the comments to the Inspector.)
  9. After you’re done, put your cursor somewhere in the editor again.
  10. Use the menu command Edit→Transformations→Convert Inspector Comments to Inline Annotations.
  11. Use the menu command Edit→Transformations→Convert Inspector Footnotes to Inline Footnotes.

If later you need to put your comments and footnotes back into the Inspector, use a similar process but instead use Edit→Transformations→Convert Inline Annotations to Inspector Comments and Edit→Transformations→Convert Inline Footnotes to Inspector Footnotes. It’s easiest if you restore paragraphs after you’ve transformed the comments and footnotes back to the Inspector.

Update Paragraphs

First, if you haven’t already, follow the directions I referenced in Part 1 for removing any “body style” or “normal style” from your project, and the directions for changing your default paragraph style to block style throughout your project. Here are the links again:

At this point you’re probably cursing me: “Darn you, Dragon, now I couldn’t find where my paragraphs begin and end if I didn’t have ‘Show Invisibles’ on!” This next step is where you fix that.

  1. Once again, in the Binder, select all the text documents that you think you might ever compile.
  2. Somewhere in the Scrivenings view, select the ¶ symbol at the end of a paragraph and copy it.
  3. Now choose Edit→Find→Project Replace… and paste the ¶ symbol once into the Find box and twice into the Replace box. It should look like this:Project replace dialog for replacing one return with two.
  4. Click “Replace.” In the “Project Replace Cannot Be Undone” alert, click OK.

From now on, you’ll need to press “enter” twice after each paragraph. This paragraph formatting will make it obvious if you don’t! It quickly becomes habit.

Quality Point: Line Breaks

Do you ever use line breaks within a paragraph? (They show up as “↩︎” when you have Show Invisibles on.) If you do, you’ll need to change each one to two spaces plus a new paragraph (“・・¶” when Show Invisibles is on.) Use the technique of copying and pasting into the Project Replace dialog above to change all these now.

Update Bold and Italic Text

This isn’t hard, but it is tedious if you have a lot of these. (If you use a keyboard macro utility, you can automate this. I’ll give keystrokes so that you can do that easily, but as I don’t use such a utility myself, I can’t tell you how to set it up.)

  1. Change Scrivener preferences to use underscores as italics markers. Open Scrivener→Preferences…, and in the Sharing panel under the Export tab, uncheck “Convert underscores to underlines when converting Markdown”. It should look like this: Scrivener Preferences dialog for adjusting underscore meaning
  2. You should already have your “compilable” documents selected from above. If not, please select them and place your cursor at the beginning of the Scrivenings view.
  3. Use the menu command Edit→Find→Find by Formatting… (Keystroke: control-option-command-F “⌃⌥⌘F”)
  4. Set up to search for italics. It should look like this: Scrivener "Find by Formatting" dialog set up to search for italics
  5. Go ahead and click “Find.”
  6. Repeat the following steps until you’ve processed them all:
  7. Move to the beginning of the selection. (Keystroke: left arrow key “←”)
  8. Type an underscore. (Keystroke: shift-hyphen “⇧-“)
  9. Select the italics again. (Keystroke: shift-option-command-G “⇧⌥⌘G”)
  10. Move to the end of the selection. (Keystroke: right arrow key “→”)
  11. Type another underscore. (Keystroke: shift-hyphen “⇧-“)
  12. Select the next italics in the Scrivenings view. (Keystroke: shift-option-command-G “⇧⌥⌘G”)
  13. Start over from step 2, but this time search for bold, and type two asterisks “**” instead of a single underscore.

Some folks use a style for italics and bold. Life with Ulysses will be much simpler if you don’t. To de-style your italics and bold, just delete the styles you used for them from the Styles list (Format→Style→Delete Style and choose your italics or bold style from the menu.) The text will still be formatted (though again, life with Ulysses will be simpler if you don’t bother in future and use underscores and double asterisks instead.)

Convert Tables

A word about Scrivener tables in general: In my opinion, Scrivener’s tables are the most problematic feature of its editor. Users on the Scrivener forums who live and die by tables (many are scientific writers) often don’t bother; they create their tables in a spreadsheet app, format them there, and paste the result into Scrivener, more as a placeholder than anything. Then, after compiling to DOCX or some other intermediate format, they do a final polish of the table formatting. They may even go back to their spreadsheets and re-paste the tables at that point. If you use that philosophy, then MMD tables are just another kind of placeholder, and you can use my conversion process to produce them almost straight from your spreadsheets. If, on the other hand, you’ve always used Scrivener tables directly, I’m going to suggest you use a spreadsheet app as an intermediate step to convert your Scrivener tables to MMD tables. (You can produce them by hand, as you will lists later, but it’s going to be a slower and more error-prone process.) Here’s my process:

  1. You should already have your “compilable” documents selected from above. If not, please select them and place your cursor at the beginning of the Scrivenings view.
  2. Once again, open the Edit→Find→Find by Formatting… dialog. This time, we’ll choose “Tables” from the dropdown menu, like this: Scrivener "Find by Formatting" dialog set to search for tables
  3. Click Find, and at your first table, open the Inspector to the Snapshots panel. Find the original table in the snapshot (which won’t have the extra “enters” we put in!)
  4. Select the entire table in the snapshot and copy it to the Clipboard.
  5. Open your favourite spreadsheet application. (If you don’t have one, Apple’s Numbers is free on the App Store.)
  6. Create a new spreadsheet and paste in your table. Save the spreadsheet if you like.
  7. Now select what you just pasted, and copy it (the spreadsheet app will have added important information, like row and column numbers, that you can’t see.)
  8. Go to the Tables Generator site. Use its “File” dropdown and select “Paste Table Data…” Do so and click “Load.” Then click the “Generate” button beneath your pasted-in data.
  9. That’s it! You’ll see a MultiMarkdown version of your table. Click the green “Copy to Clipboard” button.
  10. Back in your main editor pane, select the table and the empty line after it as well.
  11. Use the Format→Table→Remove Table menu command.
  12. Paste the MultiMarkdown table over the remains of your old table.
  13. The output from the tables generator site is basic. Add such things as alignment tags and merged cells if needed.
  14. Repeat steps 3-13 until you’ve converted all your tables.
Convert Links
External links

Once again, we’ll use Find→Find by Formatting…, this time searching for “Web/File Link”. The dialog will look like this: Scrivener "Find by Formatting" dialog set up to search for external links Click “Next”, then for each link you find:

  1. Put square brackets around the link, and an empty pair of parentheses after it, like this: [Google it!]()
  2. Right-click or control-click on the link, and select “Copy Link”
  3. Paste the link into the parentheses. Your link should now look like: [Google it!](https://google.com)
  4. You can right-click on the link again (“Google it!” in my example) and select “Remove link” if you like.
  5. If you prefer reference-style links, that’s fine! But don’t set them up now. When we start syncing and editing with Ulysses, we’ll configure it to use reference links if you prefer, and these will be converted.
Internal links

Repeat the process for external links above, but this time search for “Document Link”. For each document link you find, insert an inline annotation (shift-command-A) at the beginning. It should look like this: Internal link tagged with an inline annotation Use whatever tag you like. (If it’s an obvious link like a table of contents link, you can skip this, but remember that without some sort of clue, you won’t be able to tell the difference between internal links and plain text in Ulysses.)

Convert Lists

Sadly, we can’t search for lists with the “Find by Formatting” command. Instead, we’ll search for tab characters. This may find a few things that aren’t lists. We’ll just skip them.

  1. You should already have your “compilable” documents selected from above. If not, please select them and place your cursor at the beginning of the Scrivenings view.
  2. Open the Edit→Find→Find… dialog. In the Find box, hold down the option key and type the tab key. You should see a blue right-arow “→” in the Find field.
  3. Click “Next” until you find a list. It should look something like this:
    ◆   Foobar
    
        ⁃   Foo
    
        ⁃   Bar
    
    ◆   Foobat
    
        ⁃   Foo
    
        ⁃   Bat
    
  4. Select the entire list and choose Format→Lists→None. The bullets or numbering will disappear.
  5. Remove the blank lines between items.
  6. Open your Inspector pane to the Snapshots panel and find the list to use as a guide. Using Markdown list syntax, recreate the list in the main editor as closely as you can, using hyphens instead of bullets, and simple numbers followed by periods for enumerated items.
  7. Repeat steps 3-6 until you’ve converted all your lists.
Convert Images

Embedded images, images linked to image files within your project, and images that Scrivener linked to files outside your project—all are invisible in Ulysses, and can be accidentally deleted from your text simply by using Ulysses to edit the paragraph they’re in, like internal links. (You’ll have the means to fix this, never fear, but why deal with it if you don’t have to?) I’ll give you options so that Ulysses won’t touch your images.

  1. Once again, use Edit→Find→Find By Formatting… while you’re viewing a Scrivenings session of your compilable documents. This time, search for images.
  2. For each image you find:
    • Option 1: Put an inline annotation tag in front of it, just as you did for internal links. If you are willing to reinsert images from your snapshots if you accidentally edit their paragraphs with Ulysses, this is by far the fastest option.
    • Option 2: Create a Markdown image insertion for the image. This is much safer than Option 1. Ulysses will never mess with your image insertion unless you deliberately delete it.
  3. Right- or control-click on the image in Scrivener. If the popup menu has the item Save As Picture… in it, it’s an embedded image. Use the menu item and save the image to your hard drive, outside of any cloud drive. Do not save it to either Google Drive or iCloud Drive! The compiler will not be able to load it from there.
    Or
    If the popup menu has the item Reveal In Binder in it, it’s linked to an image that’s in the research area of your project. Go ahead and select Reveal In Binder, click on its revealed filename in the Binder, and use File→Export→Files… to save it as you would an embedded image, above.
    Or
    If the popup menu has the item Reveal In Finder, it’s an image already linked to an external image file and you need not save it.
  4. Navigate to the image in the Finder. Use the Reveal in Finder item in the popup menu, or navigate to where you just saved the image.
  5. Right- or control-click on the image in Finder.
  6. Hold down the option key. You should see an item in the popup menu that says, Copy “myimage.jpg” as Pathname.
  7. Continue to hold down the option key and select that menu item.
  8. Return to Scrivener. Delete the image, and type the Markdown syntax for an image insertion. Inside the parentheses, type “file://” and then paste your pathname from step 5. Your final image insertion should look something like ![](file:///Users/MyUserName/MyFolder/myimage.jpg)
Styled Text Cleanup

I’ve already suggested that you not style most of your text. Every time you edit a paragraph containing styles with Ulysses, you’ll need to reapply the formatting when you return to Scrivener if you want to retain it for compile. Do think critically about the styling you really need—Can you style this at compile time rather than in the text? Would it be easier to adjust the styling after compile? Do you really need both underlining and italics? Limit your styles to what you do need (I find I need blockquotes, attributions, and small caps occasionally in body text, and a few more styles in front and end matter—title pages, tables of contents, acknowledgments and the like.) Delete the others. Then follow these steps for each of the remaining styles:

  1. You should already have your “compilable” documents selected from above. If not, please select them and place your cursor at the beginning of the Scrivenings view.
  2. Once again, open the Edit→Find→Find by Formatting… dialog. This time, we’ll choose “Style” from the dropdown menu. For each style you have,
  3. Search for text with the style.
  4. Put an inline annotation with the name of the style at the beginning of each paragraph that contains the style.
Odds and Ends
  • If you have styles that include tabbed text, put them inside fenced code blocks, like this:1
    ```MyStyleName
    §This style   uses columns         separated
    §by tabs.      These are    sometimes useful
    §for things like manuscript       headers in
    §very old-     fashioned          submission
    §guidelines
    
    ```
    

    The problem is not that Ulysses will strip the style—of course it will, if you edit the paragraphs with Ulysses. No, it’s Scrivener’s MMD→RTF conversion that will strip out the tabs before compile. I’ve used section markers to show the lines that are styled. You must have an unstyled empty line before the closing fence.

  • I’ve given methods that don’t require any adjustment to the standard built-in compile formats. If you’re willing to edit compile formats, you can do all sorts of things—and you probably will. Some of the things I’ve set up:
    • Using Markdown tags to tag styles instead of inline annotations.
    • Colour-coding Scrivener styles to match colours I’ve set up in Ulysses for things like block quotes, header styles, and centred text.
    • Colouring text inside inline annotations in Ulysses to match the annotation colour in Scrivener.
    • If there’s any interest, I may do a blog post on this sort of advanced cross-formatting.
  • Image storage for Markdown: Using your own hard drive for image storage works perfectly well and will save you from slips of the keyboard. If you’d like to see your images while editing in iOS Ulysses (at least in preview mode) I’ve found you can store them two places:
    • On a website you control. Even a WordPress.com blog will do. Upload the images and use their URLs from your website in your image references.
    • On Dropbox. (NOT iCloud Drive. Sorry.) If you have Dropbox on your Mac, store the image somewhere in your Dropbox folder. Right click on the image file in Finder, and select “Copy Dropbox Link.” Use that link in your image references, but edit the link slightly: Change the dl=0 at the end of the link to dl=1. This will let Scrivener access the image for compile as well as giving you visibility in Ulysses preview mode on iOS.
  • Tag placement for italics and bold: Ulysses likes its bold and italics tags to be surrounded by whitespace, like this:
    … greeted me with a hearty _¡Hola, amigo!_
    Most of the time you can achieve this by simply including your punctuation inside your tags. But if you follow Chicago Manual of Style recommendation for dashes—em dashes are not set off by spaces—you may be in trouble if your italics/bold start right after your em-dash, as Ulysses will arbitrarily decide that of course you don’t want italics or bold to start in the middle of a word! And will put a helpful backslash in so that your italics or bold is messed up on compile.
    The easy way to get around this is to use CMS’s alternate recommendation of space-en dash-space. If you really want your em dashes, set up a compile substitution rule to convert space-en dash-space to em dash. (If you have no idea what the differences are among em dashes, en dashes, and hyphens, don’t worry about it. Just be aware that if your italics or bold don’t show up after compile, this peculiarity of Ulysses may be the reason. In Scrivener, search for a blackslash followed by an underscore or an asterisk to find and correct this problem.)

  1. You can do this for any Scrivener-styled paragraph that doesn’t have any Markdown inside. I like it; the styled paragraphs really stand out in Ulysses, and they’re easy to find in Scrivener even if the style is accidentally stripped. It’s just that for tabs to survive, you must use code blocks for styles incorporating tabs. 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.