How to use R package exams with portuguese accents?

Question

When I'm using the package exams to generate questions, I can do it perfectly in english even with special characters. For example, a Rnw question that I can compile with exams package:

<<echo=FALSE, results=hide>>=
## DATA GENERATION
P <- round(runif(n = 1, min = 1000, max = 2000), digits = 2)
S <- round(runif(n = 1, min = P + 500, max = 3000), digits = 2)


## QUESTION/ANSWER GENERATION
i <- round((S - P)/P, digits = 2)*100
@

\begin{question}
Qual \'e a taxa de juros simples obtida por uma aplica\c{c}\~ao de \textdollar $\Sexpr{P}$ que, ap\'os um ano, produz um montante de \textdollar$\Sexpr{S}$? 

\end{question}

\begin{solution}
Os juros s\~ao calculados por:

\begin{equation}
S = P(1+i \times n) \Rightarrow S = P + Pin \Rightarrow 
\end{equation}

\begin{equation}
Pin = S - P \Rightarrow 
i = \frac{S-P}{Pn} \Rightarrow i = \frac{S-P}{P}
\end{equation}

O valor absotulo dos juros \'e $\Sexpr{i}$\%.
\end{solution}

%% META-INFORMATION
%% \extype{num}
%% \exsolution{\Sexpr{fmt(abs(tstat), 3)}}
%% \exname{t statistic}
%% \extol{0.01}

For example, when I need ç I just use \c{c} and so on. BUT, I have been trying to use Rmarkdown instead of Rnw files. And the same example in Rmd:

---
output: pdf_document
---
```{r data generation, echo = FALSE, results = "hide"}
P <- round(runif(n = 1, min = 1000, max = 2000), digits = 2)
S <- round(runif(n = 1, min = P + 500, max = 3000), digits = 2)
i <- round((S - P)/P, digits = 2)*100
```

Question
========
Qual é a taxa de juros simples obtida por uma aplicação de $`r P`

Solution
========
Os juros são calculados por:

\begin{equation}
S = P(1+i \times n) \Rightarrow S = P + Pin \Rightarrow 
\end{equation}

\begin{equation}
Pin = S - P \Rightarrow 
i = \frac{S-P}{Pn} \Rightarrow i = \frac{S-P}{P}
\end{equation}

O valor absotulo dos juros é `r i`%.

Meta-information
================
extype: num
exsolution: `r round(i, digits = 3)`
exname: Euclidean distance
extol: 0.01

I can compile with RStudio showing the accents correctly:

but when I try:

exams2pdf('file.Rmd', encoding = 'utf8')

it doen't work.

Could someone help me with this issue?

Answer 1

I tried different approaches with the arguments header and inputs of exams2pdf() but none of those gave me the correct output. Also adding LaTeX commands via the YAML header (header-includes) does not work. So I did it the "hard way":

---

Go to your R library and find the location where the package exams is saved. Inside navigate to the tex folder. There you will find the different templates used by exams. Create a copy of the default template plain.tex and call this duplicate plain_pt.tex. Inside that file you add

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage[portuguese]{babel}

to the preamble. Save the file.

The full path on my OSX machine:

 /Library/Frameworks/R.framework/Versions/3.3/Resources/library/exams/tex

In Linux can be:

~/R/x86_64-pc-linux-gnu-library/3.3/Resources/library/exams/tex

Now, when calling exams2pdf you can choose your new template with template = 'plain_pt'.

This should also work for other languages by adding the appropriate LaTeX commands.

Answer 2

Thanks to @MartinDabbelJuSmelter for his reply which essentially captures what is going on. However, there are simpler solutions for this. The easiest is:

exams2pdf("file.Rmd", encoding = "UTF-8", template = "plain8")

which leads to the desired output. Now why is this so complicated and why is it so poorly documented?

It is complicated because of the modular structure of the exams package. There are so many different ways to combine the different building blocks that something as easy as this requires two arguments. First, you have to declare that the file.Rmd is in encoding UTF-8. Second, you have to use a template that supports UTF-8. The exams package ships with a simple plain template with UTF-8 enabled.

There are not more LaTeX templates in different encodings etc. because we expected that almost all users will want to use their own custom template anyways. For example, to display the name of their university or their course or to use a particular style/font/etc.

If you only have single-choice (schoice) or multiple-choice (mchoice) questions, then there is also exams2nops which offers a standardized format where it is much simpler to use (but also with less customization). For an impression, see:

exams2nops(c("anova.Rmd", "tstat2.Rmd"),
  language = "pt", encoding = "UTF-8")

So you cannot use your num question file.Rmd for this. But the big advantage if you turned it into an schoice question would be that you get automatic scanning and evaluation for exams2nops.

So now for the Achilles heel: the poor documentation. In my defense, I have to say that in Section 2.3 (Creating the first exam) of vignette("exams2", package = "exams") the encoding issue is briefly discussed and it is recommended to look at the output of exams_skeleton() to see how this works. So in your case

exams_skeleton(markup = "markdown", encoding = "UTF-8")

should have provided some useful examples.

But arguably this ought to be easier to find. A better documentation web page for exams is high on my wish list - especially for guiding newcomers - but this summer I didn't find the necessary time. Hopefully next year...

P.S.: The following lines at the start of the Rmd file are completely unnecessary and ignored by exams:

---
output: pdf_document
---

The output into which each exercise is rendered is determined by the exams2xyz functions and not the exercise files themselves. For example:

exams2html("foo.Rmd", encoding = "UTF-8", template = "plain8")

The reason for the function (rather than the Rmd file) deciding about this is simple: Users typically want to build a large pool of questions and then might want to use the same question in a PDF file (for a written exam) or for Moodle or for live voting via ARSnova etc. If you had to modify the question pool each time for this (or keep copies) that would be rather cumbersome.