Re: [Rd] Suggestion: help()
The reason I like .Rd files is that I can run the examples easily and, as Martin points out, one does not need to learn a new syntax. How about adding the following to R-exts: "We encourage the package developer to include a file named foo.package.Rd in the "man" directory, to provide a terse overview of the foo package. This Rd file is intended to be the first port of call for a new user of the package, and should provide (or point to) working examples of the package's functionality. It may also provide details or rationale for the package's structure, if non-standard; and perhaps document other features of the package that might escape a new user's notice. See package foo for an example" and package.skeleton() could be modified to write a skeleton version of foo.package.Rd and put it in the man directory. best wishes everyone rksh Duncan writes: My proposal (modified following the suggestions I've heard so far) is as follows: - to check that a couple of help topic aliases exist (.package and ) - to recommend that .package contain general information about the package, and that be an alias for it, if it isn't used for some other purpose. - to write promptPackage() to help create an initial version of .package.Rd. It can get some information from the DESCRIPTION file; perhaps it could go looking for a vignette, or the INDEX, or - to modify the other help system tools to make use of this (e.g. the package: heading on a page would become a link to the .package alias, etc.) Martin: And as much as I do like (and read) the vignettes that are available, I also do agree that writing one other *.Rd file is easier for many new package authors than to write a vignette -- the package author already had to learn *.Rd syntax anyway -- and it's nice to be able to produce something where hyperlinks to the other existing reference material (ie. help pages) just works out of the box. Duncan again: Currently R has 3 types of help: the .Rd files in the man directory (which are converted into plain text, HTML, compiled HTML, LaTex, DVI, PDF, etc), the vignettes, and unstructured files in inst/doc. We currently require .Rd files for every function and data object. Adding a requirement to also document the package that way is not all that much of a burden, and will automatically give all those output formats I listed above. It will help to solve the often-complained about problem of packages that contain no overview at all. (Requiring a vignette and giving a way to display it would also do that, but I think requiring a .Rd file is less of a burden, and for anyone who has gone to the trouble of creating a vignette, gives a natural place for a link to it. Vignettes aren't used as much as they should be, because they are hidden away where users don't see them.) -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Suggestion: help()
My 0.02: I use Misc.Rd for the purpose that Duncan suggests. I put things like details and rationale for package organization, pointers to the most important function(s) in the package, and perhaps function descriptors for ubiquitous functions that don't warrant their own helppage, but need documentation [in the case of gsl, this would be strictify() and process.args(), which every user needs to know]. It would be *great* to be required to put in "package.gsl.R" (or should that be "gsl.package.Rd"?) for this purpose. Then maybe R CMD check could check for its presence and throw a wobbly if it isn't there. Some packages have so much material that it's difficult to know where the "meat" of the functionality lies, and Duncan's suggestion would help greatly in these circumstances. best wishes rksh On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote: Kurt Hornik wrote: Henrik Bengtsson writes: Hi, I would like to suggest a standard where all packages provide an Rd page with the same name (or aliased) as the name of package so that help() or ? is always here. This especially of interest to large packages with a large package index. This page could explain the package in general and gives some hints on how to start - not like extensive vignettes, but just to get started, e.g. list the "most important" functions. This page could typically contain information that is in the DESCRIPTION file (which contains valuable information hardly every accessed by a general user), such as who is the maintainer, how to report bugs and so on. I think this is a good idea. One minor problem is that for some packages that topic name is already in use for a function (e.g. boot). For that reason, I'd suggest that there *also* be an alias called "package.", and the topic should link to it. How would this be different from the results of help(package = ) ? 1. It would work with ?, like other help topics. 2. It would give an overview. It's possible to do that in DESCRIPTION or INDEX, but you don't get the same style as for other help files (e.g. no links to other topics, at least in Windows). We should work out what the topic headings should be and extend package.skeleton() and prompt() to write a bare-bones file that suggests the questions that need to be answered in the file. The headings I'd suggest are: \name \title \alias \description (longer than the typical entry in the DESCRIPTION file) \details (Should give a short guide to the main functions, should point out the existence of external documentation like vignettes, etc.) \author (could also describe maintainer, if different) \references \seealso (Should give references to related packages) \examples \keywords There is some duplication of material from DESCRIPTION, but usually this should be longer and more reader-friendly than that file. I'd be happy to write the description of this in R Extensions, and write the changes to prompt(), if we have agreement that this file should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for it. (I think the check should just be for existence of aliases and package., and could perhaps just give a warning in 2.2.x.) Duncan Murdoch ______ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel -- Robin Hankin Uncertainty Analyst National Oceanography Centre, Southampton European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] typesetting a matrix
Hi
in a .Rd file, in a \deqn{} environment, how do I typeset a matrix in
latex?
I have
\deqn{\left(\begin{bmatrix}a&b\\c&d\end{bmatrix}\right)}{omitted}
but this doesn't give me the 2-by-2 matrix desired.
Is there a manpage somewhere with a matrix that I could adapt?
--
Robin Hankin
Uncertainty Analyst
National Oceanography Centre, Southampton
European Way, Southampton SO14 3ZH, UK
tel 023-8059-7743
__
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Re: [Rd] Trigonometric functions (PR#7728)
On Mar 15, 2005, at 11:26 pm, Thomas Lumley wrote: On Wed, 16 Mar 2005, Peter Kleiweg wrote: Thomas Lumley schreef op de 15e dag van de lentemaand van het jaar 2005: x<-sqrt(2) asin(x^2-1) result in: NaN The way I would deal with this would be to force asin() to work in complex mode: > x <- sqrt(2) > asin(x^2-1+0i) [1] 1.570796+2.980232e-08i > (the error is large because the derivative of arcsin is infinite at x=1). -- Robin Hankin Uncertainty Analyst Southampton Oceanography Centre European Way, Southampton SO14 3ZH, UK tel 023-8059-7743 __ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
[Rd] data() in data/*.R files
Hi I'm having difficulty making a package pass R CMD check. I need to read in a dataset from another package, modify it, and have the modified object available in the first package. help(require) says: The source code for a package that requires one or more other packages should have a call to 'require', preferably near the beginning of the source, and of course before any code that uses functions, classes or methods from the other package. and 200update.txt points out that the data/*.R files must be self sufficient, suggesting "require(pkg, quietly=TRUE, save=FALSE)" if needed. My .R file in the data subdirectory looks like this: require(calibrator, quietly=TRUE, save=FALSE) data(expert.estimates, package="calibrator") expert.estimates.modified <- some.function(expert.estimates) But if I do this, R CMD check says Error in eval(expr, envir, enclos) : couldn't find function "data" Execution halted ERROR: installing package indices failed ERROR Installation failed. [the package passes R CMD check if I cut-and-paste a dput and assign expert.estimates.modified directly, and dispense with the data() statement]. How do I load a dataset from another package in a .R file, and use it? -- Robin Hankin Uncertainty Analyst Southampton Oceanography Centre SO14 3ZH tel +44(0)23-8059-7743 [EMAIL PROTECTED] (edit in obvious way; spam precaution) [[alternative HTML version deleted]] __ [EMAIL PROTECTED] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
