Merge pull request #1995 from thebioengineer/latex_newline

Random Latex Updates -

Author: rich-iannone

NAMESPACE

@@ -169,6 +169,7 @@ export(info_locales)
 export(info_paletteer)
 export(info_time_style)
 export(info_unit_conversions)
+export(latex)
 export(local_image)
 export(matches)
 export(md)

NEWS.md

@@ -6,6 +6,10 @@
 
 * as_word() now handles "<br>" line breaks for md() and html(), and no longer automatically adds "Table N" ahead of the caption. 
 
+* Improvements to options for LaTeX including repeating Headers, removing top and bottom lines, applying font sizes, and line breaks (@thebioengineer, #1630, #1061, #1767)
+
+* Add `latex()` function to let users write the LaTeX they wish to see in the table cell or text (@thebioengineer, #1912)
+
 # gt 1.0.0
 
 ## Minor improvements and bug fixes
@@ -28,6 +32,7 @@
 
 * Fixed many typos in the documentation. (#1910, thanks @MichaelChirico!)
 
+
 # gt 0.11.1
 
 ## Breaking changes

R/dt_options.R

@@ -272,5 +272,8 @@ dt_options_tbl <-
     "quarto_disable_processing",         FALSE,  "quarto",           "logical", FALSE,
     "quarto_use_bootstrap",              FALSE,  "quarto",           "logical", FALSE,
     "latex_use_longtable",               FALSE,  "latex",            "logical", FALSE,
+    "latex_header_repeat",               FALSE,  "latex",            "logical", FALSE,
+    "latex_toprule",                     FALSE,  "latex",            "logical",  TRUE,
+    "latex_bottomrule",                  FALSE,  "latex",            "logical",  TRUE,
     "latex_tbl_pos",                     FALSE,  "latex",            "value",   "t",
   )[-1, ]

R/helpers.R

@@ -137,6 +137,58 @@ html <- function(text, ...) {
   htmltools::HTML(text, ...)
 }
 
+# latex() -----------------------------------------------------------------------
+#' Interpret input text as LaTeX-formatted text
+#'
+#' @description
+#'
+#' For certain pieces of text (like in column labels or table headings) we may
+#' want to express them as raw LaTeX. In fact, with LaTeX, so much more can be done for formatting.
+#' The `latex()` function will guard the input LaTeX from being escaped.
+#'
+#' @param text *LaTeX text*
+#'
+#'   `scalar<character>` // **required**
+#'
+#'   The text that is understood to be LaTeX text, which is to be preserved in
+#'   the LaTeX output context.
+#'
+#'
+#' @return A character object of class `latex`. It's tagged as an latex fragment
+#'   that is not to be sanitized.
+#'
+#' @section Examples:
+#'
+#' Use the [`exibble`] dataset to create a **gt** table. When adding a title
+#' through [tab_header()], we'll use the `latex()` helper to signify to **gt**
+#' that we're using LaTeX formatting.
+#'
+#' ```r
+#' exibble |>
+#'   dplyr::select(currency, char) |>
+#'   gt() |>
+#'   tab_header(title = latex("\\emph{LaTeX}"))
+#' ```
+#'
+#' \if{html}{\out{
+#' `r man_get_image_tag(file = "man_latex_1.png")`
+#' }}
+#'
+#' @family helper functions
+#' @section Function ID:
+#' 8-2
+#'
+#' @section Function Introduced:
+#' `v1.0.1` (May 10, 2025)
+#'
+#' @export
+latex <- function(text) {
+
+  # Apply the `from_latex` class
+  class(text) <- "from_latex"
+  text
+}
+
 # px() -------------------------------------------------------------------------
 #' Helper for providing a numeric value as pixels value
 #'

R/tab_options.R

@@ -534,6 +534,26 @@
 #'   use the `longtable` environment which will not float and may span multiple
 #'   pages.
 #'
+#'
+#' @param latex.header_repeat
+#'
+#'   * Specify if the header should repeat or not across pages*
+#'
+#'   For Long tables, it may be desirable to have the column headers repeat on
+#'   every page. Setting this parameter to `TRUE` will add a `\endhead` command
+#'   after the table headers so LaTeX knows where the headers end and will
+#'   repeat them on every page.
+#'
+#' @param latex.toprule,latex.bottomrule
+#'
+#'   * Specify if an hrule should be put in the table at the top (latex.toprule) or bottom (latex.bottomrule)*
+#'
+#'   By default the tables produced using latex code will include top and bottom
+#'   lines in the table via `\toprule` and `\bottomrule`. Setting these
+#'   parameters to `FALSE` will instead not have these commands added, which
+#'   lets the tables be produced without the top and bottom lines.
+#'
+#'
 #' @param latex.tbl.pos
 #'
 #'   *Specify latex floating position*
@@ -864,6 +884,9 @@ tab_options <- function(
     quarto.use_bootstrap = NULL,
     quarto.disable_processing = NULL,
     latex.use_longtable = NULL,
+    latex.header_repeat = NULL,
+    latex.toprule = NULL,
+    latex.bottomrule = NULL,
     latex.tbl.pos = NULL
 ) {
 

R/utils.R

@@ -939,6 +939,12 @@ process_text <- function(text, context = "html") {
 
       return(text)
 
+    } else if (inherits(text, "from_latex")) {
+
+      text <- as.character(text)
+
+      return(text)
+
     } else {
 
       text <- escape_latex(text = text)
@@ -1126,6 +1132,8 @@ markdown_to_latex <- function(text, md_engine) {
             return(NA_character_)
           }
 
+          x <- gsub("<br>","..gt_linebreak_indicator..", x)
+
           if (isTRUE(getOption("gt.html_tag_check", TRUE))) {
 
             if (grepl("<[a-zA-Z\\/][^>]*>", x)) {
@@ -1136,11 +1144,19 @@ markdown_to_latex <- function(text, md_engine) {
             }
           }
 
+
           if (names(md_engine_fn) == "commonmark") {
-            gsub("\\n$", "", md_engine_fn[[1]](text = x))
+           x <- gsub("\\n$", "", md_engine_fn[[1]](text = x))
           } else {
-            gsub("\\n$", "", md_engine_fn[[1]](text = x, format = "latex"))
+           x <- gsub("\\n$", "", md_engine_fn[[1]](text = x, format = "latex"))
+          }
+
+          if(grepl("..gt\\_linebreak\\_indicator..", x, fixed = TRUE)){
+            x <- paste0("\\shortstack[l]{" ,gsub("..gt\\_linebreak\\_indicator..", " \\\\", x, fixed = TRUE), "}")
           }
+
+          x
+
         }
       )
     )

R/utils_render_latex.R

@@ -88,11 +88,14 @@ latex_body_row <- function(content, type) {
 }
 
 #' @noRd
-latex_heading_row <- function(content) {
+latex_heading_row <- function(content, header_repeat = FALSE) {
+
 
   paste0(
     paste(paste(content, collapse = " & "), "\\\\ \n"),
-    "\\midrule\\addlinespace[2.5pt]\n",
+    "\\midrule",
+    if (header_repeat) {"\\endhead"},
+    "\\addlinespace[2.5pt]\n",
     collapse = ""
   )
 }
@@ -384,14 +387,38 @@ create_heading_component_l <- function(data) {
     footnote_subtitle_marks <- ""
   }
 
-  title_row <- latex_group("\\large ", heading$title, footnote_title_marks)
+  title_font_size <- dt_options_get_value(data, "heading_title_font_size")
+  table_font_size <- dt_options_get_value(data, "table_font_size")
+
+  if(identical(title_font_size,"default")){
+    title_font_size <- table_font_size
+  }
+
+  title_row <- latex_group(
+    convert_font_size_l(title_font_size),
+    " ",
+    heading$title,
+    footnote_title_marks,
+    convert_font_size_l(table_font_size)
+    )
 
   if (subtitle_defined) {
 
+    subtitle_font_size <- dt_options_get_value(data, "heading_subtitle_font_size")
+
+    if(identical(subtitle_font_size,"default")){
+      subtitle_font_size <- table_font_size
+    }
+
     subtitle_row <-
       paste0(
         " \\\\ \n",
-        latex_group("\\small ", heading$subtitle, footnote_subtitle_marks)
+        latex_group(
+          convert_font_size_l(subtitle_font_size),
+          " ",
+          heading$subtitle,
+          footnote_subtitle_marks,
+          convert_font_size_l(table_font_size))
       )
 
   } else {
@@ -490,8 +517,10 @@ create_columns_component_l <- function(data, colwidth_df) {
     headings_labels <- prepend_vec(headings_labels, stub_label)
   }
 
+  header_repeat <- dt_options_get_value(data, "latex_header_repeat")
+
   table_col_headings <-
-    paste0(latex_heading_row(content = headings_labels), collapse = "")
+    paste0(latex_heading_row(content = headings_labels, header_repeat = header_repeat), collapse = "")
 
   if (spanner_row_count > 0) {
 
@@ -595,8 +624,10 @@ create_columns_component_l <- function(data, colwidth_df) {
     table_col_spanners <- ""
   }
 
+  include_toprule <- dt_options_get_value(data, "latex_toprule")
+
   paste0(
-    "\\toprule\n",
+    if (include_toprule) {"\\toprule\n"},
     paste0(table_col_spanners, collapse = ""),
     table_col_headings
   )
@@ -637,7 +668,7 @@ create_body_component_l <- function(data, colwidth_df) {
         n_rows_in_group <- n_rows_in_group + dim(list_of_summaries$summary_df_data_list[[i]])[1L]
       }
       row_splits_body[[groups_rows_df$row_start[i]]][1] <-
-        sprintf("\\multirow{%d}{%s}{%s}",
+        sprintf("\\multirow[t]{%d}{%s}{%s}",
                 n_rows_in_group,
                 if (colwidth_df$unspec[1L] == 1L) "*" else "=",
                 groups_rows_df$group_label[i])
@@ -1027,8 +1058,11 @@ summary_rows_for_group_l <- function(
 #' @noRd
 create_table_end_l <- function(data) {
 
+  include_bottomrule <- dt_options_get_value(data, "latex_bottomrule")
+
+
   paste0(
-    "\\bottomrule\n",
+    if(include_bottomrule){"\\bottomrule\n"},
     ifelse(dt_options_get_value(data = data, option = "latex_use_longtable"),
            "\\end{longtable}\n",
            "\\end{tabular*}\n"),
@@ -1253,11 +1287,16 @@ convert_font_size_l <- function(x) {
     large = "\\large ",
     `x-large` = "\\Large ",
     `xx-large` = "\\LARGE ",
-    `xxx-large` = "\\huge "
+    `xxx-large` = "\\huge ",
+    `default` = ""
   )
 
-  if (as.character(x) %in% names(size_map))
+
+  if (as.character(x) %in% names(size_map)){
     return(size_map[[x]])
+  }else if(grepl("(pt|%|px|in|cm|emu|em)",x)){
+    return(.apply_style_fontsize_l(list('cell_text' = list('size' = round(parse_font_size_l(x))))))
+  }
 
   NULL
 }
@@ -1492,6 +1531,7 @@ apply_cell_styles_l <- function(content, style_obj) {
     # Apply changes that can be made to the bracketed environment
     out_text <- paste0(
       "{",
+
       .apply_style_style_l(style_obj),
       .apply_style_weight_l(style_obj),
       # Can generate "\small for example
@@ -1581,9 +1621,9 @@ apply_cell_styles_l <- function(content, style_obj) {
     return(
       paste0(
         "\\fontsize{",
-        style_obj[["cell_text"]][["size"]] * 0.75,
+        round(style_obj[['cell_text']][['size']] * 0.75),
         "}{",
-        style_obj[["cell_text"]][["size"]] * 0.75 * 1.25,
+        round(style_obj[['cell_text']][['size']] * 0.75 * 1.25),
         "}\\selectfont "
       )
     )
@@ -1669,28 +1709,28 @@ create_fontsize_statement_l <- function(data) {
 
   fs_fmt <- "\\fontsize{%3.1fpt}{%3.1fpt}\\selectfont\n"
   if (grepl(pattern = "^[[:digit:]]+(\\%|in|cm|emu|em|pt|px)$", size)) {
+    font_size <- parse_font_size_l(size)
+    ## parse_font_size_l returns font size in p
+    fs_statement <- sprintf(fs_fmt, round(font_size*.75), round(font_size* 1.2 * .75))
+  } else {
+    return("")
+  }
 
-    if (endsWith(size, "%")) {
-
-      multiple <- as.numeric(gsub("%", "", size, fixed = TRUE)) / 100
-      fs_statement <- sprintf(fs_fmt, multiple * 12, multiple * 12 * 1.2)
-
-    } else if (endsWith(size, "pt")) {
-
-      pt_size <- as.numeric(sub("pt$", "", size))
-      fs_statement <- sprintf(fs_fmt, pt_size, pt_size * 1.2)
+  fs_statement
 
-    } else {
+}
 
-      pt_size <- convert_to_px(size) * 0.75
-      fs_statement <- sprintf(fs_fmt, pt_size, pt_size * 1.2)
+parse_font_size_l <- function(x){
+  if (endsWith(x, "%")) {
 
-    }
+    size <- (as.numeric(gsub("%", "", x, fixed = TRUE)) / 100) * 16 * (4/3) ## 12pt is default font size, 4/3 to convert to px
 
-  } else return("")
+  } else {
 
-  fs_statement
+    size <- convert_to_px(x)
+  }
 
+  size
 }
 
 create_colwidth_df_l <- function(data) {