4

Can LaTeX escapes for accents be used in Rd files? I tried the standard \'e and many variants (\'{e}, {\'e}, \\'e, \\'{e}, {\\'e}, etc.), but none is rendered as an accented character in the PDF or HTML output.

I want my References section (i.e. \references{}) to be rendered with accented characters, but I do not want to type non-ASCII characters in my Rd files. Is there good/recommended practice? Should I simply replace non-ASCII characters with their ASCII equivalents (é → e, ø → o)?

To be clear, I know it is possible to type accented characters (e.g., é) directly in UTF-8-encoded files, but I would prefer to keep ASCII-encoded files.

This question is not about:

or variants.

Minimal test package

Package structure:

test
test/man
test/man/one.Rd
test/R
test/R/one.R
test/DESCRIPTION

test/man/one.Rd:

\name{one}
\alias{one}
\title{Get One}
\description{Accents are not rendered: \'e \'{e} {\'e} \\'e \\'{e} {\\'e}}
\usage{
one()
}

test/R/one.R:

one <- function() 1

test/DESCRIPTION:

Package: test
Version: 0.1
Title: Test
Author: Nobody
Maintainer: Nobody <no@body.org>
Description: Test.
License: GPL-3

Build, check, and install with:

$ R CMD build test
$ R CMD check test_0.1.tar.gz
$ R CMD INSTALL test_0.1.tar.gz
Thomas
  • 457
  • 2
  • 12
  • I posted the question on stackoverflow.com rather than on tex.stackexchange.com because (i) the question is more about R than LaTex (i.e. `\'e` fails in Rd files but works in LaTex); (ii) a search with "Rd files" gives no relevant results on tex.stackexchange.com. – Thomas Feb 07 '22 at 15:46
  • If you encode your files in utf8, there should not be problems with sharing them between different systems. – samcarter_is_at_topanswers.xyz Feb 07 '22 at 16:19
  • @samcarter_is_at_topanswers.xyz I'm afraid there is a confusion here: I'am not talking about rmarkdown (i.e. Rmd file) but about standard documentation of R package (i.e. Rd files) build by R CMD build. – Thomas Feb 07 '22 at 16:38
  • @samcarter_is_at_topanswers.xyz No, it don't. I get `é` in the PDF output. – Thomas Feb 07 '22 at 16:44

2 Answers2

2

Rd syntax is only LaTeX-like: it supports a limited set of macros, but these are not guaranteed to behave like their LaTeX counterparts, if any exist. Conversely, very few LaTeX macros have Rd equivalents.

This section of the Writing R Extensions manual describes most of the built-in Rd macros. Tables 1, 2, and 3 of this technical paper provide a complete list.

This section of WRE addresses encoding specifically. Use of non-ASCII characters in Rd files is supported, provided that you declare an appropriate encoding, either in the files themselves (via \enc and \encoding) or in DESCRIPTION (via the Encoding field). However, restriction to ASCII characters is encouraged:

Wherever possible, avoid non-ASCII chars in Rd files, and even symbols such as ‘<’, ‘>’, ‘$’, ‘^’, ‘&’, ‘|’, ‘@’, ‘~’, and ‘*’ outside ‘verbatim’ environments (since they may disappear in fonts designed to render text).

The recommended way to obtain non-ASCII characters in rendered help without including non-ASCII characters in your Rd files is to use conditional text. \ifelse allows you to provide raw LaTeX for PDF help pages, raw HTML for HTML help pages, and verbatim text for plain text help pages:

\ifelse{latex}{\out{\'{e}}}{\ifelse{html}{\out{&eacute;}}{e}}

That is quite verbose, so I would suggest defining your own macro(s) in man/macros/macros.Rd. You can do this with \newcommand and \renewcommand:

\newcommand{\eacute}{\ifelse{latex}{\out{\'{e}}}{\ifelse{html}{\out{&eacute;}}{e}}}

Then you can use \eacute{} freely in all of your Rd files. To check that text is rendered the way you want in all formats, install the package and run help(topic, help_type=), with help_type equal to "text", "html", or "pdf".

Mikael Jagan
  • 9,012
  • 2
  • 17
  • 48
  • Thank you for your answser and the canonical references. I edited my question to precise my use case (references with non-ASCII characters). Do you have any advice/What would you do? – Thomas Feb 07 '22 at 19:48
  • 1
    If I really wanted ASCII-encoded `Rd` files, then I would use `\ifelse` to include non-ASCII characters in the rendered PDF and HTML help, as explained in my answer. – Mikael Jagan Feb 07 '22 at 20:20
  • Excellent answer, thanks again ! – Thomas Feb 07 '22 at 22:27
-1

Using math mode it works. Not sure 100% if this is what you are looking for.

Here are some examples:

  \'{e} {\'e} \\'e \\'{e} {\\'e}

$\acute{e}$

$\grave{e}$

$\tilde{e}$

PDF output:

’{e} {’e} \‘e \’{e} {\’e}
é
è
ẽ

Update:

\newcommand\latexcode[1]{#1}

\latexcode{\'{a}}

Thoma\latexcode{\'{s}}

That works Thomas !

AugtPelle
  • 549
  • 1
  • 10
  • Thank you! It seems more like a trick than a proper solution though... – Thomas Feb 07 '22 at 16:05
  • 1
    @AugtPelle The font as well as the kerning will be wrong – samcarter_is_at_topanswers.xyz Feb 07 '22 at 16:09
  • I just tested in the `test` package provided in my first post and it fails: `R CMD build` returns `Warning: /tmp/xxx/xxx/test/man/test.Rd:10: unknown macro '\acute'` and accents are not rendered in the PDF or in the HTML output (I get `$\acutee$`). Does it work in an Rd file or in a standard LaTex file for you? – Thomas Feb 07 '22 at 16:20
  • 1
    @Thomas please test my last update. Turns out there is a problem Between Latex and Rmarkdown, how the markdown engine works, passing to Latex what it recognize as Latex code. You can find more details here: https://tex.stackexchange.com/questions/541298/rmarkdown-french-accents-special-characters – AugtPelle Feb 07 '22 at 16:24
  • Thank you for your update. While the issue you linked is close, I'm afraid there is a confusion here: I'am not talking about rmarkdown (i.e. **Rmd** file) but about standard documentation of R package (i.e. **Rd** files) build by `R CMD build`. Can I really define a new command in a **Rd** file? – Thomas Feb 07 '22 at 16:36