[Rd] R CMD Rdconv drops sections: arguments, seealso, examples (PR#9606)
Bill Dunlap
bill at insightful.com
Mon Apr 30 21:22:23 CEST 2007
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> – 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
More information about the R-devel
mailing list