---
title: "Printing (PDF)"
output: pdf_document
vignette: >
  %\VignetteIndexEntry{Printing (PDF)}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
pkgdown:
  as_is: true
  extension: pdf
---

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

This article is about PDF printing specifically. To learn the many other ways to print, export, or save `surveytable` tables, see `vignette("Printing")`.

# Basic printing

If a tabulation function is called from the top level, it should print out its table(s) on its own. 

As usual, first, let's start up the package and pick a survey to analyze:

```r
library(surveytable)
set_survey(namcs2019sv)
```

```{r, results='asis', echo=FALSE, message=FALSE}
library(surveytable)
set_opts(output = "kableExtra")
set_survey(namcs2019sv)
```

Now, when a tabulation function is called from the top level, it prints. You don't need to do anything extra.

```{r, results='asis'}
tab("AGER")
```

If a tabulation function is called not from the top level, such as from within a loop or another function, you do need to call `print()` explicitly for it to print. For example:

```{r, results='asis'}
for (vr in c("AGER", "SEX")) {
  print( tab_subset(vr, "MAJOR", "Preventive care") )
}
```

# Create HTML or PDF tables

Using a Quarto document, you can create tables in many different formats, such as HTML or PDF. Here is a straightforward example of what a Quarto document might look like: 

<!-- https://yihui.org/knitr/faq/ --> 

````{verbatim}
---
title: "My tables"
author: "Me"
format: pdf
---

# Welcome 

As usual, first, let's start up the package and pick a survey to analyze:

```{r, results='asis'}
library(surveytable)
set_survey(namcs2019sv, output = 'auto')
```

# Tables

Take a look at this table:

```{r, results='asis'}
tab("AGER")
```
````

Note the `format` setting, which specifies that this document will create PDF tables. Also note that you do have to add the `results='asis'` argument to the code chunks that print tables. 

# Print using various table-making packages

Use the `output` argument of `set_opts()` to select a table-making package. By default (`output = "auto"`), `surveytable` automatically selects a package depending on whether the output is to the screen (`huxtable`), HTML (`gt`), or PDF (`kableExtra`). You can also explicitly select one of these packages.

Changing the table-making package has a couple of uses:

* It allows you to generate tables in the way that you prefer.
* It allows you to print those tables to a variety of destinations, including the screen, HTML files, or PDF files.

## `kableExtra`

```{r}
set_opts(output = "kableExtra")
```

We have not implemented screen printing with `kableExtra` yet. Try one of the other packages.

Here is PDF:

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````
```{r, results='asis', echo=FALSE}
tab("AGER")
```

## `auto`

`auto` is the default option. It automatically selects one of the above packages depending on whether the output is to the screen (`huxtable`), HTML (`gt`), or PDF (`kableExtra`).

```{r}
set_opts(output = "auto")
```

PDF output (this should use `kableExtra`):

````{verbatim}
```{r, results='asis'}
tab("AGER")
```
````

```{r, results='asis', echo=FALSE}
tab("AGER")
```

# More

To learn the many other ways to print, export, or save `surveytable` tables, see `vignette("Printing")`.