add a kable function with better doc
diff --git a/R/column_spec.R b/R/column_spec.R
index 2e8a64d..2a97fee 100644
--- a/R/column_spec.R
+++ b/R/column_spec.R
@@ -39,6 +39,8 @@
#' header row will be manipulated. Default is `FALSE`.
#' @param latex_column_spec Only for LaTeX tables. Code to replace the column
#' specification. If not `NULL`, will override all other arguments.
+#' @param latex_valign vertical alignment. Only works when you specified column
+#' width. Choose among `p`, `m`, `b`.
#'
#' @details Use `latex_column_spec` in a LaTeX table to change or
#' customize the column specification. Because of the way it is handled
@@ -56,7 +58,7 @@
border_left = FALSE, border_right = FALSE,
width_min = NULL, width_max = NULL,
extra_css = NULL, include_thead = FALSE,
- latex_column_spec = NULL) {
+ latex_column_spec = NULL, latex_valign = 'p') {
if (!is.numeric(column)) {
stop("column must be numeric. ")
}
@@ -82,7 +84,8 @@
underline, strikeout,
color, background,
border_left, border_right,
- latex_column_spec = latex_column_spec))
+ latex_column_spec = latex_column_spec,
+ latex_valign = latex_valign))
}
}
@@ -222,7 +225,7 @@
underline, strikeout,
color, background,
border_left, border_right,
- latex_column_spec) {
+ latex_column_spec, latex_valign) {
table_info <- magic_mirror(kable_input)
if (!is.null(table_info$collapse_rows)) {
message("Usually it is recommended to use column_spec before collapse_rows,",
@@ -237,7 +240,8 @@
function(x) {
latex_column_align_builder(
x, width, bold, italic, monospace, underline, strikeout,
- color, background, border_left, border_right, latex_column_spec)
+ color, background, border_left, border_right, latex_column_spec,
+ latex_valign)
}
))
@@ -271,14 +275,14 @@
underline, strikeout,
color, background,
border_left, border_right,
- latex_column_spec) {
+ latex_column_spec, latex_valign) {
extra_align <- ""
if (!is.null(width)) {
extra_align <- switch(x,
"l" = "\\\\raggedright\\\\arraybackslash",
"c" = "\\\\centering\\\\arraybackslash",
"r" = "\\\\raggedleft\\\\arraybackslash")
- x <- paste0("p\\{", width, "\\}")
+ x <- paste0(latex_valign, "\\{", width, "\\}")
}
if (!is.null(color)) {
diff --git a/R/kable.R b/R/kable.R
new file mode 100644
index 0000000..f1709d5
--- /dev/null
+++ b/R/kable.R
@@ -0,0 +1,105 @@
+#' Wrapper function of knitr::kable
+#'
+#' @description knitr's kable function is the foundation of this package.
+#' However, it has many latex/html specific arguments hidden under the ground
+#' unless you check its source code. This wrapper function is created to
+#' provide better documentation (and auto-complete yay) and at the same time,
+#' solve the auto format setting in a better way.
+#'
+#' @param table.attr A character string for addition HTML table attributes.
+#' This is convenient if you simply want to add a few HTML classes or styles.
+#' For example, you can put 'class="table" style="color: red"'.
+#' @param booktabs T/F for whether to enable the booktabs format for tables. I
+#' personally would recommend you turn this on for every latex table except
+#' some special cases.
+#' @param longtable T/F for whether to use the longtable format. If you have a
+#' table that will span over two or more pages, you will have to turn this on.
+#' @param valign You probably won't need to adjust this latex option very often.
+#' If you are familar with latex tables, this is the optional position for the
+#' tabular environment controling the vertical position of the table relative
+#' to the baseline of the surrounding text. Possible choices are `b`, `c` and
+#' `t` (default).
+#' @param position This is the "real" or say floating position for the latex
+#' table environment. The `kable` only puts tables in a table environment when
+#' a caption is provided. That is also the reason why your tables will be
+#' floating around if you specify captions for your table. Possible choices are
+#' `h` (here), `t` (top, default), `b` (bottom) and `p` (on a dedicated page).
+#' @param centering T (default)/F. Whether to center tables in the table
+#' environment.
+#' @param caption.short Another latex feature. Short captions for tables
+#' @param linesep By default, in booktabs tables, `kable` insert an extra space
+#' every five rows for clear display. If you don't want this feature or if you
+#' want to do it in a different pattern, you can consider change this option.
+#' The default is c('', '', '', '', '\\addlinespace'). Also, if you are not
+#' using booktabs, but you want a cleaner display, you can change this to ''.
+#' @param table.envir You probably don't need to change this as well. The
+#' default setting is to put a table environment outside of tabular if a
+#' caption is provided.
+#' @param vline vertical separator. Default is nothing for booktabs
+#' tables but "|" for normal tables.
+#' @param toprule toprule. Default is hline for normal table but toprule for
+#' booktabs tables.
+#' @param bottomrule bottomrule. Default is hline for normal table but
+#' bottomrule for booktabs tables.
+#' @param midrule midrule. Default is hline for normal table but midrule for
+#' booktabs tables.
+#'
+#' @inheritParams knitr::kable
+#' @export
+kable <- function(x, format, digits = getOption("digits"),
+ row.names = NA, col.names = NA, align,
+ caption = NULL, label = NULL, format.args = list(),
+ escape = TRUE,
+ table.attr = '',
+ booktabs = FALSE, longtable = FALSE,
+ valign = 't', position = '', centering = TRUE,
+ vline = getOption('knitr.table.vline', if (booktabs) '' else '|'),
+ toprule = getOption('knitr.table.toprule', if (booktabs) '\\toprule' else '\\hline'),
+ bottomrule = getOption('knitr.table.bottomrule', if (booktabs) '\\bottomrule' else '\\hline'),
+ midrule = getOption('knitr.table.midrule', if (booktabs) '\\midrule' else '\\hline'),
+ linesep = if (booktabs) c('', '', '', '', '\\addlinespace') else '\\hline',
+ caption.short = '',
+ table.envir = if (!is.null(caption)) 'table', ...) {
+ if (!missing(align) && length(align) == 1L && !grepl('[^lcr]', align)) {
+ align <- strsplit(align, '')[[1]]
+ }
+ if (missing(format) | is.null(format)) {
+ if (knitr::is_latex_output()) {
+ format <- "latex"
+ return(knitr::kable(
+ x = x, format = format, digits = digits,
+ row.names = row.names, col.names = col.names, align = align,
+ caption = caption, label = label, format.args = format.args,
+ escape = escape,
+ booktabs = booktabs, longtable = longtable,
+ valign = valign, position = position, centering = centering,
+ vline = vline, toprule = toprule, bottomrule = bottomrule,
+ midrule = midrule, linesep = linesep, caption.short = caption.short,
+ table.envir = table.envir, ...
+ ))
+ } else {
+ format <- "html"
+ return(knitr::kable(
+ x = x, format = format, digits = digits,
+ row.names = row.names, col.names = col.names, align = align,
+ caption = caption, label = label, format.args = format.args,
+ escape = escape,
+ table.attr = table.attr, ...
+ ))
+ }
+ } else {
+ return(knitr::kable(
+ x = x, format = format, digits = digits,
+ row.names = row.names, col.names = col.names, align = align,
+ caption = caption, label = label, format.args = format.args,
+ escape = escape, table.attr = table.attr,
+ booktabs = booktabs, longtable = longtable,
+ valign = valign, position = position, centering = centering,
+ vline = vline, toprule = toprule, bottomrule = bottomrule,
+ midrule = midrule, linesep = linesep, caption.short = caption.short,
+ table.envir = table.envir, ...
+ ))
+ }
+
+
+}
diff --git a/R/kableExtra-package.R b/R/kableExtra-package.R
index c01f058..bb6528c 100644
--- a/R/kableExtra-package.R
+++ b/R/kableExtra-package.R
@@ -85,6 +85,3 @@
#' @export
magrittr::`%>%`
-
-#' @export
-knitr::kable
diff --git a/man/collapse_rows.Rd b/man/collapse_rows.Rd
index f145342..11196b7 100644
--- a/man/collapse_rows.Rd
+++ b/man/collapse_rows.Rd
@@ -8,12 +8,14 @@
kable_input,
columns = NULL,
valign = c("middle", "top", "bottom"),
- latex_hline = c("full", "major", "none", "custom"),
+ latex_hline = c("major", "full", "none", "custom"),
row_group_label_position = c("identity", "stack"),
custom_latex_hline = NULL,
row_group_label_fonts = NULL,
headers_to_remove = NULL,
- target = NULL
+ target = NULL,
+ col_names = TRUE,
+ longtable_clean_cut = TRUE
)
}
\arguments{
@@ -27,7 +29,8 @@
not up to date.}
\item{latex_hline}{Option controlling the behavior of adding hlines to table.
-Choose from \code{full}, \code{major}, \code{none}, \code{custom}.}
+Choose from \code{major}, \code{full}, \code{none}, \code{custom} and \code{linespace}. We changed the default from
+\code{full} to \code{major} in version 1.2.}
\item{row_group_label_position}{Option controlling positions of row group
labels. Choose from \code{identity}, \code{stack}.}
@@ -41,6 +44,19 @@
\item{headers_to_remove}{Numeric column positions where headers should be
removed when they are stacked.}
+
+\item{target}{If multiple columns are selected to do collapsing and a target
+column is specified, this target column will be used to collapse other
+columns based on the groups of this target column.}
+
+\item{col_names}{T/F. A LaTeX specific option. If you set \code{col.names} be
+\code{NULL} in your \code{kable} call, you need to set this option false to let
+everything work properly.}
+
+\item{longtable_clean_cut}{T/F with default T. Multirow cell sometimes are
+displayed incorrectly around pagebreak. This option forces groups to cut
+before the end of a page. If you have a group that is longer than 1 page,
+you need to turn off this option.}
}
\description{
Collapse same values in columns into multirow cells. This
diff --git a/man/column_spec.Rd b/man/column_spec.Rd
index 0857f4d..698c688 100644
--- a/man/column_spec.Rd
+++ b/man/column_spec.Rd
@@ -21,7 +21,8 @@
width_max = NULL,
extra_css = NULL,
include_thead = FALSE,
- latex_column_spec = NULL
+ latex_column_spec = NULL,
+ latex_valign = "p"
)
}
\arguments{
@@ -77,6 +78,9 @@
\item{latex_column_spec}{Only for LaTeX tables. Code to replace the column
specification. If not \code{NULL}, will override all other arguments.}
+
+\item{latex_valign}{vertical alignment. Only works when you specified column
+width. Choose among \code{p}, \code{m}, \code{b}.}
}
\description{
This function allows users to select a column and then specify
diff --git a/man/group_rows.Rd b/man/group_rows.Rd
index d39d0d2..0059e6f 100644
--- a/man/group_rows.Rd
+++ b/man/group_rows.Rd
@@ -95,7 +95,7 @@
\item{extra_latex_after}{Extra LaTeX text to be added after the row.}
-\item{indent}{A T?F value to control whether list items are indented.}
+\item{indent}{A T/F value to control whether list items are indented.}
}
\description{
Group a few rows in a table together under a label.
diff --git a/man/kable.Rd b/man/kable.Rd
new file mode 100644
index 0000000..f7b7d24
--- /dev/null
+++ b/man/kable.Rd
@@ -0,0 +1,137 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/kable.R
+\name{kable}
+\alias{kable}
+\title{Wrapper function of knitr::kable}
+\usage{
+kable(
+ x,
+ format,
+ digits = getOption("digits"),
+ row.names = NA,
+ col.names = NA,
+ align,
+ caption = NULL,
+ label = NULL,
+ format.args = list(),
+ escape = TRUE,
+ table.attr = "",
+ booktabs = FALSE,
+ longtable = FALSE,
+ valign = "t",
+ position = "",
+ centering = TRUE,
+ vline = getOption("knitr.table.vline", if (booktabs) "" else "|"),
+ toprule = getOption("knitr.table.toprule", if (booktabs) "\\\\toprule" else
+ "\\\\hline"),
+ bottomrule = getOption("knitr.table.bottomrule", if (booktabs) "\\\\bottomrule" else
+ "\\\\hline"),
+ midrule = getOption("knitr.table.midrule", if (booktabs) "\\\\midrule" else
+ "\\\\hline"),
+ linesep = if (booktabs) c("", "", "", "", "\\\\addlinespace") else "\\\\hline",
+ caption.short = "",
+ table.envir = if (!is.null(caption)) "table",
+ ...
+)
+}
+\arguments{
+\item{x}{For \code{kable()}, \code{x} is an R object, which is typically a
+matrix or data frame. For \code{kables()}, a list with each element being a
+returned value from \code{kable()}.}
+
+\item{format}{A character string. Possible values are \code{latex},
+\code{html}, \code{pipe} (Pandoc's pipe tables), \code{simple} (Pandoc's
+simple tables), and \code{rst}. The value of this argument will be
+automatically determined if the function is called within a \pkg{knitr}
+document. The \code{format} value can also be set in the global option
+\code{knitr.table.format}. If \code{format} is a function, it must return a
+character string.}
+
+\item{digits}{Maximum number of digits for numeric columns, passed to
+\code{round()}. This can also be a vector of length \code{ncol(x)}, to set
+the number of digits for individual columns.}
+
+\item{row.names}{Logical: whether to include row names. By default, row names
+are included if \code{rownames(x)} is neither \code{NULL} nor identical to
+\code{1:nrow(x)}.}
+
+\item{col.names}{A character vector of column names to be used in the table.}
+
+\item{align}{Column alignment: a character vector consisting of \code{'l'}
+(left), \code{'c'} (center) and/or \code{'r'} (right). By default or if
+\code{align = NULL}, numeric columns are right-aligned, and other columns
+are left-aligned. If \code{length(align) == 1L}, the string will be
+expanded to a vector of individual letters, e.g. \code{'clc'} becomes
+\code{c('c', 'l', 'c')}, unless the output format is LaTeX.}
+
+\item{caption}{The table caption.}
+
+\item{label}{The table reference label. By default, the label is obtained
+from \code{knitr::\link[knitr]{opts_current}$get('label')}.}
+
+\item{format.args}{A list of arguments to be passed to \code{\link{format}()}
+to format table values, e.g. \code{list(big.mark = ',')}.}
+
+\item{escape}{Boolean; whether to escape special characters when producing
+HTML or LaTeX tables. When \code{escape = FALSE}, you have to make sure
+that special characters will not trigger syntax errors in LaTeX or HTML.}
+
+\item{table.attr}{A character string for addition HTML table attributes.
+This is convenient if you simply want to add a few HTML classes or styles.
+For example, you can put 'class="table" style="color: red"'.}
+
+\item{booktabs}{T/F for whether to enable the booktabs format for tables. I
+personally would recommend you turn this on for every latex table except
+some special cases.}
+
+\item{longtable}{T/F for whether to use the longtable format. If you have a
+table that will span over two or more pages, you will have to turn this on.}
+
+\item{valign}{You probably won't need to adjust this latex option very often.
+If you are familar with latex tables, this is the optional position for the
+tabular environment controling the vertical position of the table relative
+to the baseline of the surrounding text. Possible choices are \code{b}, \code{c} and
+\code{t} (default).}
+
+\item{position}{This is the "real" or say floating position for the latex
+table environment. The \code{kable} only puts tables in a table environment when
+a caption is provided. That is also the reason why your tables will be
+floating around if you specify captions for your table. Possible choices are
+\code{h} (here), \code{t} (top, default), \code{b} (bottom) and \code{p} (on a dedicated page).}
+
+\item{centering}{T (default)/F. Whether to center tables in the table
+environment.}
+
+\item{vline}{vertical separator. Default is nothing for booktabs
+tables but "|" for normal tables.}
+
+\item{toprule}{toprule. Default is hline for normal table but toprule for
+booktabs tables.}
+
+\item{bottomrule}{bottomrule. Default is hline for normal table but
+bottomrule for booktabs tables.}
+
+\item{midrule}{midrule. Default is hline for normal table but midrule for
+booktabs tables.}
+
+\item{linesep}{By default, in booktabs tables, \code{kable} insert an extra space
+every five rows for clear display. If you don't want this feature or if you
+want to do it in a different pattern, you can consider change this option.
+The default is c('', '', '', '', '\\addlinespace'). Also, if you are not
+using booktabs, but you want a cleaner display, you can change this to ''.}
+
+\item{caption.short}{Another latex feature. Short captions for tables}
+
+\item{table.envir}{You probably don't need to change this as well. The
+default setting is to put a table environment outside of tabular if a
+caption is provided.}
+
+\item{...}{Other arguments (see Examples).}
+}
+\description{
+knitr's kable function is the foundation of this package.
+However, it has many latex/html specific arguments hidden under the ground
+unless you check its source code. This wrapper function is created to
+provide better documentation (and auto-complete yay) and at the same time,
+solve the auto format setting in a better way.
+}
diff --git a/man/reexports.Rd b/man/reexports.Rd
index 69a8477..7028941 100644
--- a/man/reexports.Rd
+++ b/man/reexports.Rd
@@ -4,7 +4,6 @@
\name{reexports}
\alias{reexports}
\alias{\%>\%}
-\alias{kable}
\title{Objects exported from other packages}
\keyword{internal}
\description{
@@ -12,8 +11,6 @@
below to see their documentation.
\describe{
- \item{knitr}{\code{\link[knitr]{kable}}}
-
\item{magrittr}{\code{\link[magrittr:pipe]{\%>\%}}}
}}
diff --git a/tests/visual_tests/collapse_rows_pdf.Rmd b/tests/visual_tests/collapse_rows_pdf.Rmd
index 3ecc58b..d4c83f6 100644
--- a/tests/visual_tests/collapse_rows_pdf.Rmd
+++ b/tests/visual_tests/collapse_rows_pdf.Rmd
@@ -9,11 +9,8 @@
library(knitr)
library(dplyr)
library(kableExtra)
-collapse_rows_dt <- data.frame(C1 = c(rep("aaaaaa aaaaaa", 10), rep("bbbbb bbbbbb", 5)),
- C2 = c(rep("c", 7), rep("d", 3), rep("c", 3), rep("d", 2)),
- C3 = 1:15,
- C4 = sample(c(0,1), 15, replace = TRUE))
-kable(bind_rows(collapse_rows_dt), "latex", align = "c", booktabs = T, longtable= T) %>%
- column_spec(1, bold = T, width = "5em") %>%
- collapse_rows(1:2, latex_hline = "linespace")
+mtcars %>%
+ kable("latex") %>%
+ kable_styling(latex_options = "striped", full_width = T) %>%
+ magic_mirror()
```