Critic Markup: Plain-Text Editing Markup for Humans

by mattparcher • 13 years ago

54 30 13 years ago

This would be very useful for marking up LaTeX sources - could have done with this for my thesis

BruceIV• 13 years ago

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.

jpollock• 13 years ago

Isn't version control better?

adrianhoward• 13 years ago

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.

koralatov3• 13 years ago

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.

buster• 13 years ago

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

loevborg• 13 years ago

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.

chalst• 13 years ago

Version control is useful, though, if you want to have an proofreader work on an incomplete draft while the author is adding content.

goldfeld3• 13 years ago

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?

koralatov3• 13 years ago

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.

goldfeld3• 13 years ago

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.

gbog• 13 years ago

seem like a good idea, do the markup allow nesting, eg commenting on a previous addition?

themindfulbit3• 13 years ago

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.

RBerenguel• 13 years ago

I have to add this to my text editor project!

robertskmiles• 13 years ago

Reminds me very strongly of a simpler (and in my opinion more elegant) notation that I have been using for a long time:

http://www.azarask.in/blog/post/collaboration_made_simple_wi...

thanksya• 13 years ago

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.

toki• 13 years ago

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!]

gizzlon• 13 years ago

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

jeremyswank• 13 years ago

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

borplk• 13 years ago

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.

deerpig• 13 years ago

I would love to see syntax high lighting and eventually support for this in org-mode....

kghose• 13 years ago

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?

themindfulbit3• 13 years ago

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.

davidw• 13 years ago

"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.

goldfeld3• 13 years ago

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

koralatov3• 13 years ago

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

deltasquared2• 13 years ago

Nice idea. It seems pretty easy to understand. Where is the emacs mode?

deltasquared2• 13 years ago

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" )

chyatt• 13 years ago

Seems like a nice way to collaboratively contribute to a chunk of text via email!

Critic Markup: Plain-Text Editing Markup for Humans

Related Stories