conig / revise

R package for writing revise and resubmits

revise

The goal of revise is to support authors in responding to revise and resubmit requests. These functions are designed to work with crsh/papaja.

Installation

You can install the development version of {revise} from GitHub with:

# install.packages("remotes")
remotes::install_github("conig/revise")

Starting a revision document

ReviewerComment addin

We have included an addin so you can mark text as a reviewer comment. If a YAML header is not detected in document the addin will add it. Fields will automatically be filled in if there is a .rmd file in the working directory. Additionally, selected text will be marked as a reviewer comment by including it within an “asis” chunk. Text below this chunk will be tagged as an author response. A hotkey can be set for this addin (e.g. Ctrl+Shift+R).

animation of ReviewerComment addin

Loading a manuscript

You can use rmd or docx files with revise. To load either, simply call revise::read_manuscript(“your_file.rmd”)

For example. Here is an example docx where content has been tagged with comment boxes. E.g, Revise::hard

docx_path <- system.file("examples/word_test.docx", package = "revise")

man <- read_manuscript(docx_path)
man
#> <Manuscript>
#> �[34m- 6 sections�[39m
#> �[31mNo PDF attached�[39m

We can see all tagged sections by running

names(man$sections)
#> [1] "track_changes" "section"       "multi_lines"   "bullets"       "hard"          "numbered"

Then we can retrieve using a section name

revision <- get_revision("hard", man)
revision
#> [1] ">Hard example\n>\n>This section has all features:\n>\n>* Bullet1\n>\n>* Bullet2\n>\n>* Bullet3\n>\n>Some more text is here."

This content can then be put directly into a response document using single backticks.

revise's Issues

Suggestion: Replace errors with warnings or messages where possible

Errors stop the knitting process, even when that's not necessary (e.g., when a section id is misspelled). To prevent this, I suggest replacing erorrs with warnings and providing an informative message in the document.

restart comment count for each reviewer

I think it would be nice to restart the comment counter for each editor/reviewer.

Can we include supports for {projmgr}?

https://github.com/emilyriederer/projmgr

Revise and resubmit letter in pure rmarkdown

We could potentially create a revise and resubmit letter where users can write only with markdown and include minimal LaTeX code.

API will need to be discussed and designed.

Elements which will need representation:

• Reviewer comments
• Author responses
• Manuscript quotes
• Margin comments

better error handling for get_revision

I think it would be good to have some more informative error messages for get_revision. I think the most critical is get_revision should check is target %in% names(manuscript$sections) or something similar?

Submit package to CRAN

Dear @conig , are you considering to publish the package any time soon? I am really enjoying it, would be nice to have it in a standard repository!

Quote boxes spanning more than one page overloads tex capacity

I think there might be issues with the use of agrep for pulling large sections from a paper. When a span tag covers lots of text I am getting an out of memory error. Might be good to issue a warning to turn pdf=FALSE in read_manuscript to solve?

Should we export a specific environment for storing manuscripts?

@cjvanlissa I'm really enjoying the new functionality you've built where manuscripts are automatically cached and searched.

I was wondering about the edge-case where users want to remove a manuscript from the cache (maybe they loaded the wrong manuscript erroniously). Is there an easy way to find and wipe the correct env at the moment, or do they have to restart the R session?

One solution might be to export an environment specifically for this functionality where users can easily see what objects are in there, and remove objects as needed e.g., revise::manuscript_locker. Would you be in favour of such a change or do you have concerns?

Margin notes

\usepackage[draft]{todonotes}

e.g.

\todo{Revision due: March 15, 2021}

\comment does not appear in docx or txt

\comment only appears in pdf. A system is needed which is agnostic to output type.

Example:

```{asis e1}
Reviewer comment
```
Refer back to \comment{e1}

Rendering brackets method to md or html removes bracketed section

Performing more tests, I find that text in brackets, e.g. [section]{#tag} is inconsistently rendered. In md_document and html_document, it is removed entirely. In pdf_document, the behavior depends on pandoc version: 2.18 renders as intended (no square brackets, yes text); 2.19.2 renders square brackets in text.

Dependency textreadr is not on CRAN anymore

Consequently, all integration tests fail with:

* checking package dependencies ... ERROR
Package required but not available: 'textreadr'

Highlight changed text in context

Just chucking this up as something to look at in the future, while I'm thinking about it.

It would be good to be able to indicate what was changed in the manuscript, while also being able to show the context of the change. E.g., by showing a full paragraph, but highlighting the sections that were changed. It could look something like

<span id = "rev1_com2">
This is some old text.
This is also old text.
<span class = "changed"> 
Look I made that change you wanted.
</span>
Here is the rest of the paragraph.
</span>

And have it render in the revision letter as:

This is some old text. This is also old text. Look I made that change you wanted. Here is the rest of the paragraph.

Enable reviewer engine chunk name to be changed

Currently users can indicate text as being a reviewer comment with one of two chunks:

```{asis}

```

or

```{reviewer}

```

My preference is to only support "reviewer" but rstudio currently uses r syntax highlighting for all unknown engines. This is bug and should be fixed in the future.

E.g.

For the time being 'asis' is the default and is created by the ReviewerComment addin.

Co-opting asis could be annoying for some users as there might be other uses for this chunk type. Accordingly users should be able to choose the chunk name they want to indicate a reviewer comment.

This could be done with an options call

options(reviewer_chunkname)

This option call would change the behaviour of ReviewerComment as well as assign the process_chunk functions to the new engine name.

Write documentation

We need documentation to give users an overview of features and limitations.

Make code generated revise doc instantly knitable without changing YAML

Limitations on []{#} text extraction

[]{#} tagging currently works for most circumstances, including nested references.

nested <- "[This [text]{#inner} has nested references[@ref]]{#outer}"

revise:::extract_md_sections2(nested)
#>     tag                               section
#> 1 inner                                  text
#> 2 outer This text has nested references[@ref]

But will fail if square brackets are used for anything other than references

sic <- "This sentence [includes square brackets which aren't [sic] references]{#example}"

revise:::extract_md_sections2(sic)
#>       tag         section
#> 1 example sic] references

For these situations the workaround is to use span tagging until a system with proper parentheses matching is implemented.

Merge manuscript objects

So that revisions can be extracted from multiple documents without having to keep them in multiple objects

Consider removing argument `id` from read_manuscript

There's no need to maintain backwards compatibility, because the package is not yet on CRAN. Better to streamline the interface before submitting

Reviewer comment anchor links

I am wondering if we auto add and populate link anchors for the reviewerComment add-in?

Justification causes overflow

This is particularly the case in the quote boxes. I suggest we change:

\usepackage[none]{hyphenat}

to

\usepackage{hyphenat}

with \hyphenpenalty=50

Sections on multiple lines are not parsed

I love the idea of this package and have used it for a revision I'm writing - but when trying to knit my action letter, I noticed that sections on multiple lines don't parse, which is a limitation because - to properly version control my manuscript - it is important that every sentence starts on a newline.

AnchorTag places cursor incorrectly when there are multiple anchors on a single line.

Make `id` the first argument of get_revision()

This allows the following syntax to be valid:

read_manuscript("manuscript.Rmd")
get_revision("a_revision")

The manuscript is loaded into an invisible environment variable.

include warning about Rstudio visual editor?

the visual editor really screws up the add-ins and often the md tagging. So sick of seeing {#}

Load manuscript objects directly into an environment variable

In addition to (optionally) assigning them. This makes it possible to just run get_revision("revid")

get_revision escaping $ leading to formula failure

When a chunk has a formula, get_revision seems to escape $ signs e.g. from the knited tex file:

`$$

\beta = B \times \frac{SD_x}{IQR_y}

$$`

Create rmd template for the revision letter.

Replace Remotes: crsh/papaja with Imports: papaja

As papaja now lives on CRAN