[Rd] Fwd: Bad \usage lines question

[Antti Arppe]

Thanks, that resolved it. Somehow I just thought that the line was 
truncated in the error message and that the problem was elsewhere, and 
didn't see/realize the obvious that '%' can indeed be a special 
character in Rd files.

	-Antti Arppe

On 2013-12-18 5:42 PM, Duncan Murdoch wrote:
> On 18/12/2013 12:08 PM, Antti Arppe wrote:
>> Dear colleagues,
>>
>> In checking a function I am adding to an R package, I get the following
>> warning pair:
>>
>> ...
>> Bad \usage lines found in documentation object 'nominal':
>>     "\\method{print}{nominal}"(x, max.print = 10,
>>        posthoc = "std.pearson.residuals.sign",
>>        assoc = ifelse("univariate"
>
> Notice how the line above differs from your source -- the % signs are
> taken as comment markers.  You need to escape them.
>
> Duncan Murdoch
>
>>          list(c("N", "alpha.X2", "uc.12", "uc.21")),
>>          list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>>        sort.key = NULL, ...)
>>     "\\method{summary}{nominal}"(object, posthoc =
>> "std.pearson.residuals.sign",
>>        assoc = ifelse("univariate"
>>          list(c("N", "alpha.X2", "uc.12", "uc.21")),
>>          list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>>        sort.key = NULL, ...)
>>
>> Functions with \usage entries need to have the appropriate \alias
>> entries, and all their arguments documented.
>> The \usage entries must correspond to syntactically valid R code.
>> See the chapter ‘Writing R documentation files’ in the ‘Writing R
>> Extensions’ manual.
>> ...
>>
>> The functions are described in the (same) manual page document file as
>> follows:
>>
>> ---- nominal.Rd -----
>> \name{nominal}
>> \alias{nominal}
>> \alias{print.nominal}
>> \alias{summary.nominal}
>> \alias{print.summary.nominal}
>>
>> \title{
>>     Univariate and bivariate statistics for categorical,
>>     unordered variables
>> }
>> \description{
>>
>>     \code{nominal} takes a data frame with categorical (i.e. nominal)
>>     variables and calculates a range of categorical statistics and
>>     posthoc analyses.
>>
>> }
>> \usage{
>> nominal(formula, data, sort.bivariate = NULL, std.pearson.residual.min
>> = 2,
>>      correct = FALSE, report.interval = 100, transform.variables = FALSE)
>>
>> \method{print}{nominal}(x, max.print = 10,
>>      posthoc = "std.pearson.residuals.sign",
>>      assoc = ifelse("univariate" %in% class(x),
>>        list(c("N", "alpha.X2", "uc.12", "uc.21")),
>>        list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>>      sort.key = NULL, \dots)
>>
>> \method{summary}{nominal}(object, posthoc = "std.pearson.residuals.sign",
>>      assoc = ifelse("univariate" %in% class(object),
>>        list(c("N", "alpha.X2", "uc.12", "uc.21")),
>>        list(c("N1", "N2", "N12", "uc.12", "uc.21"))),
>>      sort.key = NULL, \dots)
>>
>> \method{print}{summary.nominal}(x, max.print = 10, \dots)
>>
>> }
>> ...
>> -----
>>
>> The functions themselves are described as follows:
>>
>> ----- nominal.R -----
>> print.nominal <- function(x, max.print=10,
>> posthoc="std.pearson.residuals.sign", assoc=ifelse("univariate" %in%
>> class(x), list(c("N","alpha.X2","uc.12","uc.21")), list(c("N1","N\
>> 2","N12","uc.12","uc.21"))), sort.key=NULL, ...)
>> ...
>>
>> summary.nominal <- function(object,
>> posthoc="std.pearson.residuals.sign", assoc=ifelse("univariate" %in%
>> class(object), list(c("N","alpha.X2","uc.12","uc.21")), list(c("N1","N2"\
>> ,"N12","uc.12","uc.21"))), sort.key=NULL, ...)
>> ...
>> -----
>>
>> I've checked that the function specifications in the code match the
>> specifications in the manual page, and that all the arguments are
>> described in the manual page as well. The problem did not disappear when
>> I separated the summary method and its corresponding print method to a
>> separate file. I suppose the only difference between the code and the
>> manual pages is that in the manual pages I've tried to make the line
>> widths narrower (so there are differences in terms of space or newlines,
>> but nothing else).
>>
>> But when building the package and installing it, everything appears fine
>> within R, whether using the terminal or GUI versions.
>>
>> Am I missing something here, or what? Any suggestions or pointers will
>> be much appreciated.
>>
>> Thanks, -Antti Arppe
>>
>

-- 
======================================================================
Antti Arppe - Ph.D (General Linguistics), M.Sc. (Engineering)
Assistant Professor of Quantitative Linguistics
Department of Linguistics, University of Alberta
E-mail: arppe at ualberta.ca, antti.arppe at iki.fi
WWW: http://www.ualberta.ca/~arppe
Maanahtu ina reedûti ihza ummânuuti ihannaq - dulum ugulak úmun ingul