Merge pull request #30 from jonathan-g/devel

Proposed changes for flexible styling in tintPdf and tintBook

.travis.yml

@@ -4,7 +4,7 @@ language: c
 
 sudo: required
 
-dist: trusty
+dist: xenial
 
 before_install:
   - curl -OLs https://eddelbuettel.github.io/r-travis/run.sh && chmod 0755 run.sh

ChangeLog

@@ -1,3 +1,25 @@
+2018-11-20 Jonathan Gilligan <jonathan.gilligan@gmail.com>
+
+    * R/pdf.R: 
+        * Added options for user-specified LaTeX templates in YAML block to 
+          override the built-in ones for tintPdf and tintBook;
+        * Made YAML output option latex_engine work correctly.
+        * Added documentation for new capabilities with YAML style options
+          and custom LaTeX templates.
+
+    * R/html.R: Updated documentation for tint* functions.
+
+    * inst/rmarkdown/templates/tintBoot/resources/tintBook-template.tex:
+      Updated template to allow user-specified fonts and link color.
+    * inst/rmarkdown/templates/tintBoot/resources/tintBook-template.tex:
+      Same.
+
+    * DESCRIPTION: Add myself as a co-author, bump version number.
+
+    * man/Custom-templates.Rd: New documentation for using custom templates.
+    * man/YAML-metadata.Rd: New documentation on new YAML style options.
+    * man/tintHtml.Rd: Updated documentation on tint* functions.
+
 2018-04-08  Dirk Eddelbuettel  <edd@debian.org>
 
 	* DESCRIPTION (Version, Date): Release 0.1.0

DESCRIPTION

@@ -1,10 +1,14 @@
 Package: tint
 Type: Package
 Title: 'tint' is not 'Tufte'
-Version: 0.1.0
-Date: 2018-04-08
-Author: Dirk Eddelbuettel
-Maintainer: Dirk Eddelbuettel <edd@debian.org>
+Version: 0.1.0.9000
+Date: 2018-11-20
+Authors@R: 
+  c(person("Dirk", "Eddelbuettel", role = c("cre", "aut"), 
+           email = "edd@debian.org"),
+    person("Jonathan", "Gilligan", role = c("aut"),
+           email = "jonathan.gilligan@gmail.com", 
+           comment = c(ORCID="0000-0003-1375-6686")))
 Description: A 'tufte'-alike style for 'rmarkdown'.
 URL: http://dirk.eddelbuettel.com/code/tint.html
 BugReports: https://github.com/eddelbuettel/tint/issues

R/html.R

@@ -4,18 +4,26 @@
 #' Richard Feynman, but with an updated font choice.
 #'
 #' @param ... Other arguments to be passed to \code{\link{pdf_document}} or
-#'   \code{\link{html_document}} (note you cannot use the \code{template}
-#'   argument in \code{tintPdf} or the \code{theme} argument in
-#'   \code{tintHHtml()}; these arguments have been set internally)
+#'   \code{\link{html_document}} 
+#'   
+#'   
+#'  \strong{Note:} For \code{tintPdf} and \code{tintBook}, you can 
+#'  specify a custom \code{template} argument to replace the default. 
+#'  You \emph{cannot} use the \code{theme} argument in \code{tintHHtml()} 
+#'  because this argument has been set internally.
+#'  
 #' @references See \url{http://rstudio.github.io/tufte} for an example.
 #' @examples library(tint)
 #'
 #' @details \code{tintHtml} provides the HTML format based on the Tufte CSS
 #'   \url{https://edwardtufte.github.io/tufte-css/} with fonts set according to
-#' \url{http://nogginfuel.com/envisioned-css/}. \code{tintPdf} provides a similar
-#' PDF format using the same font family and styling applied to the
-#' Tufte-LaTeX \url{https://tufte-latex.github.io/tufte-latex/} class. \code{tintBook}
-#' is a (currently rather experimental) pdf book variant.
+#' \url{http://nogginfuel.com/envisioned-css/}. 
+#' \code{tintPdf} provides a similar PDF format using the same font family and 
+#' styling applied to the Tufte-LaTeX 
+#' \url{https://tufte-latex.github.io/tufte-latex/} class. 
+#' \code{tintBook} is a (currently rather experimental) pdf book variant.
+#' 
+#' @seealso \link{Custom-templates}, \link{YAML-metadata}.
 tintHtml <- function(...) {
 
   html_document2 = function(..., extra_dependencies = list()) {

R/pdf.R

@@ -1,35 +1,181 @@
+#' Customizing PDF document styles
+#' 
+#' Using YAML metadata to customize PDF documents.
+#' 
+#' You can easily customize fonts and a few other style attributes of  
+#' PDF documents (\code{tintPdf} and \code{tintBook}) with 
+#' YAML metadata
+#' 
+#' @section Changing the fonts:
+#' 
+#' You can use the fonts from the default \code{tufte} styles by setting
+#' \code{defaultfonts: true}
+#' 
+#' You can choose custom LaTeX font packages using \code{latexfonts}:
+#' \preformatted{
+#' latexfonts: "bera"
+#' }
+#' will use Bera Serif fonts. You can also specify multiple fonts
+#' (for instance serif, sans-serif, and typewriter families)
+#' \preformatted{
+#' latexfonts:
+#'   - "bera"
+#'   - "FiraSans"
+#'   - "FiraSansMono"
+#' }
+#' will use the Bera Serif font for regular text, Fira Sans Regular for
+#' sans serif, and Fira Sans Mono for typewriter.
+#' 
+#' You can also pass options to the packages:
+#' \preformatted{
+#' latexfonts: 
+#'   - package: newtxmath
+#'     options: 
+#'       - cmintegrals
+#'       - cmbraces
+#'   - package: ebgaramond-maths
+#'   - package: nimbusmononarrow
+#' }
+#' will use EB Garamond, with matching maths fonts from the \code{newtxmath}
+#' package, and Nimbus Mono Narrow for the typewriter font.
+#' 
+#' If you want to specify a sans-serif font for the main text, many
+#' packages allow you to do this with options:
+#' The default for tint is to use the equivalent of
+#' \preformatted{
+#' latexfonts:
+#'   - package: roboto
+#'     options: 
+#'       - sfdefault
+#'       - condensed
+#' }
+#' where \code{sfdefault} specifies that the default text font should be Roboto.
+#' Other packages use different options, such as Lato, another sans-serif 
+#' font, which you would specify as the main font like this:
+#' \preformatted{
+#' latexfonts:
+#'   - package: lato
+#'     options: default
+#' }
+#' 
+#' 
+#' @section Link Color:
+#' 
+#' Changing the link color
+#' 
+#' By default, tint uses a grayish-blue color for hyperlinks. If you want to
+#' change this, you can use the YAML \code{linkcolor} variable either as a 
+#' string with three numbers (red, green, and blue) separated by commas:
+#' \preformatted{
+#' linkcolor: "0.3,0.3,0.6"
+#' }
+#' which gives a subtler bluish-gray,
+#' or as a list of three colors:
+#' \preformatted{
+#' linkcolor:
+#'   - 0.5
+#'   - 0.2
+#'   - 0.5
+#' }
+#' which gives a mauve color.
+#' 
+#' @seealso \link{Custom-templates}
+#' @name YAML-metadata
+NULL
+
+#' Custom document templates
+#' 
+#' Using custom document templates
+#' 
+#' If you want to make more significant changes to the document styles,
+#' you can make custom Pandoc templates, using the examples provided with
+#' this package. 
+#' 
+#' You will need to have some expertise with LaTeX to do this, but you 
+#' can take the templates, such as \code{tintPdf-template.tex} 
+#' or \code{tintBook-template.tex}, which you can locate on your computer with
+#' \preformatted{
+#' system.file("rmarkdown", "templates", "tintPdf", "resources", 
+#'             "tintPdf-template.tex", package="tint")
+#' }
+#' and 
+#' \preformatted{
+#' system.file("rmarkdown", "templates", "tintBook", "resources", 
+#'             "tintBook-template.tex", package="tint")
+#' }
+#' 
+#' Copy those files to the folder where your RMarkdown file is located and edit them and then
+#' tell tint to use your custom template instead of its built-in ones by using
+#' the YAML attribute \code{template} in your \code{output} block: 
+#' \preformatted{
+#' output: 
+#'   tint::tintPdf:
+#'     template: "my-custom-template.tex"
+#' }
+#' 
+#' @seealso \link{YAML-metadata}
+#' @name Custom-templates
+NULL
+
+
 #' @inheritParams rmarkdown::pdf_document
 #' @rdname tintHtml
 tintPdf <- function(fig_width = 4, fig_height = 2.5, fig_crop = TRUE,
                     dev = 'pdf', highlight = 'tango',
                     citation_package = 'natbib', latex_engine = 'pdflatex', ...) {
     tintPdfCreate('tufte-handout', fig_width, fig_height, fig_crop,
-                  dev, highlight, citation_package, ...)
+                  dev, highlight, citation_package, 
+                  latex_engine = latex_engine, ...)
 }
 
 #' @inheritParams rmarkdown::pdf_document
 #' @rdname tintHtml
 tintBook <- function(fig_width = 4, fig_height = 2.5, fig_crop = TRUE,
                     dev = 'pdf', highlight = 'tango',
                     citation_package = 'natbib', latex_engine = 'pdflatex', ...) {
-    tintPdfCreate('tufte-book', fig_width, fig_height, fig_crop,
-                  dev, highlight, citation_package,
-                  template_resources("tintBook", "tintBook-template.tex"), ...)
+    # The manipulation of the ellipsis argument below allows us to 
+    # inject a default template argument if one is not present, but
+    # to use an optional supplied argument.
+    args = list(...)
+    if (! "template" %in% names(args)) {
+        args$template = template_resources('tintBook', 'tintBook-template.tex')
+    }
+    args = c(list(documentclass = "tufte-book", fig_width = fig_width, 
+                  fig_height = fig_height, fig_crop = fig_crop,
+                  dev = dev, highlight = highlight, 
+                  citation_package = citation_package,
+                  latex_engine = latex_engine),
+             args)
+    do.call(tintPdfCreate, args)
 }
 
 
 tintPdfCreate <- function(documentclass = c('tufte-handout', 'tufte-book'),
                           fig_width = 4, fig_height = 2.5, fig_crop = TRUE,
-                          dev = 'pdf', highlight = 'default', citation_package = 'natbib',
+                          dev = 'pdf', highlight = 'default', 
+                          citation_package = 'natbib', latex_engine = "pdflatex",
                           template = template_resources('tintPdf', 'tintPdf-template.tex'), ...) {
 
     ## resolve default highlight
     if (identical(highlight, 'default')) highlight = 'pygments'
-
+
+    # The template argument can either be a filename or a string specifying a
+    # function call.
+    # To decide which it is, we decide that it's a function call if both:
+    # There's no file at that path;
+    # The string looks like a legal function call: starts with a lexically
+    # legal name followed by an open parenthesis, some stuff, and then ends with
+    # a closing parenthesis.
+    if (!file.exists(template) && 
+        grepl("^[a-zA-Z_.][a-zA-Z0-9_.:]+\\(.*\\)$", template)) {
+        template = eval(parse(text = template))
+    }
+
     ## call the base pdf_document format with the appropriate options
     format <- rmarkdown::pdf_document(fig_width = fig_width, fig_height = fig_height,
                                       fig_crop = fig_crop, dev = dev, highlight = highlight,
                                       citation_package = citation_package,
+                                      latex_engine = latex_engine,
                                       template = template, ...)
 
     ## LaTeX document class

inst/rmarkdown/templates/tintBook/resources/tintBook-template.tex

@@ -1,4 +1,4 @@
-\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$}
+\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$if(defaultfonts)$fonts,$else$nofonts,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$}
 
 % ams
 \usepackage{amssymb,amsmath}
@@ -121,12 +121,26 @@
 
 %% -- tint overrides
 %% fonts, using roboto (condensed) as default
+$if(defaultfonts)$
+% Using default fonts.
+$else$
+$if(latexfonts)$
+$if(latexfonts.include)$
+\input{$latexfonts.include$}
+$else$
+$for(latexfonts)$
+\usepackage$if(latexfonts.options)$[$for(latexfonts.options)$$latexfonts.options$$sep$,$endfor$]$endif${$if(latexfonts.package)$$latexfonts.package$$else$$latexfonts$$endif$}
+$endfor$
+$endif$
+$else$
 \usepackage[sfdefault,condensed]{roboto}
 %% also nice: \usepackage[default]{lato}
+$endif$
+$endif$
 
 %% colored links, setting 'borrowed' from RJournal.sty with 'Thanks, Achim!'
 \RequirePackage{color}
-\definecolor{link}{rgb}{0.1,0.1,0.8} %% blue with some grey
+\definecolor{link}{rgb}{$if(linkcolor)$$for(linkcolor)$$linkcolor$$sep$,$endfor$$else$0.1,0.1,0.8$endif$} %% blue with some grey
 \hypersetup{
   colorlinks,%
   citecolor=link,%

inst/rmarkdown/templates/tintPdf/resources/tintPdf-template.tex

@@ -1,4 +1,4 @@
-\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$}
+\documentclass[$if(fontsize)$$fontsize$,$endif$$if(lang)$$lang$,$endif$$if(papersize)$$papersize$,$endif$$if(defaultfonts)$fonts,$else$nofonts,$endif$$for(classoption)$$classoption$$sep$,$endfor$]{$documentclass$}
 
 % ams
 \usepackage{amssymb,amsmath}
@@ -118,12 +118,26 @@
 
 %% -- tint overrides
 %% fonts, using roboto (condensed) as default
+$if(defaultfonts)$
+% Using default fonts.
+$else$
+$if(latexfonts)$
+$if(latexfonts.include)$
+\input{$latexfonts.include$}
+$else$
+$for(latexfonts)$
+\usepackage$if(latexfonts.options)$[$for(latexfonts.options)$$latexfonts.options$$sep$,$endfor$]$endif${$if(latexfonts.package)$$latexfonts.package$$else$$latexfonts$$endif$}
+$endfor$
+$endif$
+$else$
 \usepackage[sfdefault,condensed]{roboto}
 %% also nice: \usepackage[default]{lato}
+$endif$
+$endif$
 
 %% colored links, setting 'borrowed' from RJournal.sty with 'Thanks, Achim!'
 \RequirePackage{color}
-\definecolor{link}{rgb}{0.1,0.1,0.8} %% blue with some grey
+\definecolor{link}{rgb}{$if(linkcolor)$$for(linkcolor)$$linkcolor$$sep$,$endfor$$else$0.1,0.1,0.8$endif$} %% blue with some grey
 \hypersetup{
   colorlinks,%
   citecolor=link,%