Title: Dynamic Revision Letters for 'Rmarkdown' Manuscripts
Version: 0.1.0
Description: Extracts tagged text from markdown manuscripts for inclusion in dynamically generated revision letters. Provides an R markdown template based on papaja::revision_letter_pdf() with comment cross-referencing, a system for managing multiple sections of extracted text, and a way to automatically determine the page number of quoted sections from PDF manuscripts.
License: MIT + file LICENCE
URL: https://github.com/conig/revise
BugReports: https://github.com/conig/revise/issues
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.1.0)
Imports: bookdown, dplyr, glue, knitr, papaja, rmarkdown, rstudioapi, stringr, pdftools, officer, xml2, worcs, cli
Suggests: googledrive, docxtractr, testthat (≥ 3.0.0)
Config/testthat/edition: 3
SystemRequirements: pandoc (>= 1.14) - http://pandoc.org
NeedsCompilation: no
Packaged: 2025-03-04 00:40:21 UTC; conig
Author: James Conigrave ORCID iD [aut, cre], Philip Parker ORCID iD [aut], Taren Sanders ORCID iD [aut], Michael Noetel ORCID iD [aut], Caspar J. Van Lissa ORCID iD [aut]
Maintainer: James Conigrave <james.conigrave@gmail.com>
Repository: CRAN
Date/Publication: 2025-03-05 15:50:02 UTC

revise: Tools for Formulating Revise and Resubmit Rmarkdown Documents

Description

When writing scientific manuscripts, it is challenging to keep revisions synchronized between the manuscript and the action letter detailing responses to reviewers.

Details

Revise automates this process. Sections in the manuscript can be tagged, and inserted into the action letter.

Author(s)

Maintainer: James Conigrave james.conigrave@gmail.com (ORCID)

Authors:

See Also

Useful links:

reviewer_comment

Description

A comment to style chunks for reviewer comments

Usage

anchor_tag()

drive_comments

Description

Extract comments from a google docs document

Usage

drive_comments(url, email = NULL, cache_credentials = NULL)

Arguments

url

URL to drive document

email

drive email account. Can be set with options(gargle_oath_email)

cache_credentials

bool. Should cached credentials be used? Can be set with options(gargle_oauth_cache)

Value

A list with a length equal to the number of comments. Each element corresponds to one comment: the element's name is the comment text, and its value is the text that was bounded by the comment.

extract_refs

Description

Extract table and figure references

Usage

extract_refs(path)

Arguments

path

to markdown manuscript

extract_sections

Description

Extract sections from text string

Usage

extract_sections(string, is_span = FALSE)

Arguments

string

string to extract md sections from

is_span

logical, whether to extract sections in square brackets (default) or spans

Extract Tagged Text from a Manuscript

Description

Retrieves and formats a specified section from a revise_manuscript object based on its ID.

Usage

get_revision(
  id,
  manuscript = NULL,
  quote = TRUE,
  evaluate = TRUE,
  split_string = FALSE,
  search_length = 300,
  include_pgnum = TRUE,
  revise_errors = getOption("revise_errors"),
  envir = parent.frame(1L)
)

Arguments

id

the id as a character string from a html or markdown tag

manuscript

Optional; a revise_manuscript object in which to search for id. Defaults to NULL, in which case the manuscript object is found in the environment.

quote

should the output string be quoted by inserting '>' before the string?

evaluate

logical. Should inline rchunks be executed?

split_string

should only the start and end of the string be searched for?

search_length

numeric. Searches for the first n and n characters in a string. Shorten if difficult to find passages split by floats.

include_pgnum

logical. include PDF page number? Requires a PDF to be provided to the manuscript object.

revise_errors

logical. If FALSE, failure to match manuscript sections will result in warnings rather than errors.

envir

The environment in which to find the manuscript.

Value

A character vector of length 1 containing the text extracted from the manuscript that was tagged with id, including any modifications as specified by the arguments.

List Manuscripts in Environment

Description

Returns a character vector with the names of manuscripts loaded in a given environment.

Usage

list_manuscripts(envir = parent.frame(1))

Arguments

envir

The environment in which to check for manuscripts.

Value

A character vector, or NULL if no manuscripts exist in the environment.

Examples

temp_file <- tempfile(fileext = ".Rmd")
write("`r 1 + 1", file = temp_file)

read_manuscript(temp_file)
list_manuscripts()

Mask Text for Blind Review

Description

The YAML front matter tag mask determines whether the text is displayed or replaced by mask_message. The YAML tag can take the values yes or no.

Usage

mask(
  x,
  mask_message = "masked for blind review",
  hide = rmarkdown::metadata$mask
)

Arguments

x

Atomic character vector to be masked.

mask_message

Atomic character vector to mask x with when mask: yes, Default: 'masked for blind review'

hide

Logical, Default: rmarkdown::metadata$mask

Value

Character vector.

See Also

metadata

Examples

mask("this is masked", hide = TRUE)

read_docx

Description

Read a docx file and extract comments

Usage

read_docx(path)

Arguments

path

path to docx

Read 'Rmarkdown' Manuscript

Description

Reads an 'Rmarkdown' manuscript and, if possible, an associated PDF.

Usage

read_manuscript(
  path,
  PDF = FALSE,
  to_envir = getOption("revise_use_envir", TRUE),
  envir = parent.frame(1)
)

Arguments

path

Character, path to the 'Rmarkdown' file.

PDF

Logical or character. Default FALSE does nothing. If set to TRUE, attempts to determine PDF file path from YAML front matter. If character, should be the path to the PDF rendered from the 'Rmarkdown' file. This PDF will be loaded for page matching.

to_envir

Logical, indicating whether or not the manuscript should be invisibly assigned to an environment variable names .revise_manuscript. Defaults to TRUE. Can be disabled by setting options(revise_use_envir = FALSE).

envir

The environment to which the manuscript should be assigned.

Details

If to_envir is TRUE, the manuscript is invisibly assigned to the specified environment for later use by other revise functions. For example, this allows get_revision to work without specifying a manuscript. This behaviour can be disabled by setting options(revise_use_envir = FALSE).

Value

Invisibly returns a list of class manuscript, containing the following elements:

See Also

yaml_front_matter fileutils

Examples

tempfile <- tempfile("tmp", fileext = ".txt")
writeLines("[Maecenas mollis consectetur purus.]{#test}", con = tempfile)
read_manuscript(tempfile)

read_md

Description

Read in a markdown document for further analysis

Usage

read_md(path)

Arguments

path

to markdown manuscript

Remove Manuscript from Environment

Description

Removes a revise_manuscript from a given environment by name.

Usage

remove_manuscript(manuscript = NULL, envir = parent.frame(1))

Arguments

manuscript

A character vector of revise_manuscript names that exist in envir.

envir

The environment from which to remove the manuscript.

Value

Invisibly returns TRUE if successful, and FALSE otherwise.

Examples

temp_file <- tempfile(fileext = ".Rmd")
write("`r 1 + 1", file = temp_file)
read_manuscript(temp_file)
result <- remove_manuscript(list_manuscripts()[1])
# See that remove_manuscript() silently returns TRUE
print(result)
# See that there are no more manuscripts in envir
list_manuscripts()

reviewer_comment

Description

A comment to style chunks for reviewer comments

Usage

reviewer_comment()

Dynamic docx Revision Letter

Description

Template for creating journal revision letters with dynamic excerpts from a manuscript.

Usage

revise_letter_docx(...)

Arguments

...

Arguments passed on to bookdown::word_document2().

Details

This function wraps bookdown::word_document2().

Value

An R Markdown output format object to be passed to rmarkdown::render().

See Also

bookdown::word_document2()

Dynamic PDF Revision Letter

Description

Template for creating journal revision letters with dynamic excerpts from a manuscript.

Usage

revise_letter_pdf(...)

Arguments

...

Arguments passed on to papaja::revision_letter_pdf().

Details

This function wraps papaja::revision_letter_pdf().

Value

R Markdown output format to pass to rmarkdown::render().

See Also

papaja::revision_letter_pdf(), bookdown::pdf_document2(), rmarkdown::pdf_document()

Dynamic txt Revision Letter

Description

Template for creating journal revision letters with dynamic excerpts from a manuscript.

Usage

revise_letter_txt(...)

Arguments

...

Arguments passed on to rmarkdown::output_format().

Details

This function wraps rmarkdown::output_format().

Value

An R Markdown output format definition that can be passed to render.

See Also

rmarkdown::output_format()