Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dmurdoch/rmdconcord

Concordances for R Markdown
https://github.com/dmurdoch/rmdconcord

Last synced: about 22 hours ago
JSON representation

Concordances for R Markdown

Awesome Lists containing this project

README 

        
---

output: github_document

---



```{r setupREADME, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

```



# RmdConcord



[![R-CMD-check](https://github.com/dmurdoch/RmdConcord/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/dmurdoch/RmdConcord/actions/workflows/R-CMD-check.yaml)



The goal of RmdConcord is to provide support for concordances

in R Markdown files.



This is based on a suggestion and initial code from Heather Turner.

Thanks!



Rmarkdown files (type `.Rmd`) allow presentation articles to be generated from

simple text documents. However, if there are errors, these can be

difficult to track back to the originating markdown text because there are

often intermediate stages:  the R Markdown file is converted to plain

Markdown, the plain Markdown is converted to HTML or LaTeX, the LaTeX is 

converted to PDF. A concordance that allows back-tracking of errors from

the later steps is needed.



The main use for this in HTML output is to help deciphering HTML Tidy

error messages.  If you replace the original driver with `RmdConcord::html_documentC`, 

`R CMD check` should report locations in the original `.Rmd` file.



With PDF output using `patchDVI::pdf_documentC` (from

`patchDVI` version 1.11.0 or newer), Synctex output will be enabled, and it will be patched

to refer to the `.Rmd` file.  This is helpful in previewers like

the one in [TeXworks](https://www.tug.org/texworks/) that can link source to a

preview. This package contains

`RmdConcord::pdf_documentC0`, which does part

of the work (preparing the concordance records)

but doesn't do the patching to make previewers 

work with it.



## Limitations



The Pandoc Commonmark driver is still in

development, so some features supported in

the `rmarkdown` drivers will not be fully

supported using the drivers from this package.

At present I am using Pandoc 2.19.2 and I know of the following

missing features:



- Citations, e.g. `[@doe99]`

- Raw LaTeX will need to be “fenced”, e.g. entered as

  ````

  ```{=latex}

  LaTeX

  ```

  ````

  (The `\pagebreak` and `\newpage` macros receive special treatment, so they don’t need fencing as long as they are separated by blank lines from text above and below.) 



If you notice others, please let me know, e.g.

by posting an issue to the Github site.



These will not cause errors (Markdown doesn't

ever give errors!), but they won't be handled

properly.  We suggest using the `RmdConcord` and `patchDVI` drivers during

early development or to track down obscure bugs,

but using the `rmarkdown` drivers for regular

production.



## Installation



This version of `RmdConcord` makes use of some functions that

will be released in R 4.3.0.  Those functions have

been copied into `RmdConcord`, so the package should

be compatible with older versions of R.



You can install the development version of

`RmdConcord` from [GitHub](https://github.com/) with:



``` r

# install.packages("devtools")

devtools::install_github("dmurdoch/RmdConcord")

```



## Example



To embed concordances in an R Markdown HTML document, change

the output YAML to `patchDVI::html_documentC`.  For a PDF document,

use `patchDVI::pdf_documentC`.



```yaml

output: patchDVI::html_documentC

```



This is used in the `Sample.Rmd` vignette, which contains an error on line 23.



```{r example}

library(RmdConcord)

example(processConcordance)

```