Technical limitations of CriticMarkup and what can we do about it?

Fletcher's Avatar


17 Feb, 2013 07:01 PM

(This post represents the opinion of Fletcher Penney — no one else.)

First, let me be clear from the start — I think that CriticMarkup is a great tool, and I believe some amazing things will come from it. I am starting this thread to kick-off some additional discussion about how it will be implemented in various tools based on some of the inherent limitations. Specifically, of course, this relates to MultiMarkdown Composer.

What Is the Problem?

CriticMarkup is a fantastic syntax for denoting what changes have been made, or suggestions for changes that should be made. I think the extra features of Composer 2.1 make it even more useful.

The key issue is that the CriticMarkup syntax is "orthogonal" to the Markdown/MultiMarkdown syntax. This is important, because it would be really frustrating to have to split your changes across every element they involve. For example:

This is *text in {--italics* and--}{++emphasis* but++} not bold.

This makes perfect sense to a person reading the plain source text. And you would think it should be easy to simply show the changes in HTML, or any other format. But it's not.

The reason is that the example shown above basically has one <em> tag and two </em> tags. Now, you can imagine trying to use the CriticMarkup syntax across other Markdown/MultiMarkdown elements (headers, tables, footnotes, etc.) It would get ridiculously complicated to ensure that the HTML output is appropriate, much less valid.

This is purely a technical issue, and it's possible that someone will develop an algorithm to fix it. But I suspect that such an algorithm will be quite complicated, and may take longer to develop than it's worth.

CriticMarkup and Philosophy

This technical issue partially relates to a more philosophical discussion. In my opinion, CriticMarkup is exceptionally useful for the Markdown/MultiMarkdown source document. It's fantastic. It allows you to easily see what changes your editor or collaborator has proposed, and accept or reject those changes.

What's not as clear, however, is how CriticMarkup should be used in the HTML preview. I understand that users will intuitively want to be able to see their changes in the HTML view, and Composer will show this. The problem is that the HTML generated is not valid. This means that sometimes it is going to look roughly correct, and sometimes not.

It also means that the HTML generated using this approach cannot reliably be used for other things. For example, if you tried to convert the HTML into an ePub, it is probably going to fail.

I am going to continue to try out different approaches to trying to minimize HTML issues under basic circumstances, but it's not going to work perfectly under all circumstances.

So, What Does This Mean?

In my opinion, CriticMarkup should be thought of as a tool for plain text, not for HTML or other formats. When you want to export to HTML or something else, you either accept/reject all of the edits first, or you leave the CriticMarkup syntax intact in the output document.

I know that not everyone agrees with this from a philosophical standpoint, but there is then also the technical issue to be resolved.

What I am looking for is discussion to help shape where this goes. Some of this may be useful to Erik and Gabe when shaping CriticMarkup itself, and some may only be useful for Composer.

Please keep in mind that I am looking for productive discussion. Simply stating that Composer should export CriticMarkup under all circumstances without suggesting how to make that possible is not exactly useful. What is helpful are suggestions on how to improve CM workflow as much as possible, and how to minimize the impact of the HTML limitations.


  1. 1 Posted by bowerbird on 19 Feb, 2013 08:47 PM

    bowerbird's Avatar

    you are asking good questions, fletcher.


  2. 2 Posted by Mason on 23 Feb, 2013 01:20 AM

    Mason's Avatar

    I would have to agree with your thoughts, especially in regards to the idea that CriticMarkup should focus on the plaintext and not the HTML. For export, accepting or rejecting all of the edits would allow for a clean output.

    The other option I see for that would be to show the edits/deletions in the HTML. Maybe have them colored a certain way and then have the differences displayed via mouse over or mouse click. This would allow someone to read the differences in an exported format. It does mean that there would have to be some css or javascript that would need to be included in the HTML file to accommodate that functionality.

    This may make the option more complex than necessary. If you have two people working on the plain text in an editor that is CriticMarkup aware, then I am not sure you need to have an output that displays the edits.

Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac