Critic Markup: Plain-Text Editing Markup for Humans

Now this is excellent! The other one is slower than using pen, but this one is faster AND better!

Until now, when I had to proofread text, I would take screenshots, put it on a tablet and then write on it with pen. Or use Microsoft Word review features.

But now I'm going to use this. You just changed my life.

Your solution is just brilliant and a really cool hack. I will add this to my basic techniques. One suggestion: Change your article, instead of the sentence "he first set of brackets denotes deletion, the second set denotes addition, and the third set denotes a comment." write it the Ruleset for dumb people like me like this:

Ruleset:

First Brackets: [Deletion] Delete this word.

Second Brackets: [][Addition] Add this word.

Third Brackets: [][][Comment] Comment this word.

Combination Examples:

[Change][Replace] Delete first word, replace with second word...

[Remove][][My comment: You should remove this word!]

Cool! But how do you revise already revised text? =)

I picked up a similar system a few years ago, I don't remember the source, but it depends on always using 2 sets of brackets (thus, fewer rules to remember):

blah blah [][add something] blah blah

blah blah [delete this][] blah blah

blah blah [error][correction] blah blah

Read it as: "replace the first brackets' contents with contents of the second bracket".

An optional third set of brackets would be a comment or explanation.

In my opinion, this simplified ruleset can be used even to correct texts for people who do not dig being asked to memorize 'a lot of rules' and they often end up really liking its clarity.

edit: formatting

You're right, it can definitely get crowded.

Diff is a great tool, and it's where we started on this whole thing. Unfortunately it's a little too complicated for most users, and there's no way to comment on individual edits unless you use source control and commit on every spelling change.

Thanks for this. I won't get the chance to try it out for a couple of days, but it's much appreciated.

I would definitely welcome a Vim plugin with syntax highlighting.

Just to totally overcomplicate it, some method of going through the changes one-by-one and accepting or rejecting them, à la Word's `Track Changes' feature, would be the icing on the plugin's cake.

Kinda sorta maybe.

Source control is, relatively speaking, complicated. The people who make editorial comments on text - especially in the publishing world - are often not technical folk, and asking them all to learn and understand a new tool is decidedly non-trivial.

They can all type however. I can see this being useful.

You will be amazed at the number of publishers who run their editing process of Word documents because their change control is the closest their is to a common denominator.

Yeah, sounds like the usecase for an easy-to-use "code review" tool. Shows and discusses differences.

The use case is totally different. Say I'm a professor and I'm writing a grant proposal. I send a draft to a PhD student to proofread. Today the only practical way to do this is to use Word's "track changes" tool.

Basically, a proofreader

(i) gives you a lot of minuscule changes. A comma here, moving adverbs around there, etc. In a 10-page draft, there could be hundreds of suggestions.

(ii) only makes suggestions. I'm the one applying for the grant, so I need to explicitly approve (or reject) every single change individually. This probably won't work elegantly with `patch`.

(iii) changes individual words. Word actually records your changes as you make them. This is not the same as simply diff'ing version1 and version2. This helps me see the proofreader's point.

(iv) makes textual comments to explain changes. Or you simply need to annotate a paragraph as "I don't understand this." Maybe you need to offer different suggestions, depending on the author's meaning ("Perhaps your mean to say ...")

(v) makes different kinds of changes. "Diff" tracks changes on a line-line-basis. If you edit prose, you move around words, or lines, or even paragraphs. Basically, dealing with written language is more complicated and has more structure than source code.

(vi) does not typically have a need for a revision history. It is very rarely useful to look up when a certain sentence was introduced in a grant proposal. While it's useful to keep earlier versions as a backup (and Dropbox is enough for that), version control really is a solution looking for a problem when it comes to writing prose.

Agreed, but it's likely more useful for Markdown sources - when I was writing my thesis my supervisor and I kept the LaTeX source in a shared git repository, and added a couple macros for comments - it wasn't quite this slick, but combined with the git log it worked pretty well.

Not at this time. The syntax can get unreadable fairly quickly.

It works well with version control, and with our Sublime Text plugin you can Accept or Reject edits via keyboard shortcuts before moving to the next round of edititng.

Well if anyone wants an emacs mode for this: (require 'generic-x) ;; we need this

(define-generic-mode 'critic-mode nil nil '(("{--.--}" . 'font-lock-warning-face) ("{~~.~~}" . 'font-lock-constant-face) ("{{.}}" . 'font-lock-keyword-face) ("{>>.<<}" . 'font-lock-function-name-face) ("{\+\+.*\+\+}" . 'font-lock-type-face) ) nil nil "A mode for foo files" )