[R-SIG-Mac] manpage problem

[joerg van den hoff]

thanks for replying.

On Fri, 09 Apr 2010 07:49:05 +0200, Prof Brian Ripley  
<ripley at stats.ox.ac.uk> wrote:

> On Wed, 7 Apr 2010, joerg van den hoff wrote:
>
>> not sure whether this is MAC specific:
>
> Why do you suppose it would be?
>
>> I use \itemize or \enumerate in some manpages. it worked previously,  
>> but I'm not sure up till when...
>> now (with 2.10.1) I see the following:
>>
>> -- using the R-GUI manpages are displayed correctly
>
> with HTML help, the default, I guess.
>
>> -- in the Terminal.app (or xterm) only the bullet points (or  
>> enumerating numbers) are displayed, but the actual description
>>  for the item is missing.
>
> with text help (the default), I guess.
>
>> any ideas?
>
> RTFM time: your help (sic) pages are incorrect.  That is not how \item  
> works in those environments, and the braces are incorrect.
> For an example of the correct layout, see src/library/base/man/dcf.Rd in  
> the R sources.

that (the RTFM part) I did (before mailing, btw). RTFSC on the other hand  
would be a bit
of a tough advice -- at least as a default strategy.

AFAICS the correct \item syntax is not explained in the corresponding
section 2.4 (or any other) of the 'writing r extensions' manual. in  
retrospect one could possibly _guess_  that 'the text following
each \item is formatted...' implies that there should be no braces. so I  
wrongly assumed from the common usage of \item
(in \arguments) that braces are needed.

I would say this lack of specificity is a shortcoming of the manual which  
would profit from changing this section accordingly.

last remark: the parsers/converters to html and txt behave differently. in  
my view, the behaviour of the html converter (ignoring
the redundant/wrong braces) is more desirable. in any case they should not  
have different opinions how to interpret the help page
(your usage of `(sic)' is wrong/non-standard, btw...) source. (and the  
behaviour has changed from 2.9.x to 2.10.1: previously
the text output preserved the braced \item arguments, also the formatting  
is messed up (as I just checked on a linux machine)).

regards,

j. van den hoff

>
>>
>> thanks
>>
>> joerg
>>
>> ps: macos 10.5.8 ppc
>> pps: in case, the problem is my manpage, the source code of this  
>> (rudimentary) manpage is:
>>
>> \name{metacor}
>> \alias{metacor}
>> \title{
>> Perform metabolite correction
>> }
>> \description{
>> Computes metabolite corrected input function from whole blood data plus
>> time dependent metabolite fraction
>> }
>> \usage{
>> metacor(input, metfrac = 0)
>> }
>> \arguments{
>> \item{input}{
>> measured input function (class \code{Roidata})
>> }
>> \item{metfrac}{
>> metabolite fraction
>> }
>> }
>> \details{
>> The metabolite fraction has to be in one of the following formats.
>>
>>  \enumerate{
>>     \item{a single number}
>>     \item{a vector of metabolite fractions corresponding one-to-one to  
>> the
>>        time points in input}
>>     \item{a two column matrix (time vs. metab. fraction) where time  
>> units
>>        have to be the same as those used in input}
>>     \item{a Roidata object including timing information}
>>  }
>> }
>> \value{
>> metabolite corrected input function (\code{Roidata} object)
>> }
>> \author{
>> vdh
>> }
>> \seealso{
>> \code{readroi}
>> }
>> \keyword{ utilities }
>>
>> _______________________________________________
>> R-SIG-Mac mailing list
>> R-SIG-Mac at stat.math.ethz.ch
>> https://stat.ethz.ch/mailman/listinfo/r-sig-mac
>