---
title: "Use of `plantuml` with knitr"
output:
  rmarkdown::html_vignette: default
  pdf_document:
    latex_engine: xelatex
vignette: >
  %\VignetteIndexEntry{Use of `plantuml` with knitr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
resource_files: graphs/*
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  cache = FALSE
)
```
# Register the plantuml knitr engine

The plantuml knitr engine `plantuml_knit_engine()` needs to be registered with knitr. This is done automatically when loading the package `plantuml`. 
```{r setup, include=TRUE}
library(plantuml)
```


## PlantUML Code Chunk Options

The following options are available, in addition to the standard options:

- `plantuml_format`: the format of the resulting file. At the moment, `png` (the default), `svg`, and `eps` are implemented.
- `plantuml.path`: the path at which the resulting graphs should be saved. If the directory does not exist, it will be created.
- `plantuml.preview`: if the graph should be shown as an inline preview in the Rmarkdown document in  Rstudio. This option results in generating the image twice, which may lead to a substantial increase of the processing time. The preview is **always** a vector preview, irrespective of the file `plantuml_format`

## A simple chart as png
A png grph is nice, because it can be shown in all kinds of documents, including html, pdf and docx. But it is a bitmap format, i.e. when scaling in the grapoh becomes pixelated.
```{plantuml diagram_png, eval = TRUE, echo = FALSE, plantuml.format = "png", plantuml.path = "graphs", plantuml.preview = TRUE}
left to right direction
actor "Food Critic" as fc
package Restaurant {
  usecase "Eat Food" as UC1
  usecase "Pay for Food" as UC2
  usecase "Drink" as UC3
}
fc --> UC1
fc --> UC2
fc --> UC3
```

## A simple chart as png and with code
To also show the plantuml code, you have to set `echo = TRUE`:
```{plantuml diagram_png_code, eval = TRUE, echo = TRUE, plantuml.format = "png", plantuml.path = "graphs"}
left to right direction
actor "Food Critic" as fc
package Restaurant {
  usecase "Eat Food" as UC1
  usecase "Pay for Food" as UC2
  usecase "Drink" as UC3
}
fc --> UC1
fc --> UC2
fc --> UC3
```

## A simple chart using format `auto` with code
When specifying `plantuml.format = "auto"` the apropriate vector format is chosen for the output format:

- pdf output format: `pdf` as `plantuml.format`
- html output format: `svg` `as plantuml.format`
- docx output format: `pdf` `as plantuml.format`

Therefore, the vector format appropritw for the output format is is chosen for the output format.

```{plantuml diagram_svg, eval = TRUE, plantuml.format = "auto", plantuml.path = "graphs"}
robust "DNS Resolver" as DNS
robust "Web Browser" as WB
concise "Web User" as WU

@0
WU is Idle
WB is Idle
DNS is Idle

@+100
WU -> WB : URL
WU is Waiting
WB is Processing

@+200
WB is Waiting
WB -> DNS@+50 : Resolve URL

@+100
DNS is Processing

@+300
DNS is Idle
```

## Now only the code
```{plantuml code, eval = FALSE, plantuml.format = "png", plantuml.path = "graphs"}
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
```

## And now as ASCII Art
This does not play nicely with LaTeX and therefore pdf due to unicode characters used. I have no idea at the moment how to make this nicer.
```{plantuml asciiart, eval = TRUE, plantuml.format = "txt", plantuml.path = "graphs", comment = ""}
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml
```