Critic Markup: Plain-Text Editing Markup for Humans(criticmarkup.com)
criticmarkup.com
Critic Markup: Plain-Text Editing Markup for Humans
http://criticmarkup.com/
13 comments
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
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
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!]
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!]
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.
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.
Cool! But how do you revise already revised text? =)
Unfortunately this will make it very annoying to read. The examples look pleasant because it is a small amount of text with color coding. When you have a lot of text with a lot of corrections displayed in a regular text editor this will get very very crowded.
Why not use existing tools like diff?
Why not use existing tools like diff?
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.
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.
So here's a first stab at a Vim plugin for Critic Markup, forked out of tpope's markdown as to be a superset. For now it's just the basic add/delete/substitute. I'll add comments, highlighting and jumping to each change to accept/reject up next.
https://github.com/goldfeld/criticmarkup-vim
https://github.com/goldfeld/criticmarkup-vim
Thanks for this. I won't get the chance to try it out for a couple of days, but it's much appreciated.
Great idea. I had been thinking about something like this for a few weeks, very timely! Would you guys welcome a third-party Vim plugin to your toolkit?
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.
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.
Also as a feedback, I wouldn't offer the toolkit zip download as the only option to get the plugins--have separate links for them. Both on the announcement page and on Gabe's post I tried to click the Sublime Text plugin to get to a github page or something and see how you went about it.
That's a great point. I'll figure out a better way to handle downloads on the site.
Isn't version control better?
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.
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.
Version control is useful, though, if you want to have an proofreader work on an incomplete draft while the author is adding content.
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.
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.
Trying to teach someone non-technical how to use Git, even at the simplest of levels, is very, very difficult. I tried once for a project a friend and I were working on, and eventually gave up -- the learning curve was just too high for something he probably wouldn't use ever again.
This, however, would have been almost perfect: not too complicated, easy-to-teach, and portable.
This, however, would have been almost perfect: not too complicated, easy-to-teach, and portable.
Yeah, sounds like the usecase for an easy-to-use "code review" tool. Shows and discusses differences.
"Humans", as in "regular people" use Word for this, if they're at all familiar with the more advanced features. Which a lot of people aren't. Something like this might be useful for LiberWriter, but I'm 100% certain that our users would find it more confusing than helpful.
It's interesting although I do wonder how we can get the masses to learn and start using something like this. I know it looks trivial to you and I but don't under estimate how not tech-savvy most people are.
This would be very useful for marking up LaTeX sources - could have done with this for my thesis
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.
seem like a good idea, do the markup allow nesting, eg commenting on a previous addition?
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.
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.
I would love to see syntax high lighting and eventually support for this in org-mode....
Seems like a nice way to collaboratively contribute to a chunk of text via email!
Nice idea. It seems pretty easy to understand. Where is the emacs mode?
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" )
(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" )
I have to add this to my text editor project!
http://www.azarask.in/blog/post/collaboration_made_simple_wi...