Review

New in 1.3.

When you want someone’s comments on a draft, send it to them as a Word document. They comment and suggest changes in whatever they use, and when their copy comes back, each comment and suggestion sits in the margin beside its passage. You accept, reject or resolve them one at a time. Nothing goes into your Markdown until you say so.

Sending it

Choose File ▸ Export as Word Document (⇧⌘E) and send the file as you would any other. Reviewers can use:

Microsoft Word. Comments, replies and Track Changes all come back.
Pages. Comments and tracked changes come back if they export to Word with File ▸ Export To ▸ Word.
Google Docs. They upload the file, comment and use Suggesting mode, then choose File ▸ Download ▸ Microsoft Word. Suggestions come back as tracked changes.

Each paragraph in the file carries a hidden marker so Grasmere can tell which paragraph is which when it comes back. It’s a Word bookmark whose name starts with an underscore, which Word leaves out of its Bookmarks list. Reviewers won’t see it and don’t have to do anything with it. Word keeps the markers. Nobody says whether Pages and Google Docs do, but it hardly matters, because Grasmere matches paragraphs by their words when the markers are gone.

Grasmere also keeps a copy of exactly what it sent. That way it can tell what the reviewer changed, even if you’ve carried on writing since.

Bringing it back

Open the document, choose File ▸ Import Review and pick the reviewer’s file. You can pick several at once. The margin opens on the Page tab with a Review section at the top, showing each reviewer’s name and then their comments and changes in document order.

A comment shows what they wrote, the passage it’s on, and any replies.
A change shows a small before and after, with what goes struck through and what comes underlined. Changes made with Track Changes show the reviewer’s name and the date. If the reviewer changed something without tracking it, Grasmere still finds it by comparing their copy with the one you sent, and marks it not tracked.
A paragraph the reviewer added or took out counts as one item.

Click an item to go to its passage. The passage stays faintly washed on the page while the item is selected.

When a second reviewer’s file comes in, import it the same way and their items join the list under their name. Importing the same file twice adds nothing.

Accepting and rejecting

Accept puts the change into your text. It’s an ordinary edit, so ⌘Z takes it back.
Reject leaves your text as it is.
Resolve marks a comment as dealt with. Reply lets you write a line back first, and your reply is kept with the comment.
Accept All and Reject All, beside a reviewer’s name, deal with all their changes at once. Their comments stay. Accept All is one step for Undo.

You can keep writing while a document is out for review. If you accept a change in a paragraph you’ve edited since, Grasmere fits the reviewer’s change into your new version. Say you rewrote the start of a sentence and they changed a word at the end. Both changes stand.

It’s only a real conflict when you both changed the same words. Then the item shows three versions, one above the other:

Sent is what they saw, with their words struck through.
Suggested is their version, with their words underlined.
Now is yours, with the words you changed picked out.

If you want their change, make it by hand and then reject the item. A change that would cut through a link or bold text can’t be accepted either, so a link is never left half-written. The item tells you when this happens.

With VoiceOver, each item reads as one sentence saying who, when and what. Its Accept, Reject and Resolve are in the Actions rotor.

A whole book

You can send a whole book from the Manuscript view the same way. Its Export ▸ Export as Word Document marks every paragraph, and Grasmere notes which chapter each one came from.

When the copy comes back, choose Import Review from the Manuscript view’s Export menu. File ▸ Import Review works too, with any chapter open, because Grasmere sees that it’s the book’s copy. The whole book is compared at once, so it still works if the markers are lost. Each comment and change goes to its own chapter, and when you open a chapter they’re in its margin, as with a single document. The running order shows how many each chapter has left to deal with (“3 open”).

If you’ve moved a passage to another chapter since, its comments and changes follow it there. Some things don’t belong to any one chapter, like a comment on the title page, a part’s title or the references. Those, and anything on a chapter you’ve since deleted, go to Review notes, a document in the book’s folder. Each gets a task line with the reviewer, the date, what they said and what it was on, so they show in Tasks and you can tick them off.

Review notes is an ordinary document, but its front matter says review: notes, so the Manuscript view, Publish to PDF and Export as Word leave it out of the book. Importing the same copy twice adds nothing to it.

Going back

Every time you import a review, Grasmere first keeps a copy of each document it covers, as it is at that moment. For a single document that’s the one document. For a book it’s every chapter, plus its Review notes.

If you change your mind about what you accepted, choose File ▸ Restore to Before the Review…, or the same command in the Review section’s ⋯ menu. It lists the documents that have changed since the review came in and puts them back as they were. For a book it restores them all at once. The changes you’d accepted show in the margin again.

Restoring the open document is an ordinary edit, so ⌘Z takes it back. Grasmere also keeps what the documents said just before you restored, so choosing the command again reverses the restore.

The copies are kept in the hidden .review folder. Only the documents a review can change are copied, never the whole project, and each folder keeps the ten most recent.

What’s ignored

Only words count. Changes to fonts, styles, spacing, colours, page size or layout are never shown and never applied. A reviewer can reformat the whole document and you’ll only see what they changed in the text. Headers, footers, text boxes and pictures aren’t compared either.

Unplaced items

Sometimes an item’s passage isn’t in the document any more, say because you deleted that paragraph. The item goes to Unplaced at the end of the section, with the text it was about, so nothing is dropped. Resolve it once you’ve read it.

Where review files live

Each document’s review is kept in a small file beside it, in a hidden .review folder. Chapter One.md has .review/Chapter One.md.json. The file holds the copies sent, the reviews imported, and every comment and change, open or dealt with. It’s plain JSON, so any text editor can read it.

A few things worth knowing:

The review file goes wherever the folder goes, and Grasmere moves it when you rename or move the document in the app.
If you copy a document on its own in the Finder, its review stays behind in the .review folder where it was.
To find the file, choose Show Review File in Finder from the Review section’s ⋯ menu. Press ⇧⌘. in a Finder window to see hidden folders.
For a book, the record of which chapter each paragraph came from, and the restore copies, are in the .review folder of the book’s own folder.
Like every hidden folder, it’s left out of the contents, links, search and your website.
Git ignores it. The folder has its own .gitignore, and Grasmere’s lines in your project’s .gitignore list it too.

Your Markdown never holds review marks. Comments wait in the review file until you deal with them, and accepted changes go into the text as ordinary writing.