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-"
)
library("worldbet")
inline <- "/`r convert_bet_to_entity('SIp')`/"
```

# worldbet: Convert WorldBet to IPA

This micropackage converts [WorldBet] ASCII characters for English sounds into
UTF-8 character and HTML entities.

[WorldBet]: https://www.ling.ohio-state.edu/~edwards/WorldBet/worldbet.pdf

## Inside of R: RStudio

RStudio has rich support for UTF-8 symbols. Here is how some WorldBet-to-IPA
conversions look in RStudio.

```{r, eval = FALSE}
library("worldbet")

# that
convert_bet_to_ipa("D@t")
#> [1] "ðæt"

# uh-oh
convert_bet_to_ipa("^?o")
#> [1] "ʌʔo"

# water, weather (vector input)
convert_bet_to_ipa(c("wA)&_r", "wED&_r"))
#> [1] "wɑɾɚ" "wɛðɚ"
```

## Inside of R: Command Line

From the command prompt on Windows, R falls back to escape sequences during
the conversions.

```{r}
# that
convert_bet_to_ipa("D@t")

# uh-oh
convert_bet_to_ipa("^?o")

# water, weather (vector input)
convert_bet_to_ipa(c("wA)&_r", "wED&_r"))
```

## Outside of R: HTML Entities

For RMarkdown documents, we can use HTML entities for in-text use of IPA. For
example, we could write the following RMarkdown in our prose:

```
The word was `r inline` ("ship").

```

RMarkdown-to-markdown conversion then yields the following text with HTML 
entities instead of WorldBet symbols:

```
The word was /`r convert_bet_to_entity("SIp")`/ ("ship").
```

Finally, markdown-to-HTML conversion yields the following human-readable form of
the symbols.

> The word was /`r convert_bet_to_entity("SIp")`/ ("ship").

## WorldBet specification

The table below shows the implementation of the WorldBet used in the package.

```{r, echo = FALSE, warning = FALSE, message = FALSE}
library("dplyr")
as_literal <- function(xs) sprintf("`%s`", xs)
worldbet_key %>% 
  mutate(HTML_Entity = as_literal(Entity),
         WorldBet = as_literal(WorldBet)) %>% 
  select(WorldBet, IPA = Entity, `HTML Entity` = HTML_Entity) %>% 
  knitr::kable(.)
```