Is it possible to include an image in documentation generated by roxygen? I have a number of functions that are essentially wrappers for ggplot() that I'd like to document by showing an example of the output.
As per the change list from the announcement of R 2.14:
Rd markup has a new \figure tag so that figures can be included in
help pages when converted to HTML or LaTeX. There are examples on
the help pages for par() and points().
From: http://cran.r-project.org/doc/manuals/R-exts.html#Figures
To include figures in help pages, use the \figure markup. There are three forms.
The two commonly used simple forms are \figure{filename} and \figure{filename}{alternate text}. This will include a copy of the figure in either HTML or LaTeX output. In text output, the alternate text will be displayed instead. (When the second argument is omitted, the filename will be used.) Both the filename and the alternate text will be parsed verbatim, and should not include special characters that are significant in HTML or LaTeX.
The expert form is \figure{filename}{options: string}. (The word ‘options:’ must be typed exactly as shown and followed by at least one space.) In this form, the string is copied into the HTML img tag as attributes following the src attribute, or into the second argument of the \Figure macro in LaTeX, which by default is used as options to an \includegraphics call. As it is unlikely that any single string would suffice for both display modes, the expert form would normally be wrapped in conditionals. It is up to the author to make sure that legal HTML/LaTeX is used. For example, to include a logo in both HTML (using the simple form) and LaTeX (using the expert form), the following could be used:
\if{html}{\figure{logo.jpg}{Our logo}}
\if{latex}{\figure{logo.jpg}{options: width=0.5in}}
The files containing the figures should be stored in the directory man/figures. Files with extensions .jpg, .pdf, .png and .svg from that directory will be copied to the help/figures directory at install time. (Figures in PDF format will not display in most HTML browsers, but might be the best choice in reference manuals.) Specify the filename relative to man/figures in the \figure directive.
Related
I am new to R and Rmd and trying to generate a report using Rmd. This report has several images inserted along with the text. I am able to insert an image by hardcoding the path of the image. I have no problems with that but I need the path as a variable because it varies with the project. Can anyone help me with the syntax for calling a variable within a path to the image?
"Project123" changes based on the project. Is there a way I can declare this variable and call it to define the path?
Help please.
Images can use online R code for dynamic paths and/or alt text. (Early adopters of rmarkdown often tried this method as the default method of including R plots in the reports, using png(filepath...); plot(...); dev.off() followed by what I recommend you use.)
This will allow you to do what you need:
as raw markdown (and not inside a traditional code chunk).
If you aren't familiar with inline code blocks, then know that you can put just about anything in an inline code block. This is handy for including dynamic content in a paragraph of text, for example "the variance of the sample is \r var(sample(99))``". (Often it is just a pre-created variable, if numeric it is often rounded or formated to control the display of significant figures.)
I have a spreadsheet of exam questions that I want to use to generate quizzes and exams using R exams, and I'd like to include graphics in some of the questions.
The template here (http://www.r-exams.org/templates/fruit/) begins by defining the images as long base 64 encoded strings as generated by
base64enc::base64encode("file.png")
This seems fine, but if I have a dozen or so images of which I might only want a question to use one, two, or three images selected at random for programmatically generated exercises, how can I avoid including the encoding for all dozen images with every single exercise?
The best I can think of at the moment is to include LaTeX syntax for graphics inclusion in a spreadsheet of possible question options, and as exercises are generated, use regular expressions to find the file names inside the \includegraphics{} commands that will be included, encode those as base 64 strings, and include them in the exercise file, but I'm wondering if there's a way I can do this without writing my own code to parse LaTeX.
First a few clarifications:
The fruit exercises include the images as Base64 strings because the three icons are quite small (12K per icon) and it is convenient to have all information within the Rnw/Rmd exercise without the need to store graphics files separately. It is just one trick that can be nifty and that we wanted to demonstrate.
For more and larger images one could do the same trick but it is probably less convenient. To illustrate how static images can be included in an exercise, the following template is available: http://www.R-exams.org/templates/Rlogo/ It uses the include_supplement() function to declare a certain file as a supplement for the exercises. If this is a graphic it can then be integrated into the exercises via \includegraphics{...} in Rnw exercises and via  in Rmd exercises.
Each exercise just has to include the supplements it actually uses (and not all files from which these were sampled). And there is no need to do the Base64 encoding manually. This is done by the exams2xyz(...) functions automatically if needed.
Now for the scenario you describe. Say you have an exercise foo.Rmd in which you want to show one of three static images foo-1.png, foo-2.png, foo-3.png and ask questions about it. Then your R code might do something like:
i <- sample(1:3, 1)
img <- paste0("foo-", i, ".png")
include_supplement(img)
which randomly selects one of the three files and declares it to be an attachment. Then within the question text you would include the image via something like:
Caveats:
The code above assumes that the PNG images are located in the same directory as the Rmd exercise itself. If it is in a sub-directory bar/ say, you would need include_supplement(img, dir = "bar") etc.
If this exercise is rendered into HTML then the original file name (foo-1.png or foo-2.png or foo-3.png) would be visible in the HTML source code. This may (or may not) provide a hint for students what the correct answer is. If so, it would be better to include the file with a neutral name, e.g., include_supplement(img, target = "foo.png").
In Rnw exercises the code for including the graphic would be something like: \includegraphics{\Sexpr{img}}.
rmarkdown, following {xe|lua}latex, allows to specify fonts for main text, sans-serif text, monspaced text (most notably code chunks !) and math fonts in the YAML header. At least for PDF rendering via xetex, this works.
However, I found no (documented) way to pass options to the underlying setxxxfont \LaTeX command. For example, the YAML fragment :
```
monofont: Inconsolata
```
generates the following \LaTeX fragment :
\setmonofont[Mapping=tex-ansi]{Inconsolata}
I have two questions with this:
why is the Mapping=tex-ansi added ? And how to control it ? (I'm working in UTF8...).
How could I set additional arguments for the font options i.e. \setmonofont[Scale=0.91]{TeX Gyre Cursor}?
The R Markdown book and the Pandoc's User's Guide did not reveal anything pertinent.
Background:
When R Markdown converts the knitted code to the output format (PDF), a pandoc template is used. The template is stored within the package, and any variables which get replaced by the YAML variables are contained in the $$ Notation
1. Encoding
The Mapping=tex-ansi is added to the code as a workaround an issue as reported on GitHub. Therefore I would be cautious of deleting this for potential side effects.
If you do indeed wish to change this code, you will have to make a copy of the LaTeX template file used to convert the document. You can find the default template here. See here for some more information on providing custom templates.
2. Additional Font Options
You can use the monofontoptions YAML argument to add additional arguments to the font options.
Documentation of the variables which can be parsed by the LaTeX output are available in the pandoc documentation
I cannot find out how to make a page break in R bookdown.
With page break I mean that the content within one page is displayed as one website.
By default there is always a page break in front of every new section (like # Chapter 1).
So, if I run render_book each section becomes one html file.
But, if I have a lot of subsections then these sites get very long.
I would like to have page breaks before every subsection (like ## Chapter 1.1).
So far I tried adding \newpage, \pagebreak, --------------- to the .Rmd or to just provide the .Rmd files in the same structure as I would like to have them as .html files.
Either way, the .html files are always created according to the sections.
I think this is specified by the split_by argument of gitbook as documented here.
Sounds like you are using chapter but you want to be using section
The split_by argument specifies how you want to split the HTML output
into multiple pages, and its possible values are:
rmd: use the base filenames of the input Rmd files to create the HTML filenames, e.g., generate chapter3.html for chapter3.Rmd;
none: do not split the HTML file (the book will be a single HTML file);
chapter: split the file by the first-level headers;
section: split the file by the second-level headers;
chapter+number and section+number: similar to chapter and section, but the files will be numbered;
I'm writing a major report, and have two PDF files I'd like to include as appendices. The report is written using ReStructuredText, and rst2pdf will be used to convert it.
Does docutils or rst2pdf have any functionality for external files as appendices?
Docutils has the raw directive for passing data through to the final output untouched. In the documentation they demonstrate this for the LaTeX and HTML outputs. rst2pdf seems to support this directive: in the manual they use the raw directive to include some text/commands in the final PDF (see the section headed Raw Directive) but they do not demonstrate using this directive for including external PDF files.
If rst2pdf does support this feature, you should just be able to use:
.. raw:: pdf
:file: your_pdf_file.pdf
:encoding: the encoding of the PDF file, if different from the
reStructuredText document's encoding.
I have just had a go at doing this (if in doubt, give it a go) and I get a number of UnicodeDecodeErrors, so the feature seems to be supported but I can't get it to work.
You could embed PDFs as images, but that makes no sense for appendixes.
If you only have those files as PDF, you can add them using a PDF manipulation tool, but those usually break page numbering or links or some other piece of the PDFs.
In the end, I couldn't fix this problem directly. I converted the ReStructuredText file to Latex, and included the appendices there.