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:
Philip Parker philip.parker@acu.edu.au (ORCID)
Taren Sanders taren.sanders@acu.edu.au (ORCID)
Michael Noetel m.noetel@uq.edu.au (ORCID)
Caspar J. Van Lissa c.j.vanlissa@tilburguniversity.edu (ORCID)
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
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:
$sections: Extracted revisions
$PDF: Optionally, the PDF document
$refs: References to figures and tables
$rmd: The raw rmarkdown
$mtime: When the rmarkdown file was last modified
$checksum: A checksum of the rmarkdown file
$filename: The filename of the rmarkdown file
See Also
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
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 .