Add acknowledgement & bump version for CRAN release
diff --git a/vignettes/awesome_table_in_html.Rmd b/vignettes/awesome_table_in_html.Rmd
index 47d71d8..0ed1595 100644
--- a/vignettes/awesome_table_in_html.Rmd
+++ b/vignettes/awesome_table_in_html.Rmd
@@ -184,7 +184,8 @@
```{r}
iris[1:10, ] %>%
mutate_if(is.numeric, function(x) {
- cell_spec(x, "html", bold = T, color = spec_color(x, end = 0.9),
+ cell_spec(x, "html", bold = T,
+ color = spec_color(x, end = 0.9),
font_size = spec_font_size(x))
}) %>%
mutate(Species = cell_spec(
diff --git a/vignettes/awesome_table_in_pdf.Rmd b/vignettes/awesome_table_in_pdf.Rmd
index 1112e24..eacd8e6 100644
--- a/vignettes/awesome_table_in_pdf.Rmd
+++ b/vignettes/awesome_table_in_pdf.Rmd
@@ -18,7 +18,9 @@
- \usepackage{pdflscape}
- \usepackage{tabu}
- \usepackage{threeparttable}
+ - \usepackage{threeparttablex}
- \usepackage[normalem]{ulem}
+ - \usepackage{makecell}
vignette: >
%\VignetteIndexEntry{Create Awesome PDF Table with knitr::kable and kableExtra}
%\VignetteEngine{knitr::rmarkdown}
@@ -64,7 +66,7 @@
```{r, eval = FALSE}
# Not evaluated. Ilustration purpose
-options(kableExtra.latex.load_package = FALSE)
+options(kableExtra.latex.load_packages = FALSE)
library(kableExtra)
```
@@ -83,7 +85,10 @@
- \usepackage{pdflscape}
- \usepackage{tabu}
- \usepackage{threeparttable}
+ - \usepackage{threeparttablex}
- \usepackage[normalem]{ulem}
+ - \usepackage{makecell}
+
```
## Plain LaTeX
@@ -318,6 +323,21 @@
# Not evaluated. The code above should have the same result as the first example in this section.
```
+Note that `kable` has a relatively special feature to handle `align` and it may bring troubles to you if you are not using it correctly. In the documentation of the `align` argument of `kable`, it says:
+
+> If `length(align) == 1L`, the string will be expanded to a vector of individual letters, e.g. `'clc'` becomes `c('c', 'l', 'c')`, **unless the output format is LaTeX**.
+
+For example,
+```{r, eval=F}
+kable(mtcars[1:2, 1:2], "latex", align = c("cl"))
+# \begin{tabular}{l|cl|cl} # Note the column alignment here
+# \hline
+# & mpg & cyl\\
+# ...
+```
+
+LaTeX, somehow shows surprisingly high tolerance on that, which is quite unusual. As a result, it won't throw an error if you are just using `kable` to make some simple tables. However, when you use `kableExtra` to make some advanced modification, it will start to throw some bugs. As a result, please try to form a habbit of using a vector in the `align` argument for `kable` (tip: you can use `rep` function to replicate elements. For example, `c("c", rep("l", 10))`).
+
## Row indentation
Unlike `group_rows()`, which will insert a labeling row, sometimes we want to list a few sub groups under a total one. In that case, `add_indent()` is probably more apporiate.
For advanced users, you can even define your own css for the group labeling.
@@ -381,7 +401,6 @@
row_group_label_fonts = row_group_label_fonts)
```
-
# Table Footnote
> Now it's recommended to use the new `footnote` function instead of `add_footnote` to make table footnotes.
@@ -431,7 +450,33 @@
footnote_as_chunk = T)
```
+If your table footnote is very long, please consider to put your table in a `ThreePartTable` frame. Note that, in kableExtra version <= 0.7.0, we were using `threeparttable` but since kableExtra 0.8.0, we start to use `ThreePartTable` from `threeparttablex` instead. `ThreePartTable` supports both the `longtable` and `tabu` environments.
+
+```{r}
+kable(dt, "latex", align = "c", booktabs = T, caption = "s") %>%
+ footnote(general = "Here is a very very very very very very very very very very very very very very very very very very very very long footnote",
+ threeparttable = T)
+```
+
# LaTeX Only Features
+## Linebreak processor
+Unlike in HTML, where you can use `<br>` at any time, in LaTeX, it's actually quite difficult to make a linebreak in a table. Therefore I created the `linebreak` function to faciliate this process. Please see the [Best Practice for Newline in LaTeX Table](http://haozhu233.github.io/kableExtra/best_practice_for_newline_in_latex_table.pdf) for details.
+
+```{r}
+dt_lb <- data.frame(
+ Item = c("Hello\nWorld", "This\nis a cat"),
+ Value = c(10, 100)
+)
+
+dt_lb %>%
+ mutate_all(linebreak) %>%
+ kable("latex", booktabs = T, escape = F,
+ col.names = linebreak(c("Item\n(Name)", "Value\n(Number)"), align = "c"))
+```
+
+At the same time, since `kableExtra 0.8.0`, all `kableExtra` functions that have some contents input (such as `footnote` or `group_rows`) will automatically convert `\n` to linebreaks for you in both LaTeX and HTML.
+
+
## Table on a Landscape Page
Sometimes when we have a wide table, we want it to sit on a designated landscape page. The new function `landscape()` can help you on that. Unlike other functions, this little function only serves LaTeX and doesn't have a HTML side.
```{r}
@@ -447,7 +492,7 @@
```
## Use LaTeX table in HTML or Word
-If you want to include a LaTeX rendered table in your HTML or Word document, or if you just want to save table as an image, you may consider to use `kable_as_image()`. Note that this feature requires you to have [magick](https://github.com/ropensci/magick) installed (`install.packages("magick")`). Also, if you are planning to use it on Windows, you need to install [Ghostscript](https://www.ghostscript.com/).
+If you want to include a LaTeX rendered table in your HTML or Word document, or if you just want to save table as an image, you may consider to use `kable_as_image()`. Note that this feature requires you to have [magick](https://github.com/ropensci/magick) installed (`install.packages("magick")`). Also, if you are planning to use it on Windows, you need to install [Ghostscript](https://www.ghostscript.com/). This feature may not work if you are using tinytex. If you are using tinytex, please consider using other alternatives of this function.
```{r, eval = F}
# Not evaluated.
diff --git a/vignettes/best_practice_for_newline_in_latex_table.Rmd b/vignettes/best_practice_for_newline_in_latex_table.Rmd
new file mode 100644
index 0000000..63b3ec5
--- /dev/null
+++ b/vignettes/best_practice_for_newline_in_latex_table.Rmd
@@ -0,0 +1,80 @@
+---
+title: "Best Practice for newline in LaTeX table"
+author: "Hao"
+date: "`r Sys.Date()`"
+output: pdf_document
+header-includes:
+ - \usepackage{booktabs}
+ - \usepackage{longtable}
+ - \usepackage{array}
+ - \usepackage{multirow}
+ - \usepackage[table]{xcolor}
+ - \usepackage{wrapfig}
+ - \usepackage{float}
+ - \usepackage{colortbl}
+ - \usepackage{pdflscape}
+ - \usepackage{tabu}
+ - \usepackage{threeparttable}
+ - \usepackage{threeparttablex}
+ - \usepackage[normalem]{ulem}
+ - \usepackage{makecell}
+vignette: >
+ %\VignetteIndexEntry{Best Practice for newline in LaTeX table}
+ %\VignetteEngine{knitr::rmarkdown}
+ %\VignetteEncoding{UTF-8}
+---
+
+Since many people have asked me this question ([#157](https://github.com/haozhu233/kableExtra/issues/157), this [SO question](https://stackoverflow.com/questions/49546778/inserting-new-lines-into-kable-headers/49616173#49616173), etc.), I feel like I should document it out. :)
+
+Wrapping texts and make newlines may seem to be the same but they are actaully quite different. Thinking about when you "wrap texts" in your text editor, you have a fixed width window and the texts will be automatically wrapped. It's like a passive skill (in games :P). However, when you are trying to make newlines, you are inserting the linebreak by yourself and it's mostly like an active skill you need to cast. For these two tasks, LaTeX provides two totally different approaches.
+
+## Text wrapping
+If you are only trying stop your texts from "overflowing", you can get it done by setting a fixed width with `kableExtra::column_spec`. This is the most recommanded practice as it's fairly straightforward. The column width controls the width for both table header and table body.
+
+```{r, warning=F, message=F}
+library(kableExtra); library(dplyr)
+dt <- tibble(
+ Items = c("Item 1", "Item 2", "Item 3"),
+ Text_1 = c("Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin vehicula tempor ex. Morbi malesuada sagittis turpis, at venenatis nisl luctus a. ","In eu urna at magna luctus rhoncus quis in nisl. Fusce in velit varius, posuere risus et, cursus augue. Duis eleifend aliquam ante, a aliquet ex tincidunt in. ", "Vivamus venenatis egestas eros ut tempus. Vivamus id est nisi. Aliquam molestie erat et sollicitudin venenatis. In ac lacus at velit scelerisque mattis. "),
+ Text_2 = c("Duis posuere placerat magna, ac aliquam lorem viverra non. Ut ultrices tempus eros, quis sodales libero commodo non. In non neque ut lacus vestibulum dictum a quis ipsum. ", "Aenean ut justo interdum, laoreet enim nec, viverra eros. Donec vel pharetra nunc. Suspendisse vel ipsum ac lectus semper aliquam ac a orci. Suspendisse libero mauris, egestas semper auctor sit amet, tempor et orci. ", "Phasellus quis neque aliquet, finibus nunc eget, lacinia neque. Sed auctor lectus vel ex scelerisque commodo. ")
+)
+```
+
+```{r}
+kable(dt, "latex", booktabs = T,
+ col.names = c("Item", "Short Title", "Very Very Very Very Very Very Long Title")) %>%
+ column_spec(2:3, width = "5cm")
+```
+
+## Insert linebreak in table
+In LaTeX, to make linebreaks in table cells, people usually use the `makecell` package. `kableExtra` 0.8.0 comes with a function called `linebreak` to facilitate that. Basically, this function will scan the existance of `\n`. If `\n` exists, it will put the texts in a `makecell` statement. It works in a very similar way with `cell_spec` so you will need to put `escape = F` in `kable`.
+
+```{r}
+linebreak("a\nb")
+```
+
+When you have `\n` in your data frame, you can either change the value manually or simply use it with `dplyr::mutate_all`.
+```{r}
+dt2 <- data.frame(
+ Item = c("Hello\nWorld", "This\nis a cat"),
+ Value = c(10, 100)
+)
+
+dt2 %>%
+ mutate_all(linebreak) %>%
+ kable("latex", booktabs = T, escape = F,
+ col.names = linebreak(c("Item\n(Name)", "Value\n(Number)"), align = "c"))
+```
+
+### Linebreak in other kableExtra functions
+If you have a need to put a linebreak in `kableExtra` functions such as `add_header_above` and `group_rows`, just go ahead and use `\n` directly (in kableExtra >= 0.8.0) and it will be automatically converted. Note that this feature is also controlled by the `escape` option in those functions.
+
+```{r}
+dt2 %>%
+ mutate_all(linebreak) %>%
+ kable("latex", booktabs = T, escape = F,
+ col.names = linebreak(c("Item\n(Name)", "Value\n(Number)"), align = "c")) %>%
+ add_header_above(c("Combined\nTitle" = 2)) %>%
+ group_rows("Group\n1", 2, 2)
+```
+
diff --git a/vignettes/kableExtra_and_word.Rmd b/vignettes/kableExtra_and_word.Rmd
deleted file mode 100644
index 4ad4ceb..0000000
--- a/vignettes/kableExtra_and_word.Rmd
+++ /dev/null
@@ -1,27 +0,0 @@
----
-title: "kableExtra and Word"
-author: "Hao Zhu"
-date: "`r Sys.Date()`"
-output:
- html_document:
- theme: simplex
-vignette: >
- %\VignetteIndexEntry{kableExtra and Word}
- %\VignetteEngine{knitr::rmarkdown}
- %\VignetteEncoding{UTF-8}
----
-
-```{r setup, include=FALSE}
-knitr::opts_chunk$set(echo = TRUE)
-```
-
-
-<video width="800" height="400" controls>
- <source src="word.mp4" type="video/mp4">
- Your browser does not support the video tag.
-</video>
-
-***
-
-> You can `copy` formatted tables from HTML and `paste` them into a Word document
-without losing the format.
diff --git a/vignettes/word.mp4 b/vignettes/word.mp4
deleted file mode 100644
index 8c24fab..0000000
--- a/vignettes/word.mp4
+++ /dev/null
Binary files differ