[Rd] Problems with R CMD Rdconv and R CMD Sd2Rd (PR#8661)

[timh@insightful.com]

I'm using R 2.2.0 on Windows.
Doing some conversions of help files.  Internal comments indicate
that the Sd2Rd conversion is "Converted by Sd2Rd version 1.21."

I'm converting 
	.d -> .Rd	
	.sgml -> .Rd
using Sd2Rd, then checking by using Rdconv to
convert .Rd back to .d or .sgml.

Here are errors in some of the conversions.
The most significant errors are in .Rd to .sgml.
The largest number of errors are in .Rd to .d (however,
this conversion is not so important).

--------------------------------------------------
	.Rd to .sgml
	R CMD Rdconv -t Ssgm file.Rd > file.sgml

If the .Rd contains
\section{title}{text}
the section is missing completely from the sgml file.
(I reported this separately; it works fine when converting to .d)


Similarly, \keyword{lars}
is missing completely from the sgml file
(It works fine when converting to .d)



Rd converts \$ to \$; it should be just $.  This in .Rd

\code{.Machine\$double.eps},

is converted to

<s-expression>.Machine\$double.eps</s-expression>,

It should be

<s-expression>.Machine$double.eps</s-expression>,

or better yet

<code>.Machine$double.eps</code>,



In \examples{}, 
	<
should be converted verbatim rather than converted to 
	&lt;


In the References section (and for links more generally?), file
names are missing the .sgm
This:

\seealso{
\code{\link{lm}}
\code{\link{lsfit}}
}

is converted to:

<s-see>
<s-function name="lm">lm</s-function>
<s-function name="lsfit">lsfit</s-function>
</s-see>

It should be

<s-see>
<s-function name="lm.sgm">lm</s-function>
<s-function name="lsfit.sgm">lsfit</s-function>
</s-see>




--------------------------------------------------
	.sgml to .Rd
	R CMD Sd2Rd file.sgml > file.Rd

This

<descrip>
<tag> lar </tag>
least-angle regression
<tag> lasso </tag>
lasso method
<tag> stepwise </tag>
forward stepwise regression
</descrip>

is put verbatim into the .Rd
It should be converted into a \describe list




A references section should be converted to \references, not 
\section{References}.  This

<s-section name = "REFERENCES">
Efron, ...
</s-section>

is converted to

\section{References}{
Efron, ...
}

it should be 

\references{
Efron, ...
}




--------------------------------------------------
	.Rd to .d
	R CMD Rdconv -t Sd file.Rd > file.d

It converts
	\code{lars}
to
	'lars'
It should be
	`lars'


It converts (in argument list)
\item{...}{

to
.AG \&...

should be
.AG ...


Converts:
\section{Side Effects}{
A plot is produced
}

to:
.SH Side Effects
A plot is produced

should be
.SE
A plot is produced


Converts
\emph{Annals of Statistics}
\bold{32}, 407--451.

to:
_Annals of Statistics_
*32*, 407-451.

Should be:
.ul
Annals of Statistics
\fB32\fP, 407-451.


Sd2Rd converts
	.PP in a .d file within the arguments section 
to
	two blank lines in .Rd; 
Rdconv converts that to
	.IP "" 
whereas 
	.PP
would be better.


Rdconv loses comments.


This:
\value{
...
the same order of computational cost as a least squares fit.
}
\references{

is converted to (missing a newline):

the same order of computational cost as a least squares fit..SH REFERENCES


This
\name{lars.object}
\alias{lars.object}
\alias{class.lars}

is converted to
.FN lars.object

should be:
.FN lars.object
.FN class.lars


The document "Writing R Extensions" manual, chapter on
"Writing R documentation files" is silent about how to document S3 classes.
(It does mention S4 classes)


--------------------------------------------------
	.d to .Rd
	R CMD Sd2Rd file.d > file.Rd


A very common error when writing a .d file is to use .AG where you
should use .RC, in the .RT section, e.g.

.RT
Invisibly returns a list with components:
.AG fraction
See above
.AG cv
The CV curve at each value of fraction

Right now the converter is moving those into the "Arguments" section,
rather than leaving them in the "Value" section.  It would be nice
if they were left in the Value section.






--please do not edit the information below--

Version:
 platform = i386-pc-mingw32
 arch = i386
 os = mingw32
 system = i386, mingw32
 status = 
 major = 2
 minor = 2.0
 year = 2005
 month = 10
 day = 06
 svn rev = 35749
 language = R

Windows XP Professional (build 2600) Service Pack 2.0

Locale:
LC_COLLATE=English_United States.1252;LC_CTYPE=English_United States.1252;LC_MONETARY=English_United States.1252;LC_NUMERIC=C;LC_TIME=English_United States.1252

Search Path:
 .GlobalEnv, package:methods, package:stats, package:graphics, package:grDevices, package:utils, package:datasets, Autoloads, package:base