README.Rmd

---
output:
  md_document:
    variant: markdown_github
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# ggtextparallels

The goal of ggtextparallels is twofold: (1) to approximate fancy and expensive tools like the *Synopsis Quattuor Evangeliorum*, an essential tool for biblical scholars; and (2) to study biblical passages across multiple translations. Thanks to the people at [BibleSearch](http://bibles.org/eng-GNTD/Gen/1) `ggtextparallels` now supports over 300 versions across 277 languages. 

## Installation

`ggtextparallels` is not on CRAN, but can be installed with `devtools`:

```{r eval=FALSE}
devtools::install_github("daranzolin/ggtextparallels")
library(ggtextparallels)
```

## Preparation

`ggtextparallels` relies on two APIs: the Perseus Digital Library and BibleSearch. An API key is required to access the versions and translations from BibleSearch, but [you can obtain one free here.](http://bibles.org/pages/api) Add the key to your .Renviron, and install `rbiblesearch` from GitHub:

```{r eval = FALSE}
devtools::install_github("daranzolin/rbiblesearch")
rbiblesearch::set_biblesearch_key("your_key_here")
```

## ggtextparallel

`ggtextparallel` creates a grid of text for common stories across the four gospels. In the examples below, the story of the healing of Peter's Mother-in-law is displayed in its Matthean, Markan, and Lukan contexts. 

The function takes three arguments: a `parallel_no`, which can be gleaned from `gospel_parallels`, `version`, 304 of which can be obtained from `biblesearch_versions`, and `words_per_row`, which allows users to adjust the amount of words displayed on each row.

```{r echo = FALSE}
tibble::as.tibble(ggtextparallels::biblesearch_versions)
```


367 gospel parallels are available:

```{r echo=FALSE}
library(ggtextparallels)
t <- tibble::as.tibble(gospel_parallels)
dplyr::select(t, Pericope, Matthew, Mark, Luke, John)
```

Words common to each pericope are listed in the plot caption.

## Examples

### English (ESV)

Here I request the English, ESV translation of 'The Healing of Peter's Mother-in-Law':

```{r example, fig.width=12}
ggtextparallel(parallel_no = 37, version = "eng-ESV", words_per_row = 6)
```

### Koine Greek

Flip the `version` argument to "grc":

```{r, fig.width=12}
ggtextparallel(37, "grc", 5)
```

### Spanish (Biblia Reina Valera 1960)

```{r, fig.width=12}
ggtextparallel(37, "spa-RVR1960", 6)
```

## gglangparallel

`gglangparallel` has a similar output, but the facets are by *version* instead of book. In the example below, Romans 5:6 is displayed in English (ESV), Spanish, and French.

```{r, fig.width=12}
gglangparallel(versions = c("eng-ESV", "spa-RVR1960", "fra-LSG"), book = "romans", verses = "5:6", words_per_row = 7)
```


* Common word highlighting
* Vignette
* shiny app