Wie% in roxygen Literarischer Programmierung zu entkommen?

Question

Der Standardwert eines Parameters meiner Funktion enthält eine „%“. Dies scheint ein Problem für roxygen zu sein, erzeugt es eine Menge Warnungen und R CMD Prüfung fehlschlägt, wenn zu bauen Latex Dokumentation versucht.

Wie kann ich diese Funktion machen (und deren Dokumentation) Arbeit? Mit %% oder \% anstatt% nicht hilft.

#' Test escape \% from in-source documentation (roxygen).
#'
#' What happens when parameters contain special latex characters? 
#'
#' @param x unsuspicious parameter 
#' @param format sprintf format string (default "\%5.0f")
#'
#' @return formatted string
#' @export
#' @author Karsten Weinert
testroxy <- function(x, format = "%5.0f") {
  sprintf(format,x)
}

Answer 1

#!/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";

Das ist meine unelegant Lösung. Speichern Sie den Perl-Skript, wie zum Beispiel escape_percents.pl, dann ist die Sequenz so sein würde:

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

Dies kann mehr Probleme vorstellen, zum Beispiel, wenn Sie Beispielcode mit %% als Modulo-Operator, aber es hat sich für mich praktisch gewesen.

Answer 2

-Code, ähnlich der in der Frage arbeitet für mich ohne ein Problem und erzeugt die richtige Dokumentation. Da mehrere Kommentare sagen, muss der Grund sein, dass ich das roxygen2 Paket verwenden. Also nur roxygen2 verwenden und dann entkommen „%“ in der Dokumentation mit Backslash:

#' The percentage sign is written in the documentation like this: \%.