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

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.

--------------------------------------------------
\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

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