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

From: Bill Dunlap <bill_at_insightful.com>
Date: Mon, 30 Apr 2007 12:22:23 -0700 (PDT)

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

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.

  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


R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Mon 30 Apr 2007 - 21:53:17 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 30 Apr 2007 - 22:32:51 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.