Re: [Rd] R CMD Rdconv drops sections: arguments, seealso, examples (PR#9649)

From: Prof Brian Ripley <ripley_at_stats.ox.ac.uk>
Date: Fri, 04 May 2007 12:20:54 +0100 (BST)

On Thu, 3 May 2007, Prof Brian Ripley wrote:

> Bill,
>
> Now we have access again to the R-bugs repository (the database has been
> offline for about a week) I can try to understand this.
>
> This is a follow up to PR#9645 which was itself a follow up to PR#9606,
> which was a report that Rdconv silently drops sections it makes no sense
> of. (The latter is well known, and that's why R CMD check has an
> independent check of Rd syntax using R code.)
>
> And this supersedes the suggestion in PR#9645, both of which are that
> Rdconv should detect unclosed sections and throw an error.
>
> It is not clear to me that throwing an error is helpful as it would stop
> the package installation process when all but one section in one .Rd file
> would be useful. But it would seem good to give a warning, and so I
> propose that we adapt your code to do so.

Doing so (now in R-devel) shows a couple of false positives (\align{{} in Paren.Rd is one), and rather a lot of correct warnings about excess }s that are not doing any harm. So I have tuned the warnings to be less strident in the latter case.

> Does that reasonably reflect the various PRs?
>
> Brian
>
>
> On Tue, 1 May 2007, bill_at_insightful.com wrote:
>
>> On Mon, 30 Apr 2007 bill_at_insightful.com wrote:
>>
>>> On Tue, 10 Apr 2007 timh_at_insightful.com wrote:
>>>
>>>> I've created a .Rd file (below), then converted that to .sgml using
>>>> R CMD Rdconv --type=Ssgm combn.Rd > combn.sgml
>>>> The output (shown below) is missing some of the sections:
>>>> arguments
>>>> seealso
>>>> examples
>>>> If instead I convert to .d (below), the same sections are missing,
>>>> and the "note" section is included but without the necessary newline.
>>>
>>> The underlying problem was that there were some unmatched open-braces.
>>> (or 'brackets'?) The attached patch to share/perl/R/Rdconv.pm:mark_brackets()
>>> seems to detect unmatched open and close braces and throw an error:
>>>
>>> % R CMD INSTALL -l /tmp/Rlib timhPackage
>>> * Installing *source* package 'timhPackage' ...
>>> ** help
>>> >>> Building/Updating help pages for package 'timhPackage'
>>> Formats: text html latex example
>>> Rdconv(): mismatched braces in help file timh.Rd on or after line 12
>>> ERROR: building help failed for package 'timhPackage'
>>> ** Removing '/tmp/Rlib/timhPackage'
>>> ** Restoring previous '/tmp/Rlib/timhPackage'
>>>
>>> The code to report the line number doesn't work quite right
>>> since any "% comment" lines in the Rd file have been removed
>>> from $complete_text by the time we get here. I fudged by
>>> putting 'on or after line XXX' in the error message.
>>
>> The following patch adds a little more information (the
>> name of the \tag or whether it is an unmatched { or })
>> to the error message, so Tim's example results in
>>
>> % R CMD INSTALL -l /tmp/Rlib timhPackage
>> * Installing *source* package 'timhPackage' ...
>> ** help
>> >>> Building/Updating help pages for package 'timhPackage'
>> Formats: text html latex example
>> Rdconv(): mismatched braces ('\arguments{') in help file timh.Rd on or after line 12
>> ERROR: building help failed for package 'timhPackage'
>> ** Removing '/tmp/Rlib/timhPackage'
>> ** Restoring previous '/tmp/Rlib/timhPackage'
>>
>>
>> *** Rdconv.pm~ 2007-03-29 19:05:08.000000000 -0700
>> --- Rdconv.pm 2007-05-01 10:28:55.000000000 -0700
>> ***************
>> *** 254,259 ****
>> --- 254,275 ----
>> $complete_text =~ s/{([^{}]*)}/$id$1$id/s;
>> print STDERR "." if $debug;
>> }
>> + # Any remaining brackets must be unmatched ones, hence report error.
>> + if ($complete_text =~ /([{}])/s) {
>> + # Would like to tell which which line has unmatched { or },
>> + # but lines starting with % have already been removed.
>> + # Hence the 'on or after' in the message.
>> + my $badlineno=0 ;
>> + my $extra_info = "(\'$1\')" ;
>> + if ($complete_text =~ /(\\\w+{)/) {
>> + $extra_info = "(\'$1\')" ;
>> + }
>> + foreach my $line (split /\n/, $complete_text) {
>> + $badlineno++;
>> + last if ($line =~ /[{}]/) ;
>> + }
>> + die "Rdconv(): mismatched braces $extra_info in help file $Rdname on or after line $badlineno\n" ;
>> + }
>> }
>>
>> sub unmark_brackets {
>>
>> ______________________________________________
>> R-devel_at_r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>
>

-- 
Brian D. Ripley,                  ripley_at_stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

______________________________________________
R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Received on Fri 04 May 2007 - 11:23:23 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Mon 07 May 2007 - 20:35:36 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.