remove add_header_left entirely
update rd files
improve package documentation based on @wibeasley's suggestion
diff --git a/man/add_footnote.Rd b/man/add_footnote.Rd
index d3839a3..5bab0eb 100644
--- a/man/add_footnote.Rd
+++ b/man/add_footnote.Rd
@@ -15,7 +15,7 @@
notations in your notes.}
\item{notation}{You can select the format of your footnote notation from
-`number`, `alphabet` and `symbol`.}
+\code{number}, \code{alphabet} and \code{symbol}.}
\item{threeparttable}{Boolean value indicating if a
\href{https://www.ctan.org/pkg/threeparttable}{threeparttable} scheme should
diff --git a/man/add_header_above.Rd b/man/add_header_above.Rd
index cbe6988..d879bc7 100644
--- a/man/add_header_above.Rd
+++ b/man/add_header_above.Rd
@@ -7,13 +7,13 @@
add_header_above(kable_input, header = NULL, bold = F, italic = F)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
-\item{header}{A (named) character vector with `colspan` as values. For
-example, `c(" " = 1, "title" = 2)` can be used to create a new header row
+\item{header}{A (named) character vector with \code{colspan} as values. For
+example, \code{c(" " = 1, "title" = 2)} can be used to create a new header row
for a 3-column table with "title" spanning across column 2 and 3. For
-convenience, when `colspan` equals to 1, users can drop the ` = 1` part.
-As a result, `c(" ", "title" = 2)` is the same as `c(" " = 1, "title" = 2)`.}
+convenience, when \code{colspan} equals to 1, users can drop the \code{= 1} part.
+As a result, \code{c(" ", "title" = 2)} is the same as \code{c(" " = 1, "title" = 2)}.}
\item{bold}{A T/F value to control whether the text should be bolded.}
@@ -21,9 +21,9 @@
}
\description{
Tables with multiple rows of header rows are extremely useful
-to demonstrate grouped data. This function takes the output of a `kable()`
+to demonstrate grouped data. This function takes the output of a \code{kable()}
function and adds an header row on top of it. This function can work with
-both `HTML` and `LaTeX` outputs
+both \code{HTML} and \code{LaTeX} outputs
}
\examples{
x <- knitr::kable(head(mtcars), "html")
diff --git a/man/add_header_left.Rd b/man/add_header_left.Rd
deleted file mode 100644
index 43094a6..0000000
--- a/man/add_header_left.Rd
+++ /dev/null
@@ -1,45 +0,0 @@
-% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/add_header_left.R
-\name{add_header_left}
-\alias{add_header_left}
-\title{Add a heading column to the left side of the table}
-\usage{
-add_header_left(kable_input, header = NULL, header_name = "", align = "c",
- width = NULL, bold = F, italic = F, ...)
-}
-\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
-
-\item{header}{A (named) character vector with `rowspan` as values. For
-example, `c("xxx" = 1, "title" = 2)` can be used to create a new header column
-for a 3-row table with "xxx" spanning row 1 and "title" spanning row 2 & 3 (
-two rows). For convenience, when `rowspan` equals to 1, users can drop the
-` = 1` part. As a result, `c("xxx", "title" = 2)` is the same as
-`c("xxx" = 1, "title" = 2)`.}
-
-\item{header_name}{Column name that that extra column}
-
-\item{align}{Column alignment. you can choose from "c", "l" or "r"}
-
-\item{width}{A character string for the width of the new column. Values
-could be "10cm", "3in" or "30em", etc..}
-
-\item{bold}{A T/F value to control whether the text should be bolded.}
-
-\item{italic}{A T/F value to control whether the text should to be emphasized.}
-
-\item{...}{Extra options to be passed into HTML or LaTeX. Right now there is
-only one for LaTeX. Option full_midline is a TRUE/FALSE option to control
-if the mid line needs to be extended to the end of row.}
-}
-\description{
-This function uses the same syntax as add_header_above. It will
-add a heading column with grouped rows to the left side of the table. It can
-act as an alternative way to `group_rows` to show grouped information. As
-`add_header_above`, users can use this function to add multiple layers of
-heading columns one by one.
-}
-\examples{
-x <- knitr::kable(head(mtcars), "html")
-add_header_left(x, c("A" = 2, "B" = 2, "C" = 2))
-}
diff --git a/man/add_indent.Rd b/man/add_indent.Rd
index e141e70..439fd29 100644
--- a/man/add_indent.Rd
+++ b/man/add_indent.Rd
@@ -7,7 +7,7 @@
add_indent(kable_input, positions)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{positions}{A vector of numeric row numbers for the rows that need to
be indented.}
diff --git a/man/collapse_rows.Rd b/man/collapse_rows.Rd
index 49deb7f..e1078a3 100644
--- a/man/collapse_rows.Rd
+++ b/man/collapse_rows.Rd
@@ -7,16 +7,16 @@
collapse_rows(kable_input, columns = NULL)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{columns}{Numeric column positions where rows need to be collapsed.}
}
\description{
Collapse same values in columns into multirow cells. This
-feature does similar things with `group_rows`. However, unlike `group_rows`,
+feature does similar things with \code{group_rows}. However, unlike \code{group_rows},
it analyzes existing columns, finds out rows that can be grouped together,
-and make them multirow cells. Note that if you want to use `column_spec` to
-specify column styles, you should use `column_spec` before `collapse_rows`.
+and make them multirow cells. Note that if you want to use \code{column_spec} to
+specify column styles, you should use \code{column_spec} before \code{collapse_rows}.
}
\examples{
dt <- data.frame(a = c(1, 1, 2, 2), b = c("a", "a", "a", "b"))
diff --git a/man/column_spec.Rd b/man/column_spec.Rd
index cf4b5cf..fdedeac 100644
--- a/man/column_spec.Rd
+++ b/man/column_spec.Rd
@@ -8,7 +8,7 @@
italic = FALSE)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{column}{A numeric value indicating which column to be selected. When
you do the counting, ignore the extra header columns you added through
diff --git a/man/group_rows.Rd b/man/group_rows.Rd
index 6cf58ee..8275309 100644
--- a/man/group_rows.Rd
+++ b/man/group_rows.Rd
@@ -8,7 +8,7 @@
label_row_css = "border-bottom: 1px solid;", latex_gap_space = "0.5em")
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{group_label}{A character string for the name of the group}
diff --git a/man/kableExtra-package.Rd b/man/kableExtra-package.Rd
index 3de7e0f..33854bc 100644
--- a/man/kableExtra-package.Rd
+++ b/man/kableExtra-package.Rd
@@ -6,6 +6,60 @@
\alias{kableExtra}
\title{kableExtra}
\description{
-kableExtra
+When we are talking about table generators in R,
+\href{https://yihui.name/knitr/}{knitr}'s \code{kable()} function wins lots of flavor
+by its ultimate simplicity. Unlike those powerful table rendering engines
+such as \href{https://CRAN.R-project.org/package=xtable}{xtable}, the philosophy
+behind \href{https://rdrr.io/cran/knitr/man/kable.html}{knitr::kable()} is to
+make it easy for programmers to use. Just as it claimed in its
+function description, "this is a very simple table generator. It is simple
+by design. It is not intended to replace any other R packages for making
+tables. - Yihui".
+
+However, the ultimate simplicity of \code{kable()} also brought troubles to some
+of us, especially for new R users, who may not have a lot of experience on
+generating tables in R. It is not rare to see people including experienced
+users asking questions like how to center/left-align a table on Stack
+Overflow. Also, for me personally, I found myself repeatedly parsing CSS
+into \code{kable()} for some very simple features like striped lines. For LaTeX,
+it's even worse since I'm almost Stack Overflow dependent for LaTeX...
+That's why this package \code{kableExtra} was created.
+
+I hope with \code{kableExtra}, you can
+\itemize{
+\item Use default base \code{kable()} (Or a good alternative for markdown tables is
+\code{pander::pander()}) for all simple tables
+\item Use \code{kable()} with \code{kableExtra} to generate 90 % of complex/advanced
+tables in either HTML or LaTeX
+\item Only have to mess with raw HTML/LaTeX in the last 10% cases where
+\code{kableExtra} cannot solve the problem
}
+}
+\note{
+If you found a feature on the documentation site that is not available
+in the version of \code{kableExtra} you are using, try to install the pre-release
+version from github. You can do so by running
+\code{devtools::install_github("haozhu233/kableExtra")}.
+
+Also, note that This package can load required LaTeX package automatically in
+vanilla rmarkdown. For customized rmarkdown templates, it is recommended to
+load related LaTeX packages manually.
+}
+\section{Features}{
+
+\strong{Pipable syntax:} \code{kableExtra} is NOT a table generating package. It is a
+package that can "add features" to a \code{kable} output using a syntax
+that every useR loves - the \href{http://r4ds.had.co.nz/pipes.html}{pipe}.
+We see similar approaches to deal with plots in packages like \code{ggvis} and
+\code{plotly}. There is no reason why we cannot use it with tables.
+
+\strong{Unified functions for both HTML and PDF:} Most functionalities in
+\code{kableExtra} can work in both HTML and PDF. In fact, as long as you
+specifies format in \code{kable} (which can be set globally through option
+\code{knitr.table.format}), functions in this package will pick the right way
+to manipulate the table be themselves. As a result, if users want to left
+align the table, \code{kable_styling(kable(...), position = "left")} will work
+in both HTML and PDF.
+}
+
\keyword{package}
diff --git a/man/kable_styling.Rd b/man/kable_styling.Rd
index a491d31..52080ae 100644
--- a/man/kable_styling.Rd
+++ b/man/kable_styling.Rd
@@ -9,37 +9,37 @@
font_size = NULL, ...)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{bootstrap_options}{A character vector for bootstrap table options.
Please see package vignette or visit the w3schools'
\href{https://www.w3schools.com/bootstrap/bootstrap_tables.asp}{Bootstrap Page}
-for more information. Possible options include `basic`, `striped`,
-`bordered`, `hover`, `condensed` and `responsive`.}
+for more information. Possible options include \code{basic}, \code{striped},
+\code{bordered}, \code{hover}, \code{condensed} and \code{responsive}.}
\item{latex_options}{A character vector for LaTeX table options. Please see
package vignette for more information. Possible options include
-`basic`, `striped`, `hold_position`, `scale_down` & `repeat_header`.
-`striped` will add alternative row colors to the table. It will imports
-`LaTeX` package `xcolor` if enabled. `hold_position` will "hold" the floating
-table to the exact position. It is useful when the `LaTeX` table is contained
- in a `table` environment after you specified captions in `kable()`. It will
- force the table to stay in the position where it was created in the document.
-`scale_down` is useful for super wide table. It will automatically adjust
-the table to page width. `repeat_header` in only meaningful in a longtable
+\code{basic}, \code{striped}, \code{hold_position}, \code{scale_down} & \code{repeat_header}.
+\code{striped} will add alternative row colors to the table. It will imports
+\code{LaTeX} package \code{xcolor} if enabled. \code{hold_position} will "hold" the floating
+table to the exact position. It is useful when the \code{LaTeX} table is contained
+in a \code{table} environment after you specified captions in \code{kable()}. It will
+force the table to stay in the position where it was created in the document.
+\code{scale_down} is useful for super wide table. It will automatically adjust
+the table to page width. \code{repeat_header} in only meaningful in a longtable
environment. It will let the header row repeat on every page in that long
table.}
-\item{full_width}{A `TRUE` or `FALSE` variable controlling whether the HTML
+\item{full_width}{A \code{TRUE} or \code{FALSE} variable controlling whether the HTML
table should have 100\% width. Since HTML and pdf have different flavors on
-the preferable format for `full_width`. If not specified, a HTML table will
-have full width by default but this option will be set to `FALSE` for a
+the preferable format for \code{full_width}. If not specified, a HTML table will
+have full width by default but this option will be set to \code{FALSE} for a
LaTeX table}
\item{position}{A character string determining how to position the table
-on a page. Possible values include `left`, `center`, `right`, `float_left`
-and `float_right`. Please see the package doc site for demonstrations. For
-a `LaTeX` table, if `float_*` is selected, `LaTeX` package `wrapfig` will be
+on a page. Possible values include \code{left}, \code{center}, \code{right}, \code{float_left}
+and \code{float_right}. Please see the package doc site for demonstrations. For
+a \code{LaTeX} table, if \code{float_*} is selected, \code{LaTeX} package \code{wrapfig} will be
imported.}
\item{font_size}{A numeric input for table font size}
@@ -48,7 +48,7 @@
}
\description{
This function provides a cleaner approach to modify the style
-of HTML tables other than using the `table.attr` option in `knitr::kable()`.
+of HTML tables other than using the \code{table.attr} option in \code{knitr::kable()}.
Currenly, it assumes the HTML document has boot
}
\examples{
diff --git a/man/landscape.Rd b/man/landscape.Rd
index 793569b..3b99bf1 100644
--- a/man/landscape.Rd
+++ b/man/landscape.Rd
@@ -7,7 +7,7 @@
landscape(kable_input, margin = NULL)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{margin}{Customizable page margin for special needs. Values can be
"1cm", "1in" or similar.}
diff --git a/man/row_spec.Rd b/man/row_spec.Rd
index deb7912..d8237ad 100644
--- a/man/row_spec.Rd
+++ b/man/row_spec.Rd
@@ -7,7 +7,7 @@
row_spec(kable_input, row, bold = FALSE, italic = FALSE)
}
\arguments{
-\item{kable_input}{Output of `knitr::kable()` with `format` specified}
+\item{kable_input}{Output of \code{knitr::kable()} with \code{format} specified}
\item{row}{A numeric value indicating which row to be selected. You don't
need to count in header rows or group labeling rows.}
diff --git a/man/usepackage_latex.Rd b/man/usepackage_latex.Rd
index 62cabb8..ab2e09c 100644
--- a/man/usepackage_latex.Rd
+++ b/man/usepackage_latex.Rd
@@ -12,7 +12,7 @@
\item{options}{The LaTeX options for the package}
}
\description{
-Load a LaTeX package using R code. Just like `\\usepackage{}`
+Load a LaTeX package using R code. Just like \code{\\usepackage{}}
in LaTeX
}
\examples{