added a vignette for table formating

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: memoiR
 Title: R Markdown and Bookdown Templates to Publish Documents
-Version: 1.2-10.9005
+Version: 1.2-10.9006
 URL: https://ericmarcon.github.io/memoiR/, https://github.com/EricMarcon/memoiR/
 BugReports: https://github.com/EricMarcon/memoiR/issues/
 Authors@R: 

NEWS.md

@@ -1,4 +1,4 @@
-# memoiR 1.2-10.9005
+# memoiR 1.2-10.9006
 
 * added the "main" branch name to `build_ghworkflow()`.
 * corrected the Stylish Article template (Thanks to Florence Puech, #5).

vignettes/articles/tables.Rmd

@@ -0,0 +1,183 @@
+---
+title: "Tables with memoiR"
+output: 
+  bookdown::html_document2:
+    toc: yes
+    toc_float: yes
+    number_sections: false
+    code_folding: show
+vignette: >
+  %\VignetteIndexEntry{Tables}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r global_options, include=FALSE}
+# Installation of packages if necessary
+install_packages <- function(packages) {
+  install_package <- function(package) {
+    if (!package %in% installed.packages()[, 1]) {
+      install.packages(package, repos = "https://cran.rstudio.com/")
+    }
+  }
+  invisible(sapply(packages, install_package))
+}
+install_packages(c("gt", "huxtable"))
+knitr::opts_chunk$set(cache = FALSE)
+set.seed(97310)
+```
+
+The purpose here is to print a dataframe as a formated table.
+
+Many packages are dedicated to tables but few of them meet the requirements of memoiR:
+
+- Support of numbered captions for cross-references (such as "Table 1: caption").
+- Support of HTML, LaTeX (ultimately PDF) and hopefully Word outputs.
+- Support of 2-column LaTeX documents.
+- Support of maths in all formats.
+
+**kableExtra** is memoiR's first choice because it supports LaTeX better than the others.
+**huxtable** is an alternative if Word support is needed.
+
+
+# kableExtra
+
+## Basic use
+
+**bookdown** was built with the `kable()` function[^1], completed by the **kableExtra** package.
+
+[^1]: <https://bookdown.org/yihui/rmarkdown-cookbook/kable.html>
+
+This basic example shows how to produce a simple, well-formatted table.
+The label of the code chunk is `cars`.
+```{r}
+library("kableExtra")
+mtcars[1:5, 1:6] |>
+  kbl(
+    caption = "Demo table", 
+    booktabs = TRUE
+  ) |>
+  kable_styling()
+```
+
+The `kableExtra::kbl()` function replaces `knitr::kable()` starting from version 1.2 of **kableExtra** to avoid incorrect caption format.
+A consequence is that the table caption can't be included in the chunk header with option `tab.cap` which works only with `kable()`.
+The table caption is thus in the argument `caption` of `kbl()`.
+Formatted captions, possibly with maths, can be used with text references[^5]:
+
+- add the reference somewhere in the text (just above the code chunk is a good place), such as
+```
+(ref:cars) Caption with _italics_ and maths: $\pi$
+```
+- call the reference in the chunk with `caption = "(ref:cars)"`.
+Note that **knitr** shows the value of the text reference in the chunk below.
+
+(ref:cars) Caption with _italics_ and maths: $\pi$.
+```{r}
+#| label: cars
+library("kableExtra")
+mtcars[1:5, 1:6] |>
+  kbl(
+    caption = "(ref:cars)", 
+    booktabs = TRUE
+  ) |>
+  kable_styling()
+```
+
+Argument `booktabs = TRUE` provides clean horizontal rules and should always be used.
+
+Last, `kable_styling()` formats the table for printing.
+It has many arguments that are not detailed here: read the documentation of the package[^2].
+More details are given in the document templates of memoiR, including the code to place tables in a single column or across the full page in the Stylish Article template.
+
+[^2]: <https://haozhu233.github.io/kableExtra/>
+[^5]: <https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#text-references>
+
+Cross references (such as table \@ref(tab:cars)) are called by `table \@ref(tab:cars)`: the name of the code snippet ("cars" here) is prefixed by `tab:`.
+
+
+## Limitations
+
+**kableExtra** used to produce clean tables in Word with a workaround[^3] that was included in previous versions of memoiR but this no longer the case since its version 1.
+Tables are rendered with a single cell per row.
+
+[^3]: <https://github.com/haozhu233/kableExtra/issues/308>
+
+The solution is to produce the HTML version of the document, copy its tables and paste them into the Word version[^4].
+
+[^4]: <https://haozhu233.github.io/kableExtra/kableExtra_and_word.html>
+
+
+# huxtable
+
+## Basic use
+
+**huxtable** works perfectly with memoiR after adding the LaTeX packages in the `preamble` section of the YAML header.
+Run `huxtable::report_latex_dependencies()` and copy all of them to obtain something like
+
+```
+preamble: >
+  \usepackage{array}
+  \usepackage{caption}
+  ...
+```
+Add **huxtable** in the vector of packages to install in the "Options" chunk:
+
+```{r}
+#| eval: false
+# Add necessary packages here
+packages <- c("tidyverse", "huxtable")
+```
+
+Tables are produced by `as_hux()` and formatting is made possible by a large set of functions.
+
+(ref:ht) Made by **huxtable**
+```{r}
+#| label: ht
+#| message: false
+library("huxtable")
+mtcars[1:5, 1:6] |>
+  as_hux() |>
+  set_header_rows(1, value = TRUE) |> 
+  style_headers(bold = TRUE)|> 
+  theme_article() |>
+  set_caption("(ref:ht)")
+```
+
+Read its documentation[^6].
+
+[^6]: <https://hughjonesd.github.io/huxtable/reference/>
+
+## Limitations
+
+Word output is correct in contrast with **kableExtra** but LaTeX support is yet more limited.
+In Stylish Articles, tables are always printed in full width.
+There seems to be no way to make them fit a single column.
+
+
+# gt
+
+**gt** is the a promising table package, developped by the RStudio team with an approach similar to that of **ggplot2**, i.e. the definition of a grammar of tables.
+
+It has been focusing on HTML output and somehow neglected LaTeX in its first versions.
+LaTeX support was improved in version 0.11 but it can't be used in memoiR yet because the numbered captions are not correct, even in HTML, as shown below.
+
+```{r}
+#| label: gt
+library("gt")
+mtcars[1:5, 1:6] |>
+  gt(
+    caption = "Demo table"
+  )
+```
+
+
+# flextable
+
+**flextable** supports all output formats but it does not produce standard table captions.
+Even though they are numbered and support cross-referencing, they rely on their own style, which makes them different from figure captions.
+This requires extra work to harmonize the documents.
+
+More problematic, knitting to PDF fails with memoiR templates because the LaTeX templates are not compatible.
+
+In conclusion, flextable is not supported.