[Rd] why is \alias{anRpackage} not mandatory?
Dear R developers,
if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page, so:
?anRpackage
gives new users of a certain package a pointer where to start reading.
This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages which
don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-package,
e.g. `utils-package' for the utils package, when package?pkgname will
open that help page. If a topic named pkgname does not exist in another
Rd file, it is helpful to use this as an additional \alias."
My question: what speaks against making this sentence more pronounced
and why not NOTE-ing a missing package alias in the package check?
Thomas Petzoldt
--
Thomas Petzoldt
Technische Universitaet Dresden
Institut fuer Hydrobiologie
01062 Dresden
GERMANY
http://tu-dresden.de/Members/thomas.petzoldt
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page, so:
?anRpackage
gives new users of a certain package a pointer where to start reading.
This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages
which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias
pkgname-package, e.g. `utils-package' for the utils package, when
package?pkgname will open that help page. If a topic named pkgname
does not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more pronounced
and why not NOTE-ing a missing package alias in the package check?
Not everybody likes the idea of the overview man page, so when I wrote
that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract, why not
requesting one for software packages, at least for new ones?
- there are lots of packages without one, so this would create a lot of
work for people to add them.
No, I don't think that this is too much work. Positively speaking, it's
one small contribution to bring more light into the exponentially
growing haystack.
What about starting to advertise the use of \alias{anRpackage}, i.e. a
short article in R News and subsequently an email to the developers.
- the ones that do exist tend to include outdated information. People
update the DESCRIPTION file but forget to update the corresponding
information in the overview.
This is in fact a problem. Suggestions:
- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION and
possibly also from other resources.
- in general there's a lot of dissatisfaction with the Rd format, so
there's reluctance to invest any more effort in it.
You are right, .Rd has its limitations, but as you say, there is nothing
better available in the moment. (BTW: I heard rumours at useR! about
discussions on a meta documentation format? Is there any public
information about this??)
It would probably be a good idea to generate one automatically if not
provided by the author, at build or install time: this would address
the first point.
A reasonable idea -- at least if combined with a motivating request to
package authors to provide an own one.
I've been slowly working on some fixes that address
the second point. (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.) There's no
way to address the third point other than providing a better format, and
I don't see any prospect of that happening.
So if there are no advances in that direction I see no other choice than
using the existing mechanisms! Recently, I had several contacts with
package authors who were not even aware about the possibility of
providing a package information .Rd file.
Duncan Murdoch
Thanks, Thomas P.
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page, so:
?anRpackage
gives new users of a certain package a pointer where to start reading.
This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages which
don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-package,
e.g. `utils-package' for the utils package, when package?pkgname will
open that help page. If a topic named pkgname does not exist in another
Rd file, it is helpful to use this as an additional \alias."
My question: what speaks against making this sentence more pronounced
and why not NOTE-ing a missing package alias in the package check?
Not everybody likes the idea of the overview man page, so when I wrote
that I left it weak. Some of the disadvantages:
- there are lots of packages without one, so this would create a lot of
work for people to add them.
- the ones that do exist tend to include outdated information. People
update the DESCRIPTION file but forget to update the corresponding
information in the overview.
- in general there's a lot of dissatisfaction with the Rd format, so
there's reluctance to invest any more effort in it.
It would probably be a good idea to generate one automatically if not
provided by the author, at build or install time: this would address
the first point. I've been slowly working on some fixes that address
the second point. (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.) There's no
way to address the third point other than providing a better format, and
I don't see any prospect of that happening.
Duncan Murdoch
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page, so:
?anRpackage
gives new users of a certain package a pointer where to start reading.
This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages
which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias
pkgname-package, e.g. `utils-package' for the utils package, when
package?pkgname will open that help page. If a topic named pkgname
does not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more pronounced
and why not NOTE-ing a missing package alias in the package check?
Not everybody likes the idea of the overview man page, so when I wrote
that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract, why not
requesting one for software packages, at least for new ones?
We already require one in the DESCRIPTION file for all packages, which
you can see with
library(help=packagename)
This is related to my first two points: people have already done this
work so they are reluctant to do it again, and duplicate information is
a bad idea.
I think the R help system is too fragmented: it's hard to discover all
the different types of help that are already there (Rd files,
DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES, ChangeLogs,
SVN logs, source comments, mailing lists, web pages and publications,
...). I think having a ?packagename man page is a good place for a
single starting point, and I consider packages without one to be poorly
documented. But obviously, not everyone agrees.
- there are lots of packages without one, so this would create a lot of
work for people to add them.
No, I don't think that this is too much work. Positively speaking, it's
one small contribution to bring more light into the exponentially
growing haystack.
I agree, and I even added these to all the packages under my control:
but there are hundreds of package authors, and some have different
priorities than you and me.
What about starting to advertise the use of \alias{anRpackage}, i.e. a
short article in R News and subsequently an email to the developers.
I would have thought that putting this into NEWS and Writing R
Extensions was the right way to advertise it. If people don't read
those, why would you think they'll read R News? But more is better, so
go ahead and submit an article to R News.
I don't like robot mailings, so I wouldn't appreciate an email on this.
I don't recommend that you send one.
- the ones that do exist tend to include outdated information. People
update the DESCRIPTION file but forget to update the corresponding
information in the overview.
This is in fact a problem. Suggestions:
- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION and
possibly also from other resources.
- in general there's a lot of dissatisfaction with the Rd format, so
there's reluctance to invest any more effort in it.
You are right, .Rd has its limitations, but as you say, there is nothing
better available in the moment. (BTW: I heard rumours at useR! about
discussions on a meta documentation format? Is there any public
information about this??)
I first heard proposals for a replacement format at DSC 2001. I don't
know of anything concrete.
Duncan Murdoch
It would probably be a good idea to generate one automatically if not
provided by the author, at build or install time: this would address
the first point.
A reasonable idea -- at least if combined with a motivating request to
package authors to provide an own one.
I've been slowly working on some fixes that address
the second point. (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.) There's no
way to address the third point other than providing a better format, and
I don't see any prospect of that happening.
So if there are no advances in that direction I see no other choice than
using the existing mechanisms! Recently, I had several contacts with
package authors who were not even aware about the possibility of
providing a package information .Rd file.
Duncan Murdoch
Re: [Rd] why is \alias{anRpackage} not mandatory?
>> - there are lots of packages without one, so this would create a lot of >> work for people to add them. > > No, I don't think that this is too much work. Positively speaking, it's one > small contribution to bring more light into the exponentially growing > haystack. It may not be much work for you, but I find any additional requirements to the package format to be a real pain. I have ~10 packages on CRAN and having to go through and add this extra information all at once is a big hassle. R releases tend to happen in the middle of the US academic semester when I have a lot of other things on my plate. Additionally, I find that rdoc is the wrong format for lengthy explanation and exposition - a pdf is much better - and I think that the packages already have a abstract: the description field in DESCRIPTION. The main problem with vignettes at the moment is that they must be sweave, a format which I don't really like. I wish I could supply my own pdf + R code file produced using whatever tools I choose. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
> You are right, .Rd has its limitations, but as you say, there is nothing > better available in the moment. (BTW: I heard rumours at useR! about > discussions on a meta documentation format? Is there any public information > about this??) What do you mean by meta documentation format? Do you mean roxygen - http://cran.r-project.org/web/packages/roxygen ? Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
Duncan Murdoch wrote:
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a file
anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page, so:
?anRpackage
gives new users of a certain package a pointer where to start reading.
This is similar for packages which have the same name as their main
workhorse function, e.g. zoo or nlme, but there are many packages
which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias
pkgname-package, e.g. `utils-package' for the utils package, when
package?pkgname will open that help page. If a topic named pkgname
does not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more
pronounced and why not NOTE-ing a missing package alias in the
package check?
Not everybody likes the idea of the overview man page, so when I
wrote that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract, why
not requesting one for software packages, at least for new ones?
We already require one in the DESCRIPTION file for all packages, which
you can see with
library(help=packagename)
This is related to my first two points: people have already done this
work so they are reluctant to do it again, and duplicate information is
a bad idea.
I agree, and I also don't like duplicate inconsistent "information", but
simply try the following:
options(htmlhelp=TRUE)
library(help="base")
The result is now displayed in text format and new users don't know how
to proceed. I say new users, because an experienced user knows what to
do ... and if nothing helps he makes a grep over the sources.
I think the R help system is too fragmented: it's hard to discover all
the different types of help that are already there (Rd files,
DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES, ChangeLogs,
SVN logs, source comments, mailing lists, web pages and publications,
...). I think having a ?packagename man page is a good place for a
single starting point, and I consider packages without one to be poorly
documented. But obviously, not everyone agrees.
*I* agree -- completely with the that paragraph.
- there are lots of packages without one, so this would create a lot
of work for people to add them.
No, I don't think that this is too much work. Positively speaking,
it's one small contribution to bring more light into the exponentially
growing haystack.
I agree, and I even added these to all the packages under my control:
but there are hundreds of package authors, and some have different
priorities than you and me.
O.K., I see, so I suggest to add an additional motivating sentence to:
http://developer.r-project.org/Rds.html
and possibly an automatism that shows (or converts) the output of
library(help="foo")
to a formatted page in the appropriate help format (e.g. html).
What about starting to advertise the use of \alias{anRpackage}, i.e. a
short article in R News and subsequently an email to the developers.
I would have thought that putting this into NEWS and Writing R
Extensions was the right way to advertise it. If people don't read
those, why would you think they'll read R News? But more is better, so
go ahead and submit an article to R News.
People like me may read "Writing R Extensions" several times and then
have a look into some of the most prominent packages and get insecure,
as only few use this mechanism.
I don't like robot mailings, so I wouldn't appreciate an email on this.
I don't recommend that you send one.
Beware, not at all! But I think it was good to open this thread on
r-devel :-)
- the ones that do exist tend to include outdated information.
People update the DESCRIPTION file but forget to update the
corresponding information in the overview.
This is in fact a problem. Suggestions:
- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION and
possibly also from other resources.
- in general there's a lot of dissatisfaction with the Rd format, so
there's reluctance to invest any more effort in it.
You are right, .Rd has its limitations, but as you say, there is
nothing better available in the moment. (BTW: I heard rumours at useR!
about discussions on a meta documentation format? Is there any public
information about this??)
I first heard proposals fo
Re: [Rd] why is \alias{anRpackage} not mandatory?
Dear Hadley, thank you very much for your comments. hadley wickham wrote: - there are lots of packages without one, so this would create a lot of work for people to add them. No, I don't think that this is too much work. Positively speaking, it's one small contribution to bring more light into the exponentially growing haystack. It may not be much work for you, but I find any additional requirements to the package format to be a real pain. I have ~10 packages on CRAN and having to go through and add this extra information all at once is a big hassle. R releases tend to happen in the middle of the US academic semester when I have a lot of other things on my plate. O.K., but the discussion with Duncan shows: - the required information is already available (in DESCRIPTION), - one can think about ways to generate the page automatically for existing packages, - the intro can be short and should link to other pages or PDFs, - one should avoid doubling and inconsistency. Additionally, I find that rdoc is the wrong format for lengthy explanation and exposition - a pdf is much better - and I think that the packages already have a abstract: the description field in DESCRIPTION. o.k., but abstract may be (technically) in the wrong format and does not point to the other relevant parts of the package documentation. The main problem with vignettes at the moment is that they must be sweave, a format which I don't really like. I wish I could supply my own pdf + R code file produced using whatever tools I choose. > Hadley I like Sweave, and it is also possible to include your own PDFs and R files and then to reference them in anRpackage.Rd. Thomas P. __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
>> It may not be much work for you, but I find any additional >> requirements to the package format to be a real pain. I have ~10 >> packages on CRAN and having to go through and add this extra >> information all at once is a big hassle. R releases tend to happen in >> the middle of the US academic semester when I have a lot of other >> things on my plate. > > O.K., but the discussion with Duncan shows: > > - the required information is already available (in DESCRIPTION), > - one can think about ways to generate the page automatically for existing > packages, > - the intro can be short and should link to other pages or PDFs, > - one should avoid doubling and inconsistency. I'm obviously not going to object if it's done automatically, and I already strive to avoid doubling and inconsistency by producing most my documentation algorithmically. I think you are being cavalier by not caring about the extra work you want package authors to do. >> Additionally, I find that rdoc is the wrong format for lengthy >> explanation and exposition - a pdf is much better - and I think that >> the packages already have a abstract: the description field in >> DESCRIPTION. > > o.k., but abstract may be (technically) in the wrong format and does not > point to the other relevant parts of the package documentation. Then I don't think you should call what you want an abstract. >> The main problem with vignettes at the moment is that >> they must be sweave, a format which I don't really like. I wish I >> could supply my own pdf + R code file produced using whatever tools I >> choose. > > I like Sweave, and it is also possible to include your own PDFs and R files > and then to reference them in anRpackage.Rd. Yes, but they're not vignettes - which means they're not listed under vignette() and it's yet another place for people to look for documentation. Hadley -- http://had.co.nz/ __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
On 10/6/2008 9:55 AM, hadley wickham wrote: It may not be much work for you, but I find any additional requirements to the package format to be a real pain. I have ~10 packages on CRAN and having to go through and add this extra information all at once is a big hassle. R releases tend to happen in the middle of the US academic semester when I have a lot of other things on my plate. O.K., but the discussion with Duncan shows: - the required information is already available (in DESCRIPTION), - one can think about ways to generate the page automatically for existing packages, - the intro can be short and should link to other pages or PDFs, - one should avoid doubling and inconsistency. I'm obviously not going to object if it's done automatically, and I already strive to avoid doubling and inconsistency by producing most my documentation algorithmically. I think you are being cavalier by not caring about the extra work you want package authors to do. Additionally, I find that rdoc is the wrong format for lengthy explanation and exposition - a pdf is much better - and I think that the packages already have a abstract: the description field in DESCRIPTION. o.k., but abstract may be (technically) in the wrong format and does not point to the other relevant parts of the package documentation. Then I don't think you should call what you want an abstract. The main problem with vignettes at the moment is that they must be sweave, a format which I don't really like. I wish I could supply my own pdf + R code file produced using whatever tools I choose. I like Sweave, and it is also possible to include your own PDFs and R files and then to reference them in anRpackage.Rd. Yes, but they're not vignettes - which means they're not listed under vignette() and it's yet another place for people to look for documentation. Vignettes have R code in them and a way to extract it, so it's misleading to call something that's just a .pdf file a vignette. But I imagine there could be other ways to mix R code with documentation besides the existing Sweave formats. The most obvious way to add another one is to write another Sweave driver. I think it would require changes to the base of R to allow for Sweave drivers in packages, working with files that don't have extensions (R|r|S|s)(nw|tex), but in principle I don't see any real objection to adding that. Duncan Murdoch __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] why is \alias{anRpackage} not mandatory?
hadley wickham wrote:
It may not be much work for you, but I find any additional
requirements to the package format to be a real pain. I have ~10
packages on CRAN and having to go through and add this extra
information all at once is a big hassle. R releases tend to happen in
the middle of the US academic semester when I have a lot of other
things on my plate.
O.K., but the discussion with Duncan shows:
- the required information is already available (in DESCRIPTION),
- one can think about ways to generate the page automatically for existing
packages,
- the intro can be short and should link to other pages or PDFs,
- one should avoid doubling and inconsistency.
I'm obviously not going to object if it's done automatically, and I
already strive to avoid doubling and inconsistency by producing most
my documentation algorithmically. I think you are being cavalier by
not caring about the extra work you want package authors to do.
Sorry if my question was misunderstood this way, but I have not
requested additional work, I simply asked "why is \alias{anRpackage} not
mandatory?"
The answer was, that they are problems with inconsistencies that can be
technically solved and that it may be too much work for some package
authors with lots of packages (can also be solved with technical means),
but that other users and developers would enjoy it to have such a
starting point.
O.K., I agree that the suggestion of NOTE-ing a missing
\alias{anRpackage} during package check was a bad idea (currently ;-),
but that one can think about a combination of a technical means and an
optional entry, analogously to the CITATION file.
Additionally, I find that rdoc is the wrong format for lengthy
explanation and exposition - a pdf is much better - and I think that
the packages already have a abstract: the description field in
DESCRIPTION.
o.k., but abstract may be (technically) in the wrong format and does not
point to the other relevant parts of the package documentation.
Then I don't think you should call what you want an abstract.
Some sort of abstract, overview or, more precise, an *entry point*.
The main problem with vignettes at the moment is that
they must be sweave, a format which I don't really like. I wish I
could supply my own pdf + R code file produced using whatever tools I
choose.
I like Sweave, and it is also possible to include your own PDFs and R files
and then to reference them in anRpackage.Rd.
Yes, but they're not vignettes - which means they're not listed under
vignette() and it's yet another place for people to look for
documentation.
You are right, they are not vignettes in the strict sense, but they can
be listed in the help index of the package, the place where the majority
of "normal R users" starts to look.
ThPe
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] Bug with message if there is no documentation; R2.8alpha Win32 (PR#13131)
In the latest R 2.8 alpha for Win32, if either of the commands are typed:
> help("erfc")
.. or ..
> ?erfc
the result is:
No documentation for 'erfc' in specified packages and libraries:
you could try '??erfc'
This should be: 'help.search("erfc")', as shown in R 2.7.2
Apologies if this has already been submitted/fixed.
-Mike
--please do not edit the information below--
Version:
platform = i386-pc-mingw32
arch = i386
os = mingw32
system = i386, mingw32
status = alpha
major = 2
minor = 8.0
year = 2008
month = 10
day = 03
svn rev = 46594
language = R
version.string = R version 2.8.0 alpha (2008-10-03 r46594)
Windows XP (build 2600) Service Pack 3
Locale:
LC_COLLATE=English_Canada.1252;LC_CTYPE=English_Canada.1252;LC_MONETARY=English_Canada.1252;LC_NUMERIC=C;LC_TIME=English_Canada.1252
Search Path:
.GlobalEnv, package:stats, package:graphics, package:grDevices,
package:utils, package:datasets, package:methods, Autoloads, package:base
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]
On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a
file anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page,
so:
?anRpackage
gives new users of a certain package a pointer where to start
reading.
This is similar for packages which have the same name as their
main workhorse function, e.g. zoo or nlme, but there are many
packages which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-
package, e.g. `utils-package' for the utils package, when package?
pkgname will open that help page. If a topic named pkgname does
not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more
pronounced and why not NOTE-ing a missing package alias in the
package check?
Not everybody likes the idea of the overview man page, so when I
wrote that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract,
why not requesting one for software packages, at least for new ones?
We already require one in the DESCRIPTION file for all packages,
which you can see with
library(help=packagename)
Yes, but this is way too long to write - could we add a fall-back so
that if ?foo alias doesn't exist but package foo does then ?foo is
equivalent to help(package="foo")? At least for the way I use help it
would help a lot...
Cheers,
S
This is related to my first two points: people have already done
this work so they are reluctant to do it again, and duplicate
information is a bad idea.
I think the R help system is too fragmented: it's hard to discover
all the different types of help that are already there (Rd files,
DESCRIPTION files, vignettes, the manuals, NEWS, CHANGES,
ChangeLogs, SVN logs, source comments, mailing lists, web pages and
publications, ...). I think having a ?packagename man page is a
good place for a single starting point, and I consider packages
without one to be poorly documented. But obviously, not everyone
agrees.
- there are lots of packages without one, so this would create a
lot of work for people to add them.
No, I don't think that this is too much work. Positively speaking,
it's one small contribution to bring more light into the
exponentially growing haystack.
I agree, and I even added these to all the packages under my
control: but there are hundreds of package authors, and some have
different priorities than you and me.
What about starting to advertise the use of \alias{anRpackage},
i.e. a short article in R News and subsequently an email to the
developers.
I would have thought that putting this into NEWS and Writing R
Extensions was the right way to advertise it. If people don't read
those, why would you think they'll read R News? But more is better,
so go ahead and submit an article to R News.
I don't like robot mailings, so I wouldn't appreciate an email on
this. I don't recommend that you send one.
- the ones that do exist tend to include outdated information.
People update the DESCRIPTION file but forget to update the
corresponding information in the overview.
This is in fact a problem. Suggestions:
- propose basic style guidelines (in an R-News article)
- allow variables in .Rd files (your idea to allow "Sweave like
constructs" may be even better). In addition to entries from
DESCRIPTION, one can think also about importing data from CITATION
and possibly also from other resources.
- in general there's a lot of dissatisfaction with the Rd format,
so there's reluctance to invest any more effort in it.
You are right, .Rd has its limitations, but as you say, there is
nothing better available in the moment. (BTW: I heard rumours at
useR! about discussions on a meta documentation format? Is there
any public information about this??)
I first heard proposals for a replacement format at DSC 2001. I
don't know of anything concrete.
Duncan Murdoch
It would probably be a good idea to generate one automatically if
not provided by the author, at build or install time: this would
address the first point.
A reasonable idea -- at least if combined with a motivating request
to package authors to provide an own one.
I've been slowly working on some fixes that address the second
point. (The current idea is to use Sweave-like constructs to
import things from the DESCRIPTION file at install time.) There's
no way to address the third point other than providing a
Re: [Rd] ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]
On 10/6/2008 11:00 AM, Simon Urbanek wrote:
On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a
file anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview page,
so:
?anRpackage
gives new users of a certain package a pointer where to start
reading.
This is similar for packages which have the same name as their
main workhorse function, e.g. zoo or nlme, but there are many
packages which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-
package, e.g. `utils-package' for the utils package, when package?
pkgname will open that help page. If a topic named pkgname does
not exist in another Rd file, it is helpful to use this as an
additional \alias."
My question: what speaks against making this sentence more
pronounced and why not NOTE-ing a missing package alias in the
package check?
Not everybody likes the idea of the overview man page, so when I
wrote that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course, obvious
advantages. Almost all scientific papers start with an abstract,
why not requesting one for software packages, at least for new ones?
We already require one in the DESCRIPTION file for all packages,
which you can see with
library(help=packagename)
Yes, but this is way too long to write - could we add a fall-back so
that if ?foo alias doesn't exist but package foo does then ?foo is
equivalent to help(package="foo")? At least for the way I use help it
would help a lot...
?foo and help("foo") return an object with a class whose print method
displays the help. So doing this would require a new class with a
different print method. It seems cleaner to me to ask people to provide
the ?foo topic within the existing system, as we do now, or to produce
the topic automatically at install time, so it works within the existing
system.
Duncan Murdoch
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Bug with message if there is no documentation; R2.8alpha Win32 (PR#13131)
On Mon, 6 Oct 2008, [EMAIL PROTECTED] wrote:
In the latest R 2.8 alpha for Win32, if either of the commands are typed:
help("erfc")
.. or ..
?erfc
the result is:
No documentation for 'erfc' in specified packages and libraries:
you could try '??erfc'
This should be: 'help.search("erfc")', as shown in R 2.7.2
Why do you think so? From the NEWS
o ??topic now does help.search("topic"); variations such as
??pkg::topic or field??topic are also supported.
Apologies if this has already been submitted/fixed.
Please ask on R-devel about unreleased versions of R: from
http://cran.r-project.org/bin/windows/base/rtest.html
'Please don't report bugs in this version through the usual R bug
reporting system, please report them on the r-devel mailing list.'
-Mike
--please do not edit the information below--
Version:
platform = i386-pc-mingw32
arch = i386
os = mingw32
system = i386, mingw32
status = alpha
major = 2
minor = 8.0
year = 2008
month = 10
day = 03
svn rev = 46594
language = R
version.string = R version 2.8.0 alpha (2008-10-03 r46594)
Windows XP (build 2600) Service Pack 3
Locale:
LC_COLLATE=English_Canada.1252;LC_CTYPE=English_Canada.1252;LC_MONETARY=English_Canada.1252;LC_NUMERIC=C;LC_TIME=English_Canada.1252
Search Path:
.GlobalEnv, package:stats, package:graphics, package:grDevices,
package:utils, package:datasets, package:methods, Autoloads, package:base
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
--
Brian D. Ripley, [EMAIL PROTECTED]
Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
University of Oxford, Tel: +44 1865 272861 (self)
1 South Parks Road, +44 1865 272866 (PA)
Oxford OX1 3TG, UKFax: +44 1865 272595
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] ?foo to fall back to help(package="foo") [Was: why is \alias{anRpackage} not mandatory?]
On Oct 6, 2008, at 11:18 , Duncan Murdoch wrote:
On 10/6/2008 11:00 AM, Simon Urbanek wrote:
On Oct 6, 2008, at 8:47 , Duncan Murdoch wrote:
On 06/10/2008 8:06 AM, Thomas Petzoldt wrote:
Duncan Murdoch wrote:
Thomas Petzoldt wrote:
Dear R developers,
if one uses package.skeleton() to create a new package, then a
file anRpackage.Rd with the following entries is prepared:
\name{anRpackage-package}
\alias{anRpackage-package}
\alias{anRpackage}
\docType{package}
Packages created this way have a definite entry or overview
page, so:
?anRpackage
gives new users of a certain package a pointer where to start
reading.
This is similar for packages which have the same name as their
main workhorse function, e.g. zoo or nlme, but there are many
packages which don't have an \alias{anRpackage}.
"Writing R Extensions", sec. 2.1.4 says:
"Packages may have an overview man page with an \alias pkgname-
package, e.g. `utils-package' for the utils package, when
package? pkgname will open that help page. If a topic named
pkgname does not exist in another Rd file, it is helpful to
use this as an additional \alias."
My question: what speaks against making this sentence more
pronounced and why not NOTE-ing a missing package alias in the
package check?
Not everybody likes the idea of the overview man page, so when
I wrote that I left it weak. Some of the disadvantages:
You speak about the disadvantages but there are, of course,
obvious advantages. Almost all scientific papers start with an
abstract, why not requesting one for software packages, at least
for new ones?
We already require one in the DESCRIPTION file for all packages,
which you can see with
library(help=packagename)
Yes, but this is way too long to write - could we add a fall-back
so that if ?foo alias doesn't exist but package foo does then ?foo
is equivalent to help(package="foo")? At least for the way I use
help it would help a lot...
?foo and help("foo") return an object with a class whose print
method displays the help. So doing this would require a new class
with a different print method. It seems cleaner to me to ask people
to provide the ?foo topic within the existing system, as we do now,
... which doesn't seem to work - that's why we have the discussion ;).
or to produce the topic automatically at install time, so it works
within the existing system.
... which if ok with me - that would fit the bill ...
Thanks,
Simon
__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] splinefun gives incorrect derivs when extrapolating to the left (PR#13132)
This is a low priority bug that has been around for a while, but I came acr= oss it again while alpha testing 2.8. The resulting function for splinefun gives incorrect deriv values when x is= less than the smallest x-value used to create the function (at least in on= e circumstance), but does the correct thing for x greater than the largest = x-value. Here is an example: > x <- 1:10 > y <- sin(x) > > splfun <- splinefun(x,y, method=3D'natural') > > # these should be linear (and are) > splfun( seq(0,1, 0.1) ) [1] 0.5682923 0.5956102 0.6229280 0.6502459 0.6775638 0.7048816 0.7321995 [8] 0.7595174 0.7868352 0.8141531 0.8414710 > > # these should all be the same > splfun( seq(0,1, 0.1), deriv=3D1 ) [1] -0.34287807 -0.22582729 -0.12109764 -0.02868912 0.05139826 0.1191645= 1 [7] 0.17460962 0.21773359 0.24853643 0.26701813 0.27317870 > > # these should all be 0 > splfun( seq(0,1, 0.1), deriv=3D2 ) [1] 1.2321135 1.1089022 0.9856908 0.8624795 0.7392681 0.6160568 0.4928454 [8] 0.3696341 0.2464227 0.1232114 0.000 > splfun( seq(0,1, 0.1), deriv=3D3 ) [1] -1.232114 -1.232114 -1.232114 -1.232114 -1.232114 -1.232114 -1.232114 [8] -1.232114 -1.232114 -1.232114 -1.232114 > > > # everything works like it should on the right end > splfun( seq(10,11, 0.1) ) [1] -0.5440211 -0.6444546 -0.7448881 -0.8453215 -0.9457550 -1.0461885 [7] -1.1466220 -1.2470554 -1.3474889 -1.4479224 -1.5483559 > splfun( seq(10,11, 0.1), deriv=3D1 ) [1] -1.004335 -1.004335 -1.004335 -1.004335 -1.004335 -1.004335 -1.004335 [8] -1.004335 -1.004335 -1.004335 -1.004335 > splfun( seq(10,11, 0.1), deriv=3D2 ) [1] 0 0 0 0 0 0 0 0 0 0 0 > splfun( seq(10,11, 0.1), deriv=3D3 ) [1] 0 0 0 0 0 0 0 0 0 0 0 > --please do not edit the information below-- Version: platform =3D i386-pc-mingw32 arch =3D i386 os =3D mingw32 system =3D i386, mingw32 status =3D alpha major =3D 2 minor =3D 8.0 year =3D 2008 month =3D 10 day =3D 01 svn rev =3D 46589 language =3D R version.string =3D R version 2.8.0 alpha (2008-10-01 r46589) Windows XP (build 2600) Service Pack 3 Locale: LC_COLLATE=3DEnglish_United States.1252;LC_CTYPE=3DEnglish_United States.12= 52;LC_MONETARY=3DEnglish_United States.1252;LC_NUMERIC=3DC;LC_TIME=3DEnglis= h_United States.1252 Search Path: .GlobalEnv, package:stats, package:graphics, package:grDevices, package:ut= ils, package:datasets, package:methods, Autoloads, package:base -- Gregory (Greg) L. Snow Ph.D. Statistical Data Center Intermountain Healthcare [EMAIL PROTECTED] 801.408.8111 __ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
