docs(vignettes): formatting footnote symbols with an user-defined fun…

…ction

vignettes/format_columns.Rmd

@@ -216,6 +216,63 @@ data.frame(
   colformat_md()
 ```
 
+Experimentally, reference symbols can be formatted by an user-defined function.
+
+```{r}
+#' Custom formatter of reference symbols
+#'
+#' @param n n-th reference symbol (integer)
+#' @param part where footnote exists: "body" or "header"
+#' @param footer whether to format sybols in the footer: `TRUE` or `FALSE`
+#'
+#' @return a character vector which will further be processed as markdown texts
+ref <- function(n, part, footer) {
+  # Header uses letters and body uses integers for the symbols
+  s <- if (part == "header") {
+    letters[n]
+  } else {
+    as.character(n)
+  }
+
+  # Suffix symbols with ": " (a colon and a space) in the footer
+  if (footer) {
+    return(paste(s, ":\\ "))
+  }
+
+  # Use superscript in the header and the body
+  return(paste0("^", s, "^"))
+}
+
+# Apply custom function to format a table with footnotes
+tibble::tibble(
+  "header1^[note a]" = c("x^[note 1]", "y"),
+  "header2" = c("a", "b^[note 2]")
+) %>%
+  as_flextable() %>%
+  # process header first
+  colformat_md(
+    part = "header", .footnote_options = footnote_options(ref)
+  ) %>%
+  # process body next
+  colformat_md(
+    part = "body", .footnote_options = footnote_options(ref)
+  ) %>%
+  # tweak width for visibility
+  flextable::autofit(add_w = 0.2)
+```
+
+Some notes:
+
+- `colformat_md()` should be applied separately to the header and the body. In other words, `part = "all"` is not recommended. That may order footnotes unexpectedly.
+- `footnote_options(ref)` should not be shared among the header and the body.
+
+  ```r
+  # DO NOT SHARE fopts among header and body
+  fopts <- footnote_options(ref)
+  ... %>%
+    colformat_md(part = "header", .footnote_options = fopts) %>%
+    colformat_md(part = "body", .footnote_options = fopts)
+  ```
 
 # Images