Escaping "@" in Roxygen2 Style Documentation

Escaping @ in Roxygen2 Style Documentation

A double at-sign @@ will do the job.

As an example, take the email address in the author field of this documentation:

##' A package to check Roxygen's sanity.
##' @name helloRoxygen-package
##' @docType package
##' @author My name \email{me@@here.org}
NA

which produces this *.Rd file when processed with roxygenize():

\docType{package}
\name{helloRoxygen-package}
\alias{helloRoxygen-package}
\title{A package to check Roxygen's sanity.}
\description{
  A package to check Roxygen's sanity.
}
\author{
  My name \email{me@here.org}
}

How to escape % in roxygen literate programming?

#!/usr/bin/perl
use strict;
use File::Temp qw/tempfile/;
use File::Copy;

my $usage = <<EOD

  $0 file1.Rd [file2.Rd ...]

  When using roxygen to generate documentation for an R pacakge, if a default
  argument has a percent sign in it then roxygen will copy it directly into
  the .Rd file. Since .Rd is basically latex, this will be interpreted as a
  comment and case the file to be parsed incorrectly.

  For percent signs elsewhere in your documentation, for example in the
  description of one of the parameters, you should use "\%" so parse_Rd
  interprets it correctly.

  But you cannot do this in the default arguments because they have to be
  valid R code, too.

  Since the .Rd files are automatically generated they should not have
  any latex comments in them anyway.

  This script escapes every unescaped % within the file.

  The .Rd files are modified in place, since it would be easy to
  generate them again with R CMD roxygen.

EOD
;

my $n_tot = 0;
my $n_file = @ARGV;
my $n_esc_file = 0;
foreach my $fn (@ARGV)  {

  print STDERR ' ' x 100, "\rWorking on $fn\t";
  open my $fh, $fn or die "Couldn't open $fn: $!";
  my ($tmp_fh, $tmp_fn) = tempfile();

  my $n;
  while(<$fh>)  {
    $n += s/(?<!\\)%/\\%/g;  # if % is not preceded with backslash then replace it with '\%'
    print $tmp_fh $_;
  }
  $n_tot += $n;
  $n_esc_file ++ if $n;
  print "Escaped $n '%'\n" if $n;
  close $tmp_fh;
  move($tmp_fn => $fn);
}

print "\n";

print "$n_file files parsed\n";
print "$n_esc_file contained at least one unescaped %\n";
print "$n_tot total % were escaped\n";

This is my inelegant solution. Save the perl script as, for example, escape_percents.pl, then the sequence would be like this:

R CMD roxygen my.package
perl escape_percents.pl my.package.roxygen/man/*.Rd
R CMD install my.package.roxygen

This may introduce more problems, for example if you have example code using %% as the modulus operator, but it has been handy for me.

Using a @ sign with roxygen2

You can escape it with another @

#' @param arg An argument that uses the symbol @@

Generate items with multiple arguments in an R documentation via roxygen2

It now seems to work with roxygen2 6.0.1:

#' @param arg1,arg2 Description

(no space after comma) gives

\arguments{
  \item{arg1, arg2}{Description}
}

(with space after comma).

How to get roxygen2 to interpret backticks as code formatting?

All credit goes to @rawr's comment to the question, just formalizing it with an answer:

The secret is in the roxygen2 documentation: just add the following to the end of the package DESCRIPTION file:

# DESCRIPTION file
# [... rest of file ...]
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2  # actually works since 6.0.0

As that code would imply, this sets roxygen2 to interpret the commands as good ol' Markdown like we're used to using here on SO and elsewhere. This also implies all the other standard Markdown commands such as **bold** and *italics*, as well as [text](http://www.url.com), code blocks defined by ```, itemized and enumerated lists, etc. It's a huge improvement across the board.

Though be careful and take a look at the documentation, since there are a few gotchas. For instance, an empty line isn't necessary to start lists, so don't start any lines with #' 1. [...] or #' * [...] or you'll accidentally create a list!). There's also a few things which don't work yet, but they're pretty minor.

How do I format roxygen2 return list similar to parameter list?

I figured it out. You need to use the tabular environment, code text formatting, and additional lines. The below code works.

#' @return A list containing:\tabular{ll}{
#'    \code{pars} \tab A numeric vector of parameter estimates \cr
#'    \tab \cr
#'    \code{std.errs} \tab A numeric vector of standard errors on parameters \cr
#'    \tab \cr
#'    \code{cov.mat} \tab Parameter covariance matrix (excluding mean) \cr
#' }

Roxygen2 documentation parameter out of order

Well, congratulate me, because I spend a good 45 minutes trying to figure this out without realizing that the parameters are ordered to sync with the function usage parameter, and r was not supposed to be there anyways.

Fix ended up being that "r" (or the parameter that "r" stands for) did not directly match any of the parameters of the function, so it got thrown to the end. I feel stupid. Whatever, though. Maybe this will be a good warning for future users.

---

Related Topics