|
| 1 | +#' Customizing PDF document styles |
| 2 | +#' |
| 3 | +#' Using YAML metadata to customize PDF documents. |
| 4 | +#' |
| 5 | +#' You can easily customize fonts and a few other style attributes of |
| 6 | +#' PDF documents (\code{tintPdf} and \code{tintBook}) with |
| 7 | +#' YAML metadata |
| 8 | +#' |
| 9 | +#' @section Changing the fonts: |
| 10 | +#' |
| 11 | +#' You can use the fonts from the default \code{tufte} styles by setting |
| 12 | +#' \code{defaultfonts: true} |
| 13 | +#' |
| 14 | +#' You can choose custom LaTeX font packages using \code{latexfonts}: |
| 15 | +#' \preformatted{ |
| 16 | +#' latexfonts: "bera" |
| 17 | +#' } |
| 18 | +#' will use Bera Serif fonts. You can also specify multiple fonts |
| 19 | +#' (for instance serif, sans-serif, and typewriter families) |
| 20 | +#' \preformatted{ |
| 21 | +#' latexfonts: |
| 22 | +#' - "bera" |
| 23 | +#' - "FiraSans" |
| 24 | +#' - "FiraSansMono" |
| 25 | +#' } |
| 26 | +#' will use the Bera Serif font for regular text, Fira Sans Regular for |
| 27 | +#' sans serif, and Fira Sans Mono for typewriter. |
| 28 | +#' |
| 29 | +#' You can also pass options to the packages: |
| 30 | +#' \preformatted{ |
| 31 | +#' latexfonts: |
| 32 | +#' - package: newtxmath |
| 33 | +#' options: |
| 34 | +#' - cmintegrals |
| 35 | +#' - cmbraces |
| 36 | +#' - package: ebgaramond-maths |
| 37 | +#' - package: nimbusmononarrow |
| 38 | +#' } |
| 39 | +#' will use EB Garamond, with matching maths fonts from the \code{newtxmath} |
| 40 | +#' package, and Nimbus Mono Narrow for the typewriter font. |
| 41 | +#' |
| 42 | +#' If you want to specify a sans-serif font for the main text, many |
| 43 | +#' packages allow you to do this with options: |
| 44 | +#' The default for tint is to use the equivalent of |
| 45 | +#' \preformatted{ |
| 46 | +#' latexfonts: |
| 47 | +#' - package: roboto |
| 48 | +#' options: |
| 49 | +#' - sfdefault |
| 50 | +#' - condensed |
| 51 | +#' } |
| 52 | +#' where \code{sfdefault} specifies that the default text font should be Roboto. |
| 53 | +#' Other packages use different options, such as Lato, another sans-serif |
| 54 | +#' font, which you would specify as the main font like this: |
| 55 | +#' \preformatted{ |
| 56 | +#' latexfonts: |
| 57 | +#' - package: lato |
| 58 | +#' options: default |
| 59 | +#' } |
| 60 | +#' |
| 61 | +#' |
| 62 | +#' @section Link Color: |
| 63 | +#' |
| 64 | +#' Changing the link color |
| 65 | +#' |
| 66 | +#' By default, tint uses a grayish-blue color for hyperlinks. If you want to |
| 67 | +#' change this, you can use the YAML \code{linkcolor} variable either as a |
| 68 | +#' string with three numbers (red, green, and blue) separated by commas: |
| 69 | +#' \preformatted{ |
| 70 | +#' linkcolor: "0.3,0.3,0.6" |
| 71 | +#' } |
| 72 | +#' which gives a subtler bluish-gray, |
| 73 | +#' or as a list of three colors: |
| 74 | +#' \preformatted{ |
| 75 | +#' linkcolor: |
| 76 | +#' - 0.5 |
| 77 | +#' - 0.2 |
| 78 | +#' - 0.5 |
| 79 | +#' } |
| 80 | +#' which gives a mauve color. |
| 81 | +#' |
| 82 | +#' @seealso \link{Custom-templates} |
| 83 | +#' @name YAML-metadata |
| 84 | +NULL |
| 85 | + |
| 86 | +#' Custom document templates |
| 87 | +#' |
| 88 | +#' Using custom document templates |
| 89 | +#' |
| 90 | +#' If you want to make more significant changes to the document styles, |
| 91 | +#' you can make custom Pandoc templates, using the examples provided with |
| 92 | +#' this package. |
| 93 | +#' |
| 94 | +#' You will need to have some expertise with LaTeX to do this, but you |
| 95 | +#' can take the templates, such as \code{tintPdf-template.tex} |
| 96 | +#' or \code{tintBook-template.tex}, which you can locate on your computer with |
| 97 | +#' \preformatted{ |
| 98 | +#' system.file("rmarkdown", "templates", "tintPdf", "resources", |
| 99 | +#' "tintPdf-template.tex", package="tint") |
| 100 | +#' } |
| 101 | +#' and |
| 102 | +#' \preformatted{ |
| 103 | +#' system.file("rmarkdown", "templates", "tintBook", "resources", |
| 104 | +#' "tintBook-template.tex", package="tint") |
| 105 | +#' } |
| 106 | +#' |
| 107 | +#' Copy those files to the folder where your RMarkdown file is located and edit them and then |
| 108 | +#' tell tint to use your custom template instead of its built-in ones by using |
| 109 | +#' the YAML attribute \code{template} in your \code{output} block: |
| 110 | +#' \preformatted{ |
| 111 | +#' output: |
| 112 | +#' tint::tintPdf: |
| 113 | +#' template: "my-custom-template.tex" |
| 114 | +#' } |
| 115 | +#' |
| 116 | +#' @seealso \link{YAML-metadata} |
| 117 | +#' @name Custom-templates |
| 118 | +NULL |
| 119 | + |
| 120 | + |
1 | 121 | #' @inheritParams rmarkdown::pdf_document |
2 | 122 | #' @rdname tintHtml |
3 | 123 | tintPdf<-function(fig_width=4,fig_height=2.5,fig_crop=TRUE, |
4 | 124 | dev='pdf',highlight='tango', |
5 | 125 | citation_package='natbib',latex_engine='pdflatex',...) { |
6 | 126 | tintPdfCreate('tufte-handout',fig_width,fig_height,fig_crop, |
7 | | -dev,highlight,citation_package,...) |
| 127 | +dev,highlight,citation_package, |
| 128 | +latex_engine=latex_engine,...) |
8 | 129 | } |
9 | 130 |
|
10 | 131 | #' @inheritParams rmarkdown::pdf_document |
11 | 132 | #' @rdname tintHtml |
12 | 133 | tintBook<-function(fig_width=4,fig_height=2.5,fig_crop=TRUE, |
13 | 134 | dev='pdf',highlight='tango', |
14 | 135 | citation_package='natbib',latex_engine='pdflatex',...) { |
15 | | - tintPdfCreate('tufte-book',fig_width,fig_height,fig_crop, |
16 | | -dev,highlight,citation_package, |
17 | | - template_resources("tintBook","tintBook-template.tex"),...) |
| 136 | +# The manipulation of the ellipsis argument below allows us to |
| 137 | +# inject a default template argument if one is not present, but |
| 138 | +# to use an optional supplied argument. |
| 139 | +args=list(...) |
| 140 | +if (!"template"%in% names(args)) { |
| 141 | +args$template= template_resources('tintBook','tintBook-template.tex') |
| 142 | + } |
| 143 | +args= c(list(documentclass="tufte-book",fig_width=fig_width, |
| 144 | +fig_height=fig_height,fig_crop=fig_crop, |
| 145 | +dev=dev,highlight=highlight, |
| 146 | +citation_package=citation_package, |
| 147 | +latex_engine=latex_engine), |
| 148 | +args) |
| 149 | + do.call(tintPdfCreate,args) |
18 | 150 | } |
19 | 151 |
|
20 | 152 |
|
21 | 153 | tintPdfCreate<-function(documentclass= c('tufte-handout','tufte-book'), |
22 | 154 | fig_width=4,fig_height=2.5,fig_crop=TRUE, |
23 | | -dev='pdf',highlight='default',citation_package='natbib', |
| 155 | +dev='pdf',highlight='default', |
| 156 | +citation_package='natbib',latex_engine="pdflatex", |
24 | 157 | template= template_resources('tintPdf','tintPdf-template.tex'),...) { |
25 | 158 |
|
26 | 159 | ## resolve default highlight |
27 | 160 | if (identical(highlight,'default'))highlight='pygments' |
28 | | - |
| 161 | + |
| 162 | +# The template argument can either be a filename or a string specifying a |
| 163 | +# function call. |
| 164 | +# To decide which it is, we decide that it's a function call if both: |
| 165 | +# There's no file at that path; |
| 166 | +# The string looks like a legal function call: starts with a lexically |
| 167 | +# legal name followed by an open parenthesis, some stuff, and then ends with |
| 168 | +# a closing parenthesis. |
| 169 | +if (!file.exists(template)&& |
| 170 | + grepl("^[a-zA-Z_.][a-zA-Z0-9_.:]+\\(.*\\)$",template)) { |
| 171 | +template= eval(parse(text=template)) |
| 172 | + } |
| 173 | + |
29 | 174 | ## call the base pdf_document format with the appropriate options |
30 | 175 | format<-rmarkdown::pdf_document(fig_width=fig_width,fig_height=fig_height, |
31 | 176 | fig_crop=fig_crop,dev=dev,highlight=highlight, |
32 | 177 | citation_package=citation_package, |
| 178 | +latex_engine=latex_engine, |
33 | 179 | template=template,...) |
34 | 180 |
|
35 | 181 | ## LaTeX document class |
|