---
title: Printing Text in Color in Markdown / Quarto
format: html
vignette: >
  %\VignetteIndexEntry{Printing Text in Color in Markdown / Quarto}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
  %\VignetteDepends{grDevices,colorspace}
  %\VignetteKeywords{Quarto, HTML, PDF, color}
  %\VignettePackage{colorize}
---

```{r colorbox}
#| include: false
library("colorize")
oi <- palette.colors(names = TRUE)
```

The colorize package provides some simple functions for printing text in color in markdown or Quarto documents, to be rendered as HTML or LaTeX. This is useful when writing about the use of colors in graphs or tables, where you want to print their names in their actual color to give a direct impression of the color, like “red” shown in `r colorize("red")`, or “blue” shown in `r colorize("blue")`. 

The following functions are provided:

* `colorize(text, color)`: Print the `text` in a given `color`, as in `r colorize("this text in red", "red")`
* `colorize_bg(text, color)`: Print the `text` with a background in `color`, as in `r colorize_bg("this text in red", "red")`
* `colorbox(text, color, ...)`: Print `text` with background in color, but where the text is given a contrasting color designed to be most legible, as in `r colorbox("this text in red", "red")`

### Normal usage

In text describing analysis of the `penguins` data, to match the colors used in a graph,
you can simply use the functions like so

```{r}
#| echo: fenced
#| eval: false
`r colorize("Gentoo", "orange")` and  `r colorize("Adelie", "purple")` and  
`r colorize("Chinstrap", "darkgreen")` are Penguins.

This plot has `r colorize("red")` points, `r colorize("blue")` points, 
`r colorize("green")` points, which are nice!
Other colors used in the plot are `r colorize("yellow")`, `r colorize("pink")`, 
`r colorize("gray")` and `r colorize("black")`.

As you can see, `r colorize("yellow")` and `r colorize("pink")` are illegible on a white background,
but `r colorbox("yellow")` and `r colorbox("pink")` work fine.
```

This renders as:

`r colorize("Gentoo", "orange")` and  `r colorize("Adelie", "purple")` and  `r colorize("Chinstrap", "darkgreen")` are Penguins.

This plot has `r colorize("red")` points, `r colorize("blue")` points, `r colorize("green")` points, which are nice!
Other colors used in the plot are `r colorize("yellow")`, `r colorize("pink")`, `r colorize("gray")` and `r colorize("black")`.

As you can see, `r colorize("yellow")` and `r colorize("pink")` are illegible on a white background,
but in a `colorbox()`,  `r colorbox("yellow")` and `r colorbox("pink")` work fine.

### Named colors

_Idea:_ Named colors can just be included via `colorbox()` with just their name, e.g., `colorbox("red")` for `r colorbox("red")`. 

_Examples:_
`r colorbox("black")`,
`r colorbox("gray")`,
`r colorbox("red")`,
`r colorbox("orange")`,
`r colorbox("yellow")`,
`r colorbox("green")`,
`r colorbox("blue")`,
`r colorbox("cyan")`,
`r colorbox("magenta")`,
`r colorbox("pink")`,
`r colorbox("darkgreen")`,
`r colorbox("purple")`.

`colorize()` simply prints the color name in that color 

_Examples_:
`r colorize("black")`,
`r colorize("gray")`,
`r colorize("red")`,
`r colorize("orange")`,
`r colorize("yellow")`,
`r colorize("green")`,
`r colorize("blue")`,
`r colorize("cyan")`,
`r colorize("magenta")`,
`r colorize("pink")`,
`r colorize("darkgreen")`,
`r colorize("purple")`.

### LaTeX color names

You must be careful with LaTeX output. Quarto and markdown typically use the [`xcolor` package](https://ctan.org/pkg/xcolor). This does not define all the
color names available in R or HTML and so will trigger LaTeX errors if a color name is undefined. 

For example, `darkgreen` is not defined there, but you can use:
`\definecolor{darkgreen}{RGB}{1,50,32}` in a document to be rendered to PDF.

<!-- _Idea_: You can refer to the color of data elements used in plots -->


### Hex colors

_Idea:_ Hex colors can be included via `colorbox()` using two arguments, their verbal description (or text to be printed)
and the precise hex color code,
e.g., `colorbox("bluishgreen", "#009E73")` for `r colorbox("bluishgreen", "#009E73")`.

_Examples:_ The Okabe-Ito palette as provided (by default) by `grDevices::palette.colors(names = TRUE)` has following elements,

```{r}
oi <- palette.colors(names = TRUE) |>
  print()
```

Rendering each of these as `colorbox()`, using their names (`names(oi)[i]`) and values (`oi[i]`) gives: 

`r colorbox(names(oi)[1], oi[1])`,
`r colorbox(names(oi)[2], oi[2])`,
`r colorbox(names(oi)[3], oi[3])`,
`r colorbox(names(oi)[4], oi[4])`,
`r colorbox(names(oi)[5], oi[5])`,
`r colorbox(names(oi)[6], oi[6])`,
`r colorbox(names(oi)[7], oi[7])`,
`r colorbox(names(oi)[8], oi[8])`,
`r colorbox(names(oi)[9], oi[9])`.

### Defining color variables in your document

If you want to more easily use colorized color names in your document, in a chunk somewhere you can simply create them as variables,
whichever of `colorize()`, `color_bg()` or `colorbox()` suits your needs. 
For example:

```{r name-colors}
red <- colorize('red')
pink <- colorize("pink")
blue <- colorize('blue')
green <- colorize("green")
yellow <- colorize("yellow")
lightgreen <- colorize("lightgreen")
darkgreen <- colorize("darkgreen")
```

Then, you can use them directly in text as [inline code](https://quarto.org/docs/computations/inline-code.html) (r code, enclosed in backticks), 
giving "this line is `r red`", "that point is `r blue`".

You can also use these with `glue::glue()` more simply as "this line is {red}, this point is {blue}", which interpolates their values into
a string. 

I use this to create colorized text in figure captions, where, in Quarto, it is necessary to use `!expr` to have the text of the caption
evaluated:

```{r}
#| echo: fenced
#| eval: false
#| label: fig-Salaries-loess
#| fig-cap: !expr glue::glue("Scatterplot of Salary vs. years since PhD, adding the loess smooth. 
#|    The loess smooth curve and confidence band in {green} is nearly indistinguishable 
#|    from a quadratic fit in {blue}.")

gg1 + 
  geom_smooth(method = "loess", formula = "y ~ x", 
              color = "blue", fill = scales::muted("blue"),
              linewidth = 2) +
  geom_smooth(method = "lm", formula = "y ~ x", se = FALSE,
              color = "red",
              linewidth = 2) +
  geom_smooth(method = "lm", formula = "y ~ poly(x,2)", 
              color = "darkgreen", fill = "lightgreen",
              linewidth = 2) 
```

