Critic markup

[jebyrnes]

Any thoughts about adding the Critic Markup spec? It would be invaluable to those of us that collaborate with RMarkdown and use it to teach with (for marking up homework!)

http://criticmarkup.com

{--Delete me--}
{~~ Change text ~> To this ~~}
{++Addition++}
{==Something to highlight==}
{>>This is my comment<<}

Note, if this is outside of the scope of the package, or if there's a way to just add in an option when we knit documents, feel free to sigh, roll your eyes, and tell me so. I noticed that ROpenSci started a package to deal with this a bit, but, it seems to have been abandoned, and was trying to do a lot, rather than just implement the above tags.

[yihui]

In most cases, we can only support what is supported by Pandoc, so the question is, does Pandoc support this markup?

[jjallaire]

With pandoc 2.0 we could actually write a Lua filter that would handle additional markup types like this (e.g. the filter would look for {} delineated Critic Markup and render it as appropriate).

That said, I think what we really need in addition are editors that allow the insertion of Critic Markup in a more straightforward fashion (e.g. the work that has already been done with MultiMarkdown Composer). I don't think it's realistic that many writers will want to actually write out this markup manually when they are used to higher level interfaces like those available in MS Word and Google Docs. It's great to be able to serialize critical markup inline but to me authoring seems like a harder nut to crack (as the Rmd ecosystem is at least today oriented around pure plain text authoring).

[jebyrnes]

Two thoughts. First, a variety of markdown editors do support this (I work in Atom a lot, for example). Second, while I agree that many folk prefer to work in higher level interfaces, such as word or google docs (and I know nothing about going from those interfaces BACK to markdown), given that this can be rendered in html - see for example https://github.com/jgm/pandoc/issues/2873#issuecomment-214097345 - and other formats (and if pandoc 2.0 can handle it...) I'll say that, as an educator and collaborator, this really would dramatically change what is possible.

As an educator, having students turn in RMarkdown homeworks are great but, marking them up and returning is highly problematic. Right now, we put in font tags and such to differentiate our comments. Having an ability to markup .Rmd files, render as .html, and then return them to students would be a game changer in terms of ease of back and forth. It's only a few more markdown tags.

Similarly, as someone who frequently collaborates with large groups, the longer we can go without having to move to word or somesuch, the better, because you immediately start to get into the result-copy-paste problem as analyses change in revision. Giving collaborators a set of tools to work with within R to mark things up, and render so that each other can see what previous collaborators have done in their web browser or somesuch while they add their own edits (or just read things in Markdown) would, again, make the revision collaboration workflow move much more easily, and stay within RMarkdown much longer before jumping into a final editor (if ever).

Just my $0.02. If this is a huge headache/not possible, no worries. But, I think a lot of folk would be pretty happy about this - some of whom haven't even heard of critic markup, but have kvetched about not having anything track-change-like in RMarkdown. (Believe me, I have heard them)

[jjallaire]

I agree, I think R Markdown definitely needs to address these requirements. What I'm thinking of is an interface that allows you to use the editing gestures traditionally provided by richer editors, but have all of the work serialized to markdown / something like Critic Markup. That way anyone that wanted to work directly in Critic Markup could, but we'd also enable a more familiar set of markup tools.

All of this is technically possible but still quite a bit work. Nevertheless I think it's ultimately essential for R Markdown to achieve it's true potential!

[jebyrnes]

While I think that would be very cool (an Rstudio plugin?), I think just making sure criticmarkup renders would be huge. It's not hard to write in, and matches the just-work-in-a-text-editor philosophy. And would be less work/spur-on a plugin. Hence the request/question.

[jjallaire]

Yes, point taken.

It's actually possible to prototype this right now w/o changes to the rmarkdown package. You would write a Lua filter that does the appropriate substitutions (i.e. Critic Markup to HTML) then add the Lua filter to your Rmd using e.g.

---
title: "Doc with Critic Markup"
output:
   html_document:
      pandoc_args: ["--lua-filter", "/path/to/filter.lua"]
---

Here's an example of writing a simple Lua filter that does the same sort of macro substitution as you'd need for Critic Markup: https://pandoc.org/lua-filters.html#macro-substitution.

I realize that this would be best implemented inside the rmarkdown package but given that we don't be working on this in the near future I just wanted to point out that there is a path forward in the meantime via pandoc filters.

[noamross]

I needed a related filter and wrote a quick one to translate MS word tracked changes to markdown with CriticMarkup. Here's a first take: https://gist.github.com/noamross/12e67a8d8d1fb71c4669cd1ceb9bbcf9

[dmi3kno]

I just want to link a few things here.

• A discussion on SO related to various ways to put comment in the markdown.
• Archived unimplemented [issue] (ropensci/unconf17#86) in the RopenSci Unconf'17 repo.

[ailich]

I don't really have anything to add on the technical side, but I just wanted to say that with Quarto gaining popularity I think adding this feature could allow for consistency in how to collaborate using notebooks regardless of your coding language and would make collaboration for science/technical writing a lot easier especially with how great RStudio's visual editor is now.

[cderv]

with Quarto gaining popularity I think adding this feature could allow for consistency in how to collaborate using notebooks regardless of your coding language

Hi @ailich, do you mean this feature should be something to include in Quarto in priority ? There is related discussion about this in https://github.com/quarto-dev/quarto-cli/discussions/449 for reference

[ailich]

@cderv I do think it is something that should be considered for both inclusion in Quarto (so it knows how to render the document) and for Rstudio's visual editor (which would make it more user friendly and easy to visualize). Quarto seems to be focused on making markdown based code notebooks better for technical/scientific writing (e.g cross-referencing support), but one of the main challenges is still collaboration, especially with people who have less experience with the tools. Having a menu in Rstudio's visual editor to track changes/make comments and automatically have it add critic markup code to the source version in my opinion would be a game changer. Quarto would then need to understand how to render that code (e.g. reject all changes and render or accept all changes and render).

[cderv]

I agree ! I think this will be something definitely tackle within the Quarto project https://github.com/quarto-dev/quarto-cli/discussions/405