R devel - Apr 2007 - R CMD Rdconv drops sections: arguments, seealso, examples (PR#9645)

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.

I tried this on 650 packages from CRAN and didn't get any
false alarms, but I'm not convinced that none are possible.

*** R-2.5.0/share/perl/R/Rdconv.pm~	2007-03-29 19:05:08.000000000 -0700
--- R-2.5.0/share/perl/R/Rdconv.pm	2007-04-30 12:18:12.000000000 -0700
***************
*** 254,259 ****
--- 254,271 ----
  	$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 ;
+         foreach my $line (split /\n/, $complete_text) {
+             $badlineno++;
+             last if ($line =~ /[{}]/) ;
+         }
+         die "Rdconv(): mismatched braces in help file $Rdname on or after
line $badlineno\n" ;
+     }
  }

  sub unmark_brackets {
> \name{combn}
> \alias{combn}
> \title{ Generate combinations of m elements out of x }
> \description{
>   Generate all combinations of \code{m} elements out of \code{x} or
>   \code{1:n}, and optionally apply a function to each, and return
>   a list or simplify to a matrix or array.
> }
> \usage{
> combn(x, m, FUN = NULL, simplify = TRUE, ...)
> }
> \arguments{
>   \item{x}{ This is normally an integer \code{n}, in which case
>     combinations of elemnents from \code{1:n} are returned.
>     Otherwise this is a a vector, and elements of the vector are returned.
>   \item{m}{ Number of elements in each combination. }
>   \item{FUN}{ function to apply to each combination.  If \code{NULL},
>     the combinations themselves are returned, one in each column of the
>     result. }
>   \item{simplify}{ If \code{FALSE}, the results are returned as a list,
>     one combination or function value in each element.  If \code{TRUE},
>     if possible the results are simplified to a matrix or array.
>   }
>   \item{\dots}{ Optional argument to pass to \code{FUN}
>   }
> }
> \details{
>   The case where \code{FUN} is supplied are handled by calling
>   \code{\link{sapply}}, so \code{...}
>   should not include argument to \code{\link{sapply}} -- in particular
avoid
>     \code{X} and \code{FUN}.
> }
> \value{
>   Normally, a matrix with \code{m} rows and \code{choose(n,m)} columns.
>   If \code{simplify=FALSE} a list is returned instead, with
>   \code{choose(n,m)} elements.  If \code{FUN} is supplied then the
>   results of calling the function replace the combinations.
> }
> \note{This is similar to the R function \code{combn}.  However,
>   this version returns a list if simplification is not possible, e.g.
>   because the \code{FUN} returns objects with varying lengths.
> }
> \seealso{ \code{\link{combinations}} is used to create the combinations.
>   It is faster to call function directly (note that it gives the
combinations
>   in a different order).
>   \code{\link{sapply}} is used when \code{FUN} is supplied.
> \examples{
> combn(5, 3)
> combinations(5, 3)
> combn(letters[1:5], 3)
> combn(5, 3, simplify = FALSE)
> combn(5, 3, FUN = max)
> \keyword{ math }
>
> --------------------------------------------------
> <!doctype s-function-doc system "s-function-doc.dtd" [
> <!entity % S-OLD "INCLUDE">
> ]
> >
> <s-function-doc>
> <s-topics>
>   <s-topic>combn</s-topic>
> </s-topics>
>
> <s-title>
> Generate combinations of m elements out of x
> </s-title>
>
> <s-description>
> Generate all combinations of <code>m</code> elements out of
<code>x</code> or
> <code>1:n</code>, and optionally apply a function to each, and
return
> a list or simplify to a matrix or array.
> </s-description>
>
> <s-usage>
> <s-old-style-usage>
> combn(x, m, FUN = NULL, simplify = TRUE, ...)
> </s-old-style-usage>
> </s-usage>
>
> <s-details>
> The case where <code>FUN</code> is supplied are handled by
calling
> <s-function name="sapply">sapply</s-function>, so
<code>...</code>
> should not include argument to <s-function
name="sapply">sapply</s-function> &ndash; in particular
avoid
> <code>X</code> and <code>FUN</code>.
> </s-details>
>
> <s-value>
> Normally, a matrix with <code>m</code> rows and
<code>choose(n,m)</code> columns.
> If <code>simplify=FALSE</code> a list is returned instead, with
> <code>choose(n,m)</code> elements.  If
<code>FUN</code> is supplied then the
> results of calling the function replace the combinations.
> </s-value>
>
> <s-section name="NOTE">
> This is similar to the R function <code>combn</code>.  However,
> this version returns a list if simplification is not possible, e.g.
> because the <code>FUN</code> returns objects with varying
lengths.
> </s-section>
>
> <s-keywords>
> <s-keyword>math</s-keyword>
> </s-keywords>
> <s-docclass>
> function
> </s-docclass>
> </s-function-doc>
>
> --------------------------------------------------
> .\" -*- nroff -*- generated from .Rd format
> .de PF
> ,br
> .ne 2
> .ft 3
> .nf
> ..
> .de FP
> .br
> .ne 2
> .ft 1
> .fi
> ..
> .BG
> .FN combn
> .TL
> Generate combinations of m elements out of x
> .DN
> Generate all combinations of 'm' elements out of 'x' or
> '1:n', and optionally apply a function to each, and return
> a list or simplify to a matrix or array.
> .CS
>
> combn(x, m, FUN = NULL, simplify = TRUE, ...)
>
> .RT
> Normally, a matrix with 'm' rows and 'choose(n,m)' columns.
> If 'simplify=FALSE' a list is returned instead, with
> 'choose(n,m)' elements.  If 'FUN' is supplied then the
> results of calling the function replace the combinations.
> .DT
> The case where 'FUN' is supplied are handled by calling
> 'sapply', so '\&...'
> should not include argument to 'sapply' - in particular avoid
> 'X' and 'FUN'.Note
> This is similar to the R function 'combn'.  However,
> this version returns a list if simplification is not possible, e.g.
> because the 'FUN' returns objects with varying lengths.
>
> .KW math
> .WR
>
>
>
>
>
>
> --please do not edit the information below--
>
> Version:
>  platform = i686-pc-linux-gnu
>  arch = i686
>  os = linux-gnu
>  system = i686, linux-gnu
>  status >  major = 2
>  minor = 4.1
>  year = 2006
>  month = 12
>  day = 18
>  svn rev = 40228
>  language = R
>  version.string = R version 2.4.1 (2006-12-18)
>
> Locale:
>
LC_CTYPE=en_US.UTF-8;LC_NUMERIC=C;LC_TIME=en_US.UTF-8;LC_COLLATE=en_US.UTF-8;LC_MONETARY=en_US.UTF-8;LC_MESSAGES=en_US.UTF-8;LC_PAPER=en_US.UTF-8;LC_NAME=C;LC_ADDRESS=C;LC_TELEPHONE=C;LC_MEASUREMENT=en_US.UTF-8;LC_IDENTIFICATION=C
>
> Search Path:
>  .GlobalEnv, package:combinat, package:stats, package:graphics,
package:grDevices, package:utils, package:datasets, package:methods, Autoloads,
package:base
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

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 {