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

[bill at insightful.com]

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 {