diff --git a/.travis.yml b/.travis.yml index e38786a..3bd0e3d 100644 --- a/.travis.yml +++ b/.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 diff --git a/ChangeLog b/ChangeLog index e9b8825..40ab6d4 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2018-11-20 Jonathan Gilligan + + * 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 * DESCRIPTION (Version, Date): Release 0.1.0 diff --git a/DESCRIPTION b/DESCRIPTION index 424403f..66363f5 100644 --- a/DESCRIPTION +++ b/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 +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 diff --git a/R/html.R b/R/html.R index bcd4764..feffd03 100644 --- a/R/html.R +++ b/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()) { diff --git a/R/pdf.R b/R/pdf.R index 136b1a1..04c4d7f 100644 --- a/R/pdf.R +++ b/R/pdf.R @@ -1,10 +1,131 @@ +#' 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 @@ -12,24 +133,49 @@ tintPdf <- function(fig_width = 4, fig_height = 2.5, fig_crop = TRUE, 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 diff --git a/inst/rmarkdown/templates/tintBook/resources/tintBook-template.tex b/inst/rmarkdown/templates/tintBook/resources/tintBook-template.tex index 0147dd6..7a4dd6b 100644 --- a/inst/rmarkdown/templates/tintBook/resources/tintBook-template.tex +++ b/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,% diff --git a/inst/rmarkdown/templates/tintPdf/resources/tintPdf-template.tex b/inst/rmarkdown/templates/tintPdf/resources/tintPdf-template.tex index a1443f8..6aac3c1 100644 --- a/inst/rmarkdown/templates/tintPdf/resources/tintPdf-template.tex +++ b/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,% diff --git a/man/Custom-templates.Rd b/man/Custom-templates.Rd new file mode 100644 index 0000000..76ef8d9 --- /dev/null +++ b/man/Custom-templates.Rd @@ -0,0 +1,38 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pdf.R +\name{Custom-templates} +\alias{Custom-templates} +\title{Custom document templates} +\description{ +Using custom document templates +} +\details{ +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} +} diff --git a/man/YAML-metadata.Rd b/man/YAML-metadata.Rd new file mode 100644 index 0000000..0f64e8a --- /dev/null +++ b/man/YAML-metadata.Rd @@ -0,0 +1,92 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/pdf.R +\name{YAML-metadata} +\alias{YAML-metadata} +\title{Customizing PDF document styles} +\description{ +Using YAML metadata to customize PDF documents. +} +\details{ +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} +} diff --git a/man/tintHtml.Rd b/man/tintHtml.Rd index b0f5227..61958a1 100644 --- a/man/tintHtml.Rd +++ b/man/tintHtml.Rd @@ -15,12 +15,12 @@ tintHtml(...) tint(...) -tintPdf(fig_width = 4, fig_height = 2.5, fig_crop = TRUE, dev = "pdf", - highlight = "tango", citation_package = "natbib", +tintPdf(fig_width = 4, fig_height = 2.5, fig_crop = TRUE, + dev = "pdf", highlight = "tango", citation_package = "natbib", latex_engine = "pdflatex", ...) -tintBook(fig_width = 4, fig_height = 2.5, fig_crop = TRUE, dev = "pdf", - highlight = "tango", citation_package = "natbib", +tintBook(fig_width = 4, fig_height = 2.5, fig_crop = TRUE, + dev = "pdf", highlight = "tango", citation_package = "natbib", latex_engine = "pdflatex", ...) newthought(text) @@ -33,9 +33,13 @@ sans_serif(text) } \arguments{ \item{...}{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.} \item{fig_width}{Default width (in inches) for figures} @@ -69,10 +73,11 @@ Richard Feynman, but with an updated font choice. \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. \code{newthought()} can be used in inline R expressions in R Markdown (e.g. \samp{`r newthought(Some text)`}), and it works for both @@ -95,3 +100,6 @@ library(tint) \references{ See \url{http://rstudio.github.io/tufte} for an example. } +\seealso{ +\link{Custom-templates}, \link{YAML-metadata}. +}